Initialize the C# API client

This is documentation for v6 of the C# API clients, which is not the latest version. To see the documentation for the latest version, see C# v7.

Before you can index your data or search your Algolia indices, you must initialize a search client with your application ID and API key. You can find both in your Algolia account.

Initialize the search client

The search client handles authentication and lets you manage your indices, for example, add data to them, or search them.

1
2
SearchClient client = new SearchClient("YourApplicationID", "YourWriteAPIKey");
SearchIndex index = client.InitIndex("your_index_name");

Replace your_index_name with the name of the index you want to use. You can find your existing indices in the Algolia dashboard or using the listIndices method. If the index doesn’t exist, a new, empty index is created locally. It’s created on Algolia’s servers only if you add records to the index.

Don’t use sensitive or personally identifiable information as your index name, including usernames, IDs, or email addresses. Index names are publicly shared.

Operations that are scoped to your Algolia application through the client are:

Operations scoped to an index are:

The Recommend, Personalization, Insights, and A/B testing APIs come with their own clients:

Usage notes

Serialization

The API client uses Json.NET as the serializer for your POCOs. You can index your POCOs directly if they follow the .NET naming convention.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
using Algolia.Search.Clients;
using Algolia.Search.Models.Search;
using System.Collections.Generic;

public class Contact
{
    public string ObjectID { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

public class AlgoliaIntegration
{
    private SearchClient client;
    private SearchIndex index;

    public AlgoliaIntegrationService(string applicationId, string apiKey)
    {
        client = new SearchClient(applicationId, apiKey);
        index = client.InitIndex("contact");
    }

    public void SaveContacts(IEnumerable<Contact> contacts)
    {
        // Ensure that contacts is not null and has data
        if (contacts != null)
        {
            index.SaveObjects(contacts);
        }
    }

    public Contact GetContact(string objectId)
    {
        try
        {
            Contact contact = index.GetObject<Contact>(objectId);
            return contact;
        }
        catch (Algolia.Search.Exceptions.AlgoliaApiException ex)
        {
            // Handle exceptions from the Algolia API here
            // Log the exception message: ex.Message
            return null;
        }
    }

    public IEnumerable<Contact> SearchForContact(string queryText)
    {
        try
        {
            var result = index.Search<Contact>(new Query(queryText));
            return result.Hits;
        }
        catch (Algolia.Search.Exceptions.AlgoliaApiException ex)
        {
            // Handle exceptions from the Algolia API here
            // Log the exception message: ex.Message
            return new List<Contact>();
        }
    }
}

// Usage:
// AlgoliaIntegration algoliaService = new AlgoliaIntegration("YourApplicationID", "YourWriteAPIKey");
// IEnumerable<Contact> contacts = ... // Fetch from DB or a Json file
// algoliaService.SaveContacts(contacts);
// Contact contact = algoliaService.GetContact("myId");
// IEnumerable<Contact> searchResult = algoliaService.SearchForContact("contact");

You can override the naming strategy with the following attribute: [JsonProperty(PropertyName = "propertyName")]

You can also add and retrieve records via JObject:

1
2
3
4
5
6
7
8
9
using (StreamReader re = File.OpenText("contacts.json"))
using (JsonTextReader reader = new JsonTextReader(re))
{
   JArray batch = JArray.Load(reader);
   index.SaveObjects(batch).Wait();
}

// Retrieve one JObject Contact
JObject contact = index.GetObject<JObject>("myId");

Algolia objects such as Rule, Synonym, or Settings are now typed.

Example with the Settings class:

1
2
3
4
5
6
7
8
9
10
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string> {"attribute1", "attribute2"},
    AttributesForFaceting = new List<string> {"filterOnly(attribute2)"},
    UnretrievableAttributes = new List<string> {"attribute1", "attribute2"},
    AttributesToRetrieve = new List<string> {"attribute3", "attribute4"}
    // etc.
};

index.SetSettings(settings);

If you want to access all properties of the SearchResponse object, you must add these properties to your class. For example, to get the _rankingInfo attribute with your search:

1
2
3
4
5
6
7
8
public class Contact
{
  public string ObjectID { get; set; }
  public string Name { get; set; }
  public int Age { get; set; }

  public object _rankingInfo { get; set; }
}

Asynchronous and synchronous methods

The API client provides both synchronous and asynchronous methods for every API endpoint. Asynchronous methods are suffixed with the Async keyword.

1
2
3
4
5
// Synchronous
Contact res = index.GetObject<Contact>("myId");

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId");

Using a custom HTTP client

The API client uses the built-in HttpClient of the .NET Framework.

The HttpClient is wrapped in an interface: IHttpRequester. If you want to use a custom HttpClient, you can pass it to the constructors of If you wish to use another HttpClient, you can inject it through the constructor when instantiating a SearchClient, AnalyticsClient, or InsightsClient.

Example:

1
2
3
4
5
6
IHttpRequester myCustomHttpClient = new MyCustomHttpClient();

SearchClient client = new SearchClient(
    new SearchConfig("YourApplicationID", "YourWriteAPIKey"),
    myCustomHttpClient
);

Thread safety

The API client is thread-safe. You can use SearchClient, AnalyticsClient, and InsightsClient in a multi-threaded environment.

Did you find this page helpful?