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!
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?
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.
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.
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.
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.
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 email@example.com or log issues in our GitHub repo.