Since first releasing the .NET SDK for Azure Search in March 2015, we've received a lot of great customer feedback. One common theme stands out: feature parity between the REST API and .NET SDK.

Many customers use Azure Search features that are still in preview. These features are not available in the .NET SDK. When preview features are introduced in the REST API, the SDK should be updated to support them as soon as possible. Similarly, when features become generally available, a stable SDK version including those features should also be released.

For the past several months we've been working hard to make this a reality. Now that version 1.0-preview of the .NET SDK is available, we’re almost ready to release the first stable, generally available version. We're not at feature parity for preview features yet, but now is a good time to share our progress to date, and our plans for reaching feature parity soon.

Version 1.0-preview

We recently announced the release of version 1.0-preview of the Azure Search .NET SDK. You can download the new SDK from NuGet, and read about what's new in this article.

There are some big changes in this version, both in the interface and under the hood. The result is an SDK that's easier to use and consistent with the next generation of Azure client libraries. Most importantly, it's built on a solid foundation that will enable us to add features more quickly.

To look at our future roadmap, read on. If you're interested in the details of 1.0-preview, feel free to skip to “What changed in 1.0-preview and why.”

Upcoming releases

General availability and Lucene query syntax (version 1.1)

The next planned release of the Azure Search .NET SDK will be the first generally available release, meaning:

1. You can use the new version with confidence that we won't make any breaking changes.
2. We will drop the -preview moniker from the SDK version. You won't need to check “Include Prerelease” anymore when searching for the Microsoft.Azure.Search NuGet package.

We plan to ship the first stable release of the SDK in February and it will target version 2015-02-28 of the REST API.

Also, by popular demand, we will be adding support for the Lucene query syntax to the SDK. It is currently available only in version 2015-02-28-Preview of the REST API, but we will make it available in version 2015-02-28 before the 1.1 SDK release.

Preview feature availability (2.x-preview versions)

Once the first stable SDK ships, we will begin working on a new preview SDK version, which we're tentatively calling 2.x-preview. This will target version 2015-02-28-Preview of the REST API. We plan to incrementally update this with preview features until we achieve parity between the REST API and SDK. These features include:

• Custom analyzers
• Azure Blob Storage Indexer
• Indexer customization via field mappings
• ETags support to enable safe concurrent updating of index definitions, indexers, and data sources

We are planning this work for Q1 of this year. It's too early to say in which order the features will ship or exactly when, but we will share this information as we make progress. You can track our progress on GitHub; Just look for pull requests and issues with “Search SDK” in the title.

Next major feature release (2.x)

Soon after 2.x-preview ships, the features included in 2.x-preview will be made generally available in a new locked REST API version, followed closely by what we are tentatively calling version 2.x of the .NET SDK. Our goal from this point on is to ship new features in the .NET SDK within one month after making them available in the REST API. That goes for preview features as well.

What changed in 1.0-preview and why

Like many Azure SDKs, the Azure Search SDK is developed with the help of a code generation tool and common runtime library. We use codegen because we intend to bring the Azure Search SDK to other languages and platforms. Codegen will make this easier. It also ensures a common “look and feel” across Azure SDKs, which makes the Azure platform as a whole more usable. Having a common runtime library is also a necessary part of this, since it provides things like a common exception class (CloudException), built-in retry policies, common ways to authenticate, and so on.

Prior versions of the Azure Search .NET SDK used an internal Microsoft code generation tool known as, Hyak, and its corresponding runtime library Hyak.Common. Starting with version 1.0-preview, we've moved to a new open-source tool called AutoRest, which includes a new common runtime library. This migration was a big investment, but it has already started to pay off and we'll continue to see benefits far into the future. The following are just some of the benefits of using AutoRest for the Azure Search SDK:

• AutoRest-generated C# code uses JSON.NET for serialization. This allowed us to expose powerful client-side serialization features in 1.0-preview that make it easier to map your own custom model classes to your Azure Search index schema.
• AutoRest takes Swagger specifications as input. Swagger is a popular open format for specifying REST APIs. Switching to Swagger from Hyak's proprietary specifications is making it easier for us to add new features to the Azure Search SDK. As an added bonus, customers familiar with Swagger can now use our Swagger specs as a secondary reference for the Azure Search REST API. Note: Not all of the API is modeled in Swagger at the time of this writing, but we will be adding more coverage over time).
• The generated code now clearly separates HTTP-level methods from higher-level simplified methods working directly with model classes. For example, Indexes.Create no longer returns an IndexDefinitionResponse. It now returns an Index object directly.
• AutoRest uses Razor templates as its code-generation backend. This makes it much easier to add support for new target languages. This will help us port the Azure Search SDK to more languages and platforms in the future.

Now that the move to AutoRest is complete, we're ready to make our final push towards feature parity between the REST API and .NET SDK. This will be accomplished over the next few SDK releases.

Summary

Releasing a generally available .NET SDK and reaching feature parity between the Azure Search REST API and .NET SDK are high priorities for us. Releasing version 1.0-preview of the SDK was the first step. This table summarizes the upcoming releases that will get us there:

In the meantime, we encourage everyone to try out version 1.0-preview and send us your feedback. If you encounter problems, feel free to ask us for help on the Azure Search MSDN forum. If you find a bug, you can file an issue in the Azure .NET SDK GitHub repository. Make sure to prefix your issue title with “Search SDK: ” so it gets to the right people.

Thank you for using Azure Search!