Skip to content

Commit 0fad321

Browse files
HeidiSteenHeidiSteen
committed
management SDK doc clean up
1 parent d2b9b51 commit 0fad321

File tree

1 file changed

+10
-50
lines changed

1 file changed

+10
-50
lines changed

‎articles/search/search-dotnet-mgmt-sdk-migration.md

Lines changed: 10 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Management SDKs
2+
title: Upgrade management SDKs
33
titleSuffix: Azure Cognitive Search
44
description: Learn about the management libraries and packages used for control plane operations in Azure Cognitive Search.
55

@@ -13,28 +13,22 @@ ms.topic: conceptual
1313
ms.date: 09/15/2023
1414
---
1515

16-
# Manage a search service using Azure SDKs
16+
# Upgrade versions of the Azure Search .NET Management SDK
1717

18-
Azure SDKs include libraries and packages for provisioning and managing an Azure Cognitive Search service. This article enumerates the c
19-
## Control plane tasks
18+
This article points you to libraries in the Azure SDK for .NET that are used to provision or deprovision search services, adjust capacity, manage API keys, and configure network security.
2019

21-
22-
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.
23-
24-
Management SDKs target a specific version of the Management REST API. For more information about concepts and operations, see [Search Management (REST)](/rest/api/searchmanagement/).
20+
Management SDKs target a specific version of the Management REST API. Release notes for each library indicate which REST API version is the target for each package. For more information about concepts and operations, see [Search Management (REST)](/rest/api/searchmanagement/).
2521

2622
## Versions
2723

28-
Microsoft.Azure.Management.Search is now deprecated. We recommend [Azure.ResourceManager.Search](https://github.com/Azure/azure-sdk-for-net/blob/Azure.ResourceManager.Search_1.0.0/sdk/search/Azure.ResourceManager.Search/README.md) instead.
24+
The following table lists the client libraries used to provision a search service.
2925

30-
| SDK version | Corresponding REST API version | Feature addition or behavior change |
31-
|-------------|--------------------------------|-------------------------------------|
32-
| [1.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/) | 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](https://github.com/Azure/azure-sdk-for-net/blob/Azure.ResourceManager.Search_1.0.0/sdk/search/Azure.ResourceManager.Search/README.md) for links and next steps.|
33-
| [3.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Search/3.0.0) | api-version=2020-30-20 | Adds endpoint security (IP firewalls and integration with [Azure Private Link](../private-link/private-endpoint-overview.md)) |
34-
| [2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Search/2.0.0) | api-version=2019-10-01 | Usability improvements. Breaking change on [List Query Keys](/rest/api/searchmanagement/2021-04-01-preview/query-keys/list-by-search-service) (GET is discontinued). |
35-
| [1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Search/1.0.1) | api-version=2015-08-19 | First version |
26+
| Namespace | Version| Status | Change log |
27+
|-----------|--------|--------|------------|
28+
| [Azure.ResourceManager.Search](/dotnet/api/overview/azure/resourcemanager.search-readme?view=azure-dotnet&preserve-view=true) | [Package versions](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.0.0) | **Current** | [Release notes](https://github.com/Azure/azure-sdk-for-net/blob/Azure.ResourceManager.Search_1.2.0-beta.1/sdk/search/Azure.ResourceManager.Search/CHANGELOG.md) |
29+
| [Microsoft.Azure.Management.Search](/dotnet/api/overview/azure/search/management/management-cognitivesearch(deprecated)?view=azure-dotnet&preserve-view=true) | [Package versions](https://www.nuget.org/packages/Microsoft.Azure.Management.Search#versions-body-tab) | **Deprecated** | [Release notes](https://www.nuget.org/packages/Microsoft.Azure.Management.Search#release-body-tab) |
3630

37-
## How to upgrade
31+
## Checklist for upgrade
3832

3933
1. Review the [client library changelist](https://github.com/Azure/azure-sdk-for-net/blob/Azure.ResourceManager.Search_1.0.0/sdk/search/Azure.ResourceManager.Search/CHANGELOG.md) for insight into the scope of changes.
4034

@@ -44,40 +38,6 @@ Microsoft.Azure.Management.Search is now deprecated. We recommend [Azure.Resourc
4438

4539
1. Once NuGet has downloaded the new packages and their dependencies, replace the API calls.
4640

47-
<!-- | Old API | New API |
48-
|---------|---------|
49-
| [CreateOrUpdateWithHttpMessagesAsync Method](/dotnet/api/microsoft.azure.management.search.iservicesoperations.createorupdatewithhttpmessagesasync) | TBD |
50-
| [CheckNameAvailabilityWithHttpMessagesAsync Method](/dotnet/api/microsoft.azure.management.search.iservicesoperations.checknameavailabilitywithhttpmessagesasync) | TBD |
51-
| [IAdminKeysOperations.GetWithHttpMessagesAsync Method](/dotnet/api/microsoft.azure.management.search.iadminkeysoperations.getwithhttpmessagesasync) | TBD | -->
52-
53-
## Upgrade to 3.0
54-
55-
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.
56-
57-
### New APIs
58-
59-
| API | Category| Details |
60-
|-----|--------|------------------|
61-
| [NetworkRuleSet](/rest/api/searchmanagement/2021-04-01-preview/services/create-or-update#networkruleset) | IP firewall | Restrict access to a service endpoint to a list of allowed IP addresses. See [Configure IP firewall](service-configure-firewall.md) for concepts and portal instructions. |
62-
| [Shared Private Link Resource](/rest/api/searchmanagement/2021-04-01-preview/shared-private-link-resources) | Private Link | Create a shared private link resource to be used by a search service. |
63-
| [Private Endpoint Connections](/rest/api/searchmanagement/2021-04-01-preview/private-endpoint-connections) | Private Link | Establish and manage connections to a search service through private endpoint. See [Create a private endpoint](service-create-private-endpoint.md) for concepts and portal instructions.|
64-
| [Private Link Resources](/rest/api/searchmanagement/2021-04-01-preview/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 Azure AI services or Key Vault, then all of those resources should have endpoints in the virtual network, and this API should return a list. |
65-
| [PublicNetworkAccess](/rest/api/searchmanagement/2021-04-01-preview/services/create-or-update#publicnetworkaccess)| Private Link | This is a property on Create or Update Service requests. When disabled, private link is the only access modality. |
66-
67-
### Breaking changes
68-
69-
You can no longer use GET on a [List Query Keys](/rest/api/searchmanagement/2021-04-01-preview/query-keys/list-by-search-service) request. In previous releases you could use either GET or POST, in this release and in all releases moving forward, only POST is supported.
70-
71-
## Upgrade to 2.0
72-
73-
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:
74-
75-
* `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.
76-
77-
* If you still want to poll service provisioning manually, you can use the new `Services.BeginCreateOrUpdate` method or one of its asynchronous versions.
78-
79-
* 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.
80-
8141
## Next steps
8242

8343
If you encounter problems, the best forum for posting questions is [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-cognitive-search?tab=Newest). If you find a bug, you can file an issue in the [Azure .NET SDK GitHub repository](https://github.com/Azure/azure-sdk-for-net/issues). Make sure to label your issue title with "[search]".

0 commit comments

Comments
 (0)