Quickstart with the .NET API Client

Supported platforms

The API client supports:

• .NET Standard versions 1.3 to 2.1
• .NET Core versions 1.0 to 3.1
• .NET Framework versions 4.6 to 4.8

Install

Install via the .NET CLI

If you already initialized a .NET project with the CLI, run:

1
dotnet add package Algolia.Search

You can initialize a new .NET project with:

1
dotnet new <TYPE>

Replace <TYPE> with the type of application you want to build. For example, with dotnet new console you can create a new command-line application.

Install via NuGet

1
Install-Package Algolia.Search

Download the package

You can download the package from NuGet.org.

POCO, Types and Json.NET

The API client is using Json.NET as serializer.

The Client is meant to be used with POCOs and Types to improve type safety and developer experience. You can directly index your POCOs if they follow the .NET naming convention for class and properties:

• PascalCase for property names
• PascalCase for class name

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public class Contact
{
  public string ObjectID { get; set; }
  public string Name { get; set; }
  public int Age { get; set; }
}

SearchClient client = new SearchClient("YourApplicationID", "YourAdminAPIKey");
SearchIndex index = client.InitIndex("contact");

IEnumerable<Contact> contacts; // Fetch from DB or a Json file
index.SaveObjects(contacts);

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

// Search one typed Contact
var result = index.Search<Contact>(new Query("contact"));

If you can’t follow the convention, you can still override the naming strategy with the following attribute [JsonProperty(PropertyName = "propertyName")]

However, it’s still possible to use JObject to add and retrieve records.

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, Settings, etc., are now typed. You can enjoy the completion of your favorite IDE while developing with the library.

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 fully type the hit object in SearchResponse<T> (i.e not using object or JObject) and want to access properties that can be sent by the engine in the hits attribute, you must add these properties to your object. For example, when you want to retrieve the _rankingInfo with your search, you must define a property for it or it will be ignored by the serializer.

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 & Synchronous Methods

The API client provides both Async and Sync methods for every API endpoint. Asynchronous methods are suffixed with the Async keyword. You can use any of them depending on your needs.

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

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

HttpClient Injection

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

The HttpClient is wrapped in an interface: IHttpRequester. If you wish to use another HttpClient, you can inject it through the constructor while instantiating a SearchClient, AnalyticsClient, and InsightsClient.

Example:

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

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

Multithreading

The client is designed to be thread-safe. You can use SearchClient, AnalyticsClient, and InsightsClient in a multithreaded environment.

Cross-Platform

As the API client is following .NET Standard, it can be used on Windows, Linux, or MacOS. The library is continuously tested in all three environments. If you want more information about .NET Standard, you can visit the official page.

Quickstart

If you want to get started quickly with self-contained code examples that you can run directly from your code editor, you can explore the quickstart samples on GitHub.

In the following sections, you can learn how to index and search objects in 30 seconds.

Initialize the client

To start, you need to initialize the client. To do this, you need your Application ID and API Key. You can find both on your Algolia account.

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

The API key displayed here is your Admin API key. To maintain security, never use your Admin API key on your front end, nor share it with anyone. In your front end, use the search-only API key or any other key that has search-only rights.

Push data

Without any prior configuration, you can start indexing 500 contacts in the contacts index using the following code:

1
2
3
4
5
6
7
8
9
10
SearchIndex index = client.InitIndex("contacts");

using (StreamReader re = File.OpenText("contacts.json"))
using (JsonTextReader reader = new JsonTextReader(re))
{
    JArray batch = JArray.Load(reader);
    index.SaveObjects(batch, autoGenerateObjectId: true);
    // Asynchronous
    // index.SaveObjectsAsync(batch, autoGenerateObjectId: true);
}

Configure

You can customize settings to fine tune the search behavior. For example, you can add a custom ranking by number of followers to further enhance the built-in relevance:

1
2
3
4
5
6
7
8
9
IndexSettings settings = new IndexSettings
{
    CustomRanking = new List<string> { "desc(followers)"},
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

You can also configure the list of attributes you want to index by order of importance (most important first).

Algolia is designed to suggest results as you type, which means you’ll generally search by prefix. In this case, the order of attributes is crucial to decide which hit is the best.

1
2
3
4
5
6
7
8
9
10
11
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string>
        {"lastname", "firstname", "company", "email", "city"}
};

// Synchronous
index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

Search

You can now search for contacts by firstname, lastname, company, etc. (even with typos):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Search for a first name
index.Search<Contact>(new Query("jimmie"));
// Asynchronous
await index.SearchAsync<Contact>(new Query("jimmie"));

// Search for a first name with typo
index.Search<Contact>(new Query("jimie"));
// Asynchronous
await index.SearchAsync<Contact>(new Query("jimie"));

// Search for a company
index.Search<Contact>(new Query("california paint"));
// Asynchronous
await index.SearchAsync<Contact>(new Query("california paint"));

// Search for a first name and a company
index.Search<Contact>(new Query("jimmie paint"));
// Asynchronous
await index.SearchAsync<Contact>(new Query("jimmie paint"));

Search UI

If you’re building a web application, you may be interested in using one of Algolias front-end search UI libraries.

The following example shows how to quickly build a front-end search using InstantSearch.js

index.html

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
<!doctype html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.4.5/themes/satellite-min.css" integrity="sha256-TehzF/2QvNKhGQrrNpoOb2Ck4iGZ1J/DI4pkd2oUsBc=" crossorigin="anonymous">
</head>
<body>
  <header>
    <div id="search-box"></div>
  </header>

  <main>
      <div id="hits"></div>
      <div id="pagination"></div>
  </main>

  <script type="text/html" id="hit-template">
    <div class="hit">
      <p class="hit-name">
        {{#helpers.highlight}}{ "attribute": "firstname" }{{/helpers.highlight}}
        {{#helpers.highlight}}{ "attribute": "lastname" }{{/helpers.highlight}}
      </p>
    </div>
  </script>

  <script src="https://cdn.jsdelivr.net/npm/algoliasearch@4.5.1/dist/algoliasearch-lite.umd.js" integrity="sha256-EXPXz4W6pQgfYY3yTpnDa3OH8/EPn16ciVsPQ/ypsjk=" crossorigin="anonymous"></script>
  <script src="https://cdn.jsdelivr.net/npm/instantsearch.js@4.8.3/dist/instantsearch.production.min.js" integrity="sha256-LAGhRRdtVoD6RLo2qDQsU2mp+XVSciKRC8XPOBWmofM=" crossorigin="anonymous"></script>
  <script src="app.js"></script>
</body>

app.js

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
// Replace with your own values
const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey' // search only API key, not admin API key
);

const search = instantsearch({
  indexName: 'contacts',
  searchClient,
  routing: true,
});

search.addWidgets([
  instantsearch.widgets.configure({
    hitsPerPage: 10,
  })
]);

search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#search-box',
    placeholder: 'Search for contacts',
  })
]);

search.addWidgets([
  instantsearch.widgets.hits({
    container: '#hits',
    templates: {
      item: document.getElementById('hit-template').innerHTML,
      empty: `We didn't find any results for the search <em>"{{query}}"</em>`,
    },
  })
]);

search.start();