API client / Getting started / Update

Update the .NET API client

You should keep your .NET API client up to date to benefit from improvements and bug fixes. Algolia’s Service Level Agreement only applies to the latest version of the API client.

The .NET API client follows Semantic Versioning. You can check what the latest version of the API client is on the GitHub release page.

Upgrade to v6

The design of the latest version of the .NET client is almost the same as the previous version to make upgrading as smooth as possible. The names of the client and index classes changed to SearchClient and SearchIndex with similar method names.

This new version is compatible with the same .NET versions as before: from .NET 4.5 to .NET Core 2.2.

Upgrade the library

With the .NET command-line tool

dotnet add package Algolia.Search

With the NuGet Package Manager console

Update-Package Algolia.Search

With the NuGet website

Download the package on NuGet.org.

Client instantiation

Replace the instantiation of the client as shown below.

// Before
AlgoliaClient client = new AlgoliaClient("YourApplicationID", "YourWriteAPIKey");
Index index = client.InitIndex("your_index_name");

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

Configure the client

You can instantiate all clients with configuration objects. This is useful to change how a client behaves. You can configure:

  • BatchSize to customize the size of batch for save methods
  • Hosts to set custom hosts

You can also add entries in the DefaultHeaders dictionary to set some HTTP Headers for every request. Example:

SearchConfig config = new SearchConfig("YourApplicationID", "YourWriteAPIKey")
  BatchSize = 2000,
config.DefaultHeaders.Add("MyCustomHeaderKey", "MyCustomHeaderValue");

SearchClient client = new SearchClient(config);

Analytics instantiation

Similarly, you need to update the way you initialize the Analytics client.

// Before
AlgoliaClient client = new AlgoliaClient("YourApplicationID", "YourWriteAPIKey");
Analytics analytics = new Analytics(client);

// After
AnalyticsClient analytics = new AnalyticsClient("YourApplicationID", "YourWriteAPIKey");

New methods

The client has some new methods to help implement commonly used features. These features were always available but required either a deeper understanding or custom code.

  • CopySettings: lets you copy settings between indices.
  • CopySynonyms: lets you copy synonyms between indices.
  • CopyRules: lets you copy rules between indices.
  • ReplaceAllObjects: lets you add new objects to an index and remove all existing ones, atomically.
  • ReplaceAllSynonyms: lets you add new synonyms to an index and remove all existing ones, atomically.
  • ReplaceAllRules: lets you add new Rules to an index and remove all existing ones, atomically.
  • AccountClient.CopyIndex: lets you copy an index between Algolia applications.
  • CustomRequest: lets you request the Algolia API with custom parameters, URLs, and headers.

Breaking changes

JObject and types

The v6 of the client, in contrast to the previous one, is typed for every method. This implies a breaking change on most methods. You can still save and retrieve your records with JObject. For Settings, Rules, APIkeys, and Synonyms, you need to convert your JObject to a class.

How to export JObject to new types

Example with settings:

// Your old JObject
JObject oldObject = JObject.Parse("{\"customRanking\":[\"desc(population)\", \"asc(name)\"], \"attributesToIndex\":[\"attr1\", \"attr2\"],\"numericAttributesToIndex\": [\"attr1\", \"attr2\"]}");

IndexSettings settings = oldObject.ToObject<IndexSettings>();

This snippet also works for all other classes in the client, such as Rules, APIkeys, and Synonyms.

List of method changes

Before After
SetSettings(settings, null, true) SetSettings(settings, forwardToReplicas: true)
BatchSynonyms(synonyms, true, false) SaveSynonyms(synonyms, forwardToReplicas: true)
BatchSynonyms(synonyms, true, true) ReplaceAllSynonyms(synonyms, forwardToReplicas: true)
BatchSynonyms(synonyms, false, false) SaveSynonyms(synonyms)
BatchSynonyms(synonyms, false, true) ReplaceAllSynonyms(synonyms)
AddObjects(objectsWithObjectId) SaveObjects(objectsWithObjectId)
AddObjects(objectsWithoutObjectId) SaveObjects(objectsWithoutObjectId, autoGenerateObjectId: true)

List of return type changes


Method name New return type Old return type
InitIndex SearchIndex Index
MultipleGetObjects MultipleGetObjectsResponse< T > JObject
MultipleQueries MultipleQueriesResponse< T > JObject
MultipleBatch MultipleIndexBatchIndexingResponse JObject
ListIndices ListIndicesResponse JObject
DeleteIndex DeleteResponse JObject
ListApiKeys ListApiKeysResponse JObject
GetApiKey ApiKey JObject
AddApiKey AddApiKeyResponse JObject
UpdateApiKey UpdateApiKeyResponse JObject
DeleteApiKey DeleteApiKeyResponse JObject
ListClusters IEnumerable< ClustersResponse > JObject
SearchUserIDs SearchResponse< UserIdResponse > JObject
ListUserIds ListUserIdsResponse JObject
GetUserId UserIdResponse JObject
GetTopUserId TopUserIdResponse JObject
AssignUserId AssignUserIdResponse JObject
RemoveUserId RemoveUserIdResponse JObject
GetLogs LogResponse JObject
CopySettings CopyToResponse JObject
CopyRules CopyToResponse JObject
CopySynonyms CopyToResponse JObject
CopyIndex CopyToResponse JObject
MoveIndex MoveIndexResponse JObject


Method name New return type Old return type
GetABTest ABTest JObject
GetABTests ABTestsReponse JObject
AddABTest AddABTestResponse JObject
StopABTest StopABTestResponse JObject
DeleteABTest DeleteABTestResponse JObject


Method name New return type Old return type
PartialUpdateObject UpdateObjectResponse JObject
PartialUpdateObjects BatchIndexingResponse JObject
SaveObject BatchIndexingResponse JObject
SaveObjects BatchIndexingResponse JObject
ReplaceAllObjects MultiResponse JObject
Batch BatchResponse JObject
Batch BatchResponse JObject
DeleteObject DeleteResponse JObject
DeleteObjects BatchIndexingResponse JObject
DeleteBy DeleteResponse JObject
ClearObjects DeleteResponse JObject
Search SearchResponse< T > JObject
SearchForFacetValue SearchForFacetResponse JObject
GetObject T JObject
GetObjects IEnumerable< T > JObject
Browse IndexIterator< T > JObject
BrowseFrom BrowseIndexResponse< T > JObject
GetRule Rule JObject
SearchRule SearchResponse< Rule > JObject
SaveRule SaveRuleResponse JObject
SaveRules BatchResponse JObject
ReplaceAllRules BatchResponse JObject
DeleteRule DeleteResponse JObject
ClearRules DeleteResponse JObject
GetSettings IndexSettings JObject
SetSettings SetSettingsResponse JObject
SearchSynonyms SearchResponse< Synonym > JObject
GetSynonym Synonym JObject
SaveSynonyms SaveSynonymResponse JObject
ReplaceAllSynonyms SaveSynonymResponse JObject
SaveSynonym SaveSynonymResponse JObject
DeleteSynonym DeleteResponse JObject
ClearSynonyms ClearSynonymsResponse JObject
CopyTo CopyToResponse JObject
MoveFrom MoveIndexResponse JObject
WaitTask Void JObject
GetTask TaskStatusResponse JObject
Did you find this page helpful?