Edit

Upgrading versions of the Azure Search .NET Management SDK

  • Article
  • 3 minutes to read

This article explains how to migrate to successive versions of the Azure Search .NET Management SDK, used to provision or deprovision search services, adjust capacity, and manage API keys.

Management SDKs target a specific version of the Management REST API. For more information about concepts and operations, see Search Management (REST).

Versions

Microsoft.Azure.Management.Search is now deprecated. We recommend Azure.ResourceManager.Search instead.

SDK version Corresponding REST API version Feature addition or behavior change
1.0 api-version=2020-08-01 This is a new package from the Azure SDK team that implements approaches and standards that are common to resource management in Azure. There's no migration path. If you've used the previous client library for service administration in Azure Cognitive Search, you should redesign your solution to use the new Azure.ResourceManager.Search package. See the readme for links and next steps.
3.0 api-version=2020-30-20 Adds endpoint security (IP firewalls and integration with Azure Private Link)
2.0 api-version=2019-10-01 Usability improvements. Breaking change on List Query Keys (GET is discontinued).
1.0 api-version=2015-08-19 First version

How to upgrade

  1. Review the client library changelist for insight into the scope of changes.

  2. In your application code, delete the reference to Microsoft.Azure.Management.Search and its dependencies.

  3. Add a reference for Azure.ResourceManager.Search using either the NuGet Package Manager Console or by right-clicking on your project references and selecting "Manage NuGet Packages..." in Visual Studio.

  4. Once NuGet has downloaded the new packages and their dependencies, replace the API calls.

Upgrade to 3.0

Version 3.0 adds private endpoint protection by restricting access to IP ranges, and by optionally integrating with Azure Private Link for search services that shouldn't be visible on the public internet.

New APIs

API Category Details
NetworkRuleSet IP firewall Restrict access to a service endpoint to a list of allowed IP addresses. See Configure IP firewall for concepts and portal instructions.
Shared Private Link Resource Private Link Create a shared private link resource to be used by a search service.
Private Endpoint Connections Private Link Establish and manage connections to a search service through private endpoint. See Create a private endpoint for concepts and portal instructions.
Private Link Resources Private Link For a search service that has a private endpoint connection, get a list of all services used in the same virtual network. If your search solution includes indexers that pull from Azure data sources (such as Azure Storage, Azure Cosmos DB, Azure SQL), or uses Cognitive Services or Key Vault, then all of those resources should have endpoints in the virtual network, and this API should return a list.
PublicNetworkAccess Private Link This is a property on Create or Update Service requests. When disabled, private link is the only access modality.

Breaking changes

You can no longer use GET on a List Query Keys request. In previous releases you could use either GET or POST, in this release and in all releases moving forward, only POST is supported.

Upgrade to 2.0

Version 2 of the Azure Search .NET Management SDK is a minor upgrade, so changing your code should require only minimal effort. The changes to the SDK are strictly client-side changes to improve the usability of the SDK itself. These changes include the following:

  • Services.CreateOrUpdate and its asynchronous versions now automatically poll the provisioning SearchService and don't return until service provisioning is complete. This saves you from having to write such polling code yourself.

  • If you still want to poll service provisioning manually, you can use the new Services.BeginCreateOrUpdate method or one of its asynchronous versions.

  • New methods Services.Update and its asynchronous versions have been added to the SDK. These methods use HTTP PATCH to support incremental updating of a service. For example, you can now scale a service by passing a SearchService instance to these methods that contains only the desired partitionCount and replicaCount properties. The old way of calling Services.Get, modifying the returned SearchService, and passing it to Services.CreateOrUpdate is still supported, but is no longer necessary.

Next steps

If you encounter problems, the best forum for posting questions is Stack Overflow. If you find a bug, you can file an issue in the Azure .NET SDK GitHub repository. Make sure to label your issue title with "[search]".