Update 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.
You should keep your C# API client up to date to benefit from improvements and bug fixes.
The C# API client follows Semantic Versioning.
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
1
dotnet add package Algolia.Search
With the NuGet Package Manager console
1
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.
1
2
3
4
5
6
7
// 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 methodsHosts
to set custom hosts
You can also add entries in the DefaultHeaders
dictionary to set some HTTP Headers for every request.
Example:
1
2
3
4
5
6
7
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.
1
2
3
4
5
6
// 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:
1
2
3
4
// 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 |