Upgrading versions of the Azure Search .NET Management SDK
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).
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
|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).|
How to upgrade
Review the client library changelist for insight into the scope of changes.
In your application code, delete the reference to
Microsoft.Azure.Management.Searchand its dependencies.
Add a reference for
Azure.ResourceManager.Searchusing either the NuGet Package Manager Console or by right-clicking on your project references and selecting "Manage NuGet Packages..." in Visual Studio.
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.
|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.|
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.CreateOrUpdateand its asynchronous versions now automatically poll the provisioning
SearchServiceand 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.BeginCreateOrUpdatemethod or one of its asynchronous versions.
Services.Updateand 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
SearchServiceinstance to these methods that contains only the desired
replicaCountproperties. The old way of calling
Services.Get, modifying the returned
SearchService, and passing it to
Services.CreateOrUpdateis still supported, but is no longer necessary.
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]".