Upgrade the C# API client to version 6

Keep your C# API client up to date to benefit from improvements and bug fixes.

This page documents an earlier version of the API client. For the latest version, see Upgrade.

Keep your C# API client up to date to benefit from improvements and bug fixes.

The C# API client follows semantic versioning.

Upgrade to version 6

The design of version 6 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.

C#

// Before
AlgoliaClient client = new AlgoliaClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
Index index = client.InitIndex("ALGOLIA_INDEX_NAME");

// After
SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
SearchIndex index = client.InitIndex("ALGOLIA_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:

C#

SearchConfig config = new SearchConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
{
  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.

C#

// Before
AlgoliaClient client = new AlgoliaClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
Analytics analytics = new Analytics(client);

// After
AnalyticsClient analytics = new AnalyticsClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

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:

C#

// 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

AlgoliaClient/SearchClient

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

AlgoliaClient/AnalyticsClient

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

Index/SearchIndex

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