Azure Cosmos DB .NET SDK Version 3.0 now in public preview

The Azure Cosmos DB team is excited to announce version 3.0 of the .NET SDK, now in public preview and open sourced on GitHub!

We are excited to get your feedback, so please try it out and let us know what you think. You can get the latest version through NuGet, and contribute on GitHub.

What is Azure Cosmos DB?

Azure Cosmos DB is a globally distributed, multi-model database service that enables you to read and write data from any Azure region. It offers turnkey global distribution, guarantees single-digit millisecond latencies at the 99th percentile, and elastic scaling of throughput and storage.

What is new in version 3.0 of .NET SDK?

Version 3.0 of the SDK targets .NET Standard 2.0 and features numerous usability and performance improvements, including a new, more intuitive object model and support for streams. The SDK also joins our Java, JavaScript, and Python SDKs in being open source on GitHub.

This is an early preview of the version 3.0 SDK, and we recommend folks continue to use version 2.x of our .NET SDK for production workloads. We have no immediate plans at this time to deprecate or discontinue support for version 2.x of the .NET SDK.

Targets .NET Standard 2.0

We’ve unified our existing .NET and .NET Core SDKs into a single .NET SDK, which targets .NET Standard 2.0. This means you can now use the .NET SDK in both your .NET Framework 4.6.1+ and .NET Core 2.0+ applications.

Intuitive programming model

Over the past few months, our team has been working on improving the developer experience of the Azure Cosmos DB SDKs based on your feedback.

New Fluent API Surface

We’ve created a new top level CosmosClient class to replace DocumentClient, and split up its methods into modular CosmosDatabase, CosmosContainer, and CosmosItems classes. The new programming model removes the need for UriFactory and other “noise” from the application code.

Our usability studies showed the hierarchy makes it easier for new developers to discover what to do next. The modular CosmosDatabase and CosmosContainer types also make dependency injection easier. Now, you can easily pass around the context of a database or container in your application, without the need to pass the client, database, and container names.

Easier to test

Following numerous requests from developers, unit testing is made easier with the new hierarchical programming model, as all types made mockable. We also introduced middleware extensibility via CosmosConfiguration.AddCustomHandlers(), that allows you to plug into the SDK request/response pipeline.

Naming changes

We’ve made some naming changes to better align the SDK to the Azure Cosmos DB resource model. Because Azure Cosmos DB supports multiple data models, we’re renaming Collection and Document to the more generic name of Container and Item across all SDKs.

Performance improvements

The prior versions of SDKs always serialized and deserialized the data to and from the network. In many cases, this is unnecessary and leads to performance overhead. Now, when you read an item or query in the context of an ASP.NET Web API, you can just get the stream and pass it to the response without serialization overhead, by using the new ReadItemAsStreamAsync and CreateItemQueryAsStream methods.

Removed reliance on dynamic

With the new SDK, you can continue to use dynamic, but we no longer inject our own dynamic type. We’ve also removed the double deserialization occurrences the 2.x.x SDK had.

Streamlined exception handling

Marshalling exceptions across async await calls can be expensive. The new SDK continues to throw exceptions for the typed programming model as developers expect. However, for the Stream programming model, we give you a CosmosResponseMessage.StatusCode for any response returned by the server. The SDK only throws for errors that led to no response being returned, allowing performance sensitive applications finer control over exceptions usage.

Open source

The Azure Cosmos DB .NET SDK is now open source! We’ll be logging issues, tracking feedback, and accepting PRs in GitHub.

Preview features FAQ

In this preview release, there are several features not yet supported. They include:

• LINQ support
• User Defined Functions (UDF) and Triggers
• Users and Permissions
• Change feed

Support for these futures will be upcoming in a future release.

Get started

To get started with the new SDK, add our new NuGet package to your project. Follow our new tutorials for .NET and .NET Core. We’d love to hear your feedback! Email askcosmosdb@microsoft.com or log issues in our GitHub repo.

Stay up-to-date on the latest Azure #CosmosDB news and features by following us on Twitter @AzureCosmosDB. We are really excited to see what you will build with Azure Cosmos DB!

Source: Azure Blog Feed