.NET API Client V6 is released 🎉

release
dotnet
api-clients

#1

Hi everyone :wave:!

A couple of months ago, we announced the release of a new major version for the PHP client.

Today we’re proud to announce that the V6 of the C# API client is now out :rocket:
It implements our common specs as well, and it’s coming with a lot of sweet additions :candy:

Check them out!

:books: Following .NET Standard

The .NET framework has changed a lot those past few years, and so does our library! Our library is targeting the .NET Standard specification which means that our API Client is running on all .NET implementations!

Thus the library is compatible with:

  • .NET Standard 1.3 to .NET Standard 2.0,
  • .NET Core 1.0 to .NET Core 2.2,
  • .NET Framework 4.5 to .NET Framework 4.7.1

:keyboard: Every request and response are now typed

To improve the developer experience of the library we decided to type every response and every request.

That means :

  • You can’t create an invalid Json anymore, the schema is ensured by the types.
  • You will have the IDE completion on every class, don’t need to go back anymore to the doc to find a property anymore!
  • You will find the documentation of each property in the class through IDE completion.

:memo: POCO, types and new serialization strategy

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

To achieve this, we introduced a new strategy for the serialization. Your standard C# POCO will be serialized by default in camelCased JSON (which is the convention for the API and JSON).
However, if you don’t want to follow this default behavior you can still override it with [JsonObject(NamingStrategyType = typeof(PascalCaseNamingStrategy))] in your classes.

:spider_web: ASP.NET

If you are an ASP.NET user we wrote a guide to help you using the library with an MVC or WebAPI application!

:gear: Thread Safe clients

The Library is designed to be thread-safe. Every Client class in the library, such as SearchClient, AnalyticsClient, and InsightsClient can be used in a multithreaded environment.

:stopwatch: Async 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.

// Synchronous
Contact res = index.GetObject<Contact>("myId");

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

:syringe: Injectable HttpClient

Our library is using the default HTTP Client provided by the .NET Framework. If you don’t want to use it, you can inject your own HTTP Client into the library.
You have to implement the IHttpRequester interface. Good news is, even if you inject another Http client, the retry strategy will still work!

:bug: New debugging tools

We added a logger that trace in debug mode all the payload received and sent to the API.
To make it work you have to set the ALGOLIA_DEBUG env variable to true and run the tests in debug mode!

:beetle: Exceptions

A bunch of new Exceptions have been introduced. The main reason is to help the developers controlling the flow of their software.

  • AlgoliaApiException to catch exception from the API. You have the API error message and the HttpCode in it.
  • AlgoliaUnreachableHostException is thrown when all hosts are unreachable.
  • AlgoliaException is thrown when you pass invalid arguments to methods.

:stopwatch: An easy way to wait for any operation to be complete

As easy as:

var response = index.SaveObjects(contacts).Wait();

The beauty here is that you can wait not only for operations that return a taskId; such as indexing objects, but also operations that don’t, like keys. You can wait on every class that implements the IAlgoliaWaitableResponse interface. For example:

client.DeleteApiKey(“ApiKey”).Wait();

The cool thing is, you know that a method is waitable directly throught the IDE completion, thing you couldn’t have done before!

:robot: All methods related to indexing can take an iterator and automatically create batches.

By automatically creating batches, we ensure we optimize the number of network calls for our users without having them to think about it. For very specific use-cases, the batch size can be changed with the AlgoliaConfiguration when creating a client.

Example :

SearchConfig config = new SearchConfig("YourApplicationId", "YourAdminAPIKey")
{
  BatchSize = 2000
};

SearchClient client = new SearchClient(config);

:muscle: News methods to bring the DX one step further

A bunch of new helpers where added that aren’t just a simple mapping to an API endpoint method.

There are some use cases that require a complex and long strategy to be implemented. For instance, to reindex without any downtime, you have to handle a temporary index, add the configuration and data, rename the index, etc… Now :

index.ReplaceAllObjects(IEnumerable<T> newObjects);

Of course the objects are automatically batched.

Here is a list of interesting helpers:

Targeting the same application:

  • CopyRules, CopySynonyms
  • ReplaceAllSynonyms, ReplaceAllRules, ReplaceAllObjects

Targeting multiple applications:

  • Account.CopyIndex to copy indices across applications!

:confused: No more confusion between add and save.

We dropped the add verb. Now, all save methods mean either you add something new or replace it completely if it was already existing.

Also, if you decide to save objects objectID is now required. Check out the documentation.

:vulcan_salute: Specific client classes

To have a better understanding of the Algolia API we have created a class for each type of clients such as SearchClient, AnalyticsClient and InsightsClient.

:running_man:‍Running the test suite in less that 30 seconds

As the client is thread safe, we were able to run our test suite in parallel. The result is impressive: we are running around 30 end to end tests in less than 30 seconds!

How to run the tests?

Set the required environment variables and type :

dotnet test src/Algolia.Search.Test

Note: If you don’t have an MCM application you can skip the test by adding [Ignore("No MCM application")] on top of the test class.

:arrow_up: Upgrade Where should I start?

Our documentation was updated, check out the Upgrade Guide and the API Reference.

:raised_hands: Call for feedback

If you are already an Algolia user or if you plan to be, please share any feedback you may have via:

GitHub issues or Pull Requests