升級至 Azure AI 搜尋服務 .NET SDK 第 11 版

發行項
09/03/2024

如果您的搜尋解決方案是以 Azure SDK for .NET 建置，則本文可協助您將程式碼從舊版 Microsoft.Azure.Search 移轉至第 11 版，亦即新的 Azure.Search.Documents 用戶端程式庫。版本 11 是完全重新設計的用戶端程式庫，由 Azure SDK 開發小組發行 (舊版是由 Azure AI 搜尋服務開發小組製作)。

第 10 版的所有功能都可在第 11 版中實作。重要差異包括：

一個套件 (Azure.Search.Documents)，而不是四個
三個用戶端，而不是兩個：SearchClient、SearchIndexClient、SearchIndexerClient
不同 API 的命名差異，以及可簡化某些工作的些微結構差異

用戶端程式庫的變更記錄提供一份更新的明細清單。您可以在本文中檢閱版本摘要。

Azure AI 搜尋服務產品文件中的所有 C# 程式碼範例和程式碼片段都已修訂為使用新的 Azure.Search.Documents 用戶端程式庫。

為何要升級？

升級的優點摘要如下：

新功能只會新增至 Azure.Search.Documents。舊版 Microsoft.Azure.Search 現已淘汰。已淘汰的程式庫更新僅限於高優先順序的錯誤修正程式。
與其他 Azure 用戶端程式庫保持一致。 Azure.Search.Documents 相依於 Azure.Core 和 System.Text.Json，並遵循一般工作的傳統方法，例如用戶端連線和授權。

Microsoft.Azure.Search 已正式淘汰。如果您使用舊版本，建議您升級至下一個較高的版本，並連續重複此程序，直到升級到第 11 版和 Azure.Search.Documents 為止。累進式升級策略可讓您更輕鬆地發現和修正執行問題。如需指引，請參閱舊版文件。

套件比較

第 11 版整合並簡化套件管理，所以要管理的部分較少。

第 10 版和先前版本	第 11 版
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Azure.Search.Documents 套件

用戶端比較

下表對應兩個版本之間的用戶端程式庫 (如果適用)。

用戶端作業	Microsoft.Azure.Search (第 10 版)	Azure.Search.Documents (第 11 版)
以索引 (查詢和資料匯入) 的文件集合為目標	SearchIndexClient	SearchClient
以索引相關物件 (索引、分析器、同義字對應) 為目標	SearchServiceClient	SearchIndexClient
以索引子相關物件 (索引子、資料來源、技能集) 為目標	SearchServiceClient	SearchIndexerClient (new)

警告

請注意，兩個版本都有 SearchIndexClient，但以不同的作業為目標。在第 10 版中，SearchIndexClient 會建立索引和其他物件。在第 11 版中，SearchIndexClient 可搭配使用現有的索引，使用查詢和資料擷取 API 鎖定文件集合為目標。若要避免在更新程式碼時發生混淆，請留意用戶端參考更新的順序。遵循升級步驟中的順序，應該有助於減輕字串取代問題。

命名和其他 API 差異

除了用戶端差異 (前面已說明，故在此省略)，多個其他 API 已重新命名並在某些情況下重新設計。下列各節彙整了類別名稱差異。這份清單並不詳盡，但依工作將 API 變更進行分組，因此對於特定程式碼區塊的修訂很有幫助。如需 API 更新的明細清單，請參閱 GitHub 上 Azure.Search.Documents 的變更記錄。

驗證和加密

第 10 版	第 11 版對等項目
SearchCredentials	AzureKeyCredential
EncryptionKey (未記載於 API 參考資料。這個 API 的支援已轉換成在第 10 版中正式發行，但僅限在預覽版 SDK 中提供)	SearchResourceEncryptionKey

索引、分析器、同義字對應

第 10 版	第 11 版對等項目
Index	SearchIndex
欄位	SearchField
DataType	SearchFieldDataType
ItemError	SearchIndexerError
分析器	LexicalAnalyzer (另外，`AnalyzerName` 對應至 `LexicalAnalyzerName`)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (另外，`StandardTokenizerV2` 對應至 `LuceneStandardTokenizerV2`)
TokenInfo	AnalyzedTokenInfo
權杖化工具	LexicalTokenizer (另外，`TokenizerName` 對應至 `LexicalTokenizerName`)
SynonymMap.Format	無。移除對 `Format` 的參考。

欄位定義已簡化：SearchableField、SimpleField、ComplexField 是用來建立欄位定義的新 API。

索引子、資料來源、技能集

第 10 版	第 11 版對等項目
索引子	SearchIndexer
DataSource	SearchIndexerDataSourceConnection
Skill	SearchIndexerSkill
Skillset	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

資料匯入

第 10 版	第 11 版對等項目
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

查詢要求和回應

第 10 版	第 11 版對等項目
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult 或 SearchResults，視結果是單一或多重文件而定。
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (新類別，用來建構 OData 篩選條件運算式)

JSON 序列化

根據預設，Azure SDK 會使用 System.Text.Json 進行 JSON 序列化，並運用這些 API 的功能來處理先前透過原生 SerializePropertyNamesAsCamelCaseAttribute 類別實作的文字轉換，而這項類別在新程式庫中沒有對應項目。

若要將屬性名稱序列化為 camelCase，您可以使用 JsonPropertyNameAttribute (類似此範例)。

或者，您也可以設定 JsonSerializerOptions 中提供的 JsonNamingPolicy。下列 System.Text.Json 程式碼範例取自 Microsoft.Azure.Core.Spatial 讀我檔案，示範如何使用 camelCase 而不需要歸因每個屬性：

// Get the Azure AI Search service endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

如果您使用 Newtonsoft.Json 進行 JSON 序列化，可以使用類似的屬性，或使用 JsonSerializerSettings 中的屬性來傳入全域命名原則。如需與上述相當的範例，請參閱 Newtonsoft.Json 讀我檔案中的還原序列化文件範例。

在第 11 版之中

Azure AI 搜尋服務用戶端程式庫的每個版本均會對應至 REST API 的特定版本。 REST API 被視為服務的基礎，並在不同的 SDK 中包裝一個 REST API 版本。身為 .NET 開發人員，如需特定物件或作業的深入說明，請檢閱更詳細的 REST API 文件。第 11 版係對應至 2020-06-30 搜尋服務規格。

11.0 版完全支援下列物件和作業：

索引建立和管理
同義字對應建立和管理
索引子建立和管理
索引子資料來源建立和管理
技能集建立和管理
所有查詢類型和語法

11.1 版新增項目 (變更記錄詳細資料)：

FieldBuilder (11.1 新增項目)
序列化程式屬性 (11.1 新增項目) 用來支援自訂序列化

11.2 版新增項目 (變更記錄詳細資料)：

EncryptionKey 屬性已新增索引子、資料來源和技能集
IndexingParameters.IndexingParametersConfiguration 屬性支援
地理空間類型是 FieldBuilder 中的原生支援項目。 SearchFilter 可以編碼 Microsoft.Spatial 中的幾何類型，不需要明確的組件相依性。

您也可以繼續明確宣告 Microsoft.Spatial 的相依性。這項技術的範例適用於 System.Text.Json 和 Newtonsoft.Json。

11.3 版新增項目 (變更記錄詳細資料)：

KnowledgeStore
已在 SearchDocument、SearchFilter 和 FieldBuilder 中新增 Azure.Core.GeoJson 類型支援。
已新增 EventSource 型記錄。事件來源名稱為 Azure-Search-Documents。目前事件集的重點放在調整 SearchIndexingBufferedSender 的批次大小。
已新增 CustomEntityLookupSkill 和 DocumentExtractionSkill。已在 LanguageDetectionSkill 中新增 DefaultCountryHint。

升級前

快速入門、教學課程和 C# 範例均已更新為使用 Azure.Search.Documents 套件。建議您先檢閱範例和逐步解說以了解新的 API，再開始進行移轉練習。
如何使用 Azure.Search.Documents 介紹最常用的 API。即使已相當熟悉 Azure AI 搜尋服務，仍建議使用者在進行移轉之前，先檢閱這個新程式庫的介紹。

升級步驟

下列步驟會逐步解說第一組必要工作，特別是關於用戶端參考的部分，引導您開始進行程式碼移轉。

以滑鼠右鍵按一下您的專案參考，然後在 Visual Studio 中選取 [管理 NuGet 套件...]，以安裝 Azure.Search.Documents 套件。

取代 Microsoft.Azure.Search 的 using 指示詞，如下陳述式所示：

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

對於需要 JSON 序列化的類別，將 using Newtonsoft.Json 取代為 using System.Text.Json.Serialization。
修改用戶端驗證碼。在舊版中，您會使用用戶端物件的屬性來設定 API 金鑰 (例如 SearchServiceClient.Credentials 屬性)。在目前的版本中，請使用 AzureKeyCredential 類別將金鑰當作認證傳遞，這樣一來在必要時，您可以更新 API 金鑰，而不需建立新的用戶端物件。

用戶端屬性已簡化為只有 Endpoint、ServiceName 和 IndexName (視需要)。下列範例會使用系統 Uri 類別來提供端點和 Environment 類別，以讀取金鑰值：
```
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
```
新增索引子相關物件的用戶端參考。如果您使用索引子、資料來源或技能集，請將用戶端參考變更為 SearchIndexerClient。此用戶端是第 11 版的新增項目，沒有前項。
修訂集合和清單。在新 SDK 中，所有清單都是唯讀性質，以免在清單碰巧含有 Null 值時發生下游問題。程式碼變更是要在清單中新增項目。例如，不用將字串指派給 Select 屬性，您只要如下所示新增字串即可：
```
var options = new SearchOptions
 {
    SearchMode = SearchMode.All,
    IncludeTotalCount = true
 };

 // Select fields to return in results.
 options.Select.Add("HotelName");
 options.Select.Add("Description");
 options.Select.Add("Tags");
 options.Select.Add("Rooms");
 options.Select.Add("Rating");
 options.Select.Add("LastRenovationDate");
```
Select、Facets、SearchFields、SourceFields、ScoringParameters 和 OrderBy 都是現在必須重新建構的清單。
更新查詢和資料匯入的用戶端參考。 SearchIndexClient 的執行個體應該變更為 SearchClient。若要避免發生名稱混淆，請務必先攔截所有執行個體，再繼續進行下一個步驟。
更新索引、同義字對應和分析器物件的用戶端參考。 SearchServiceClient 的執行個體應變更為 SearchIndexClient。
如需程式碼的其餘部分，請更新類別、方法和屬性，以使用新程式庫的 API。您可以從命名差異區段開始，但也可以檢閱變更記錄。

如果您在尋找對等的 API 時遇到問題，建議您在 https://github.com/MicrosoftDocs/azure-docs/issues 記錄問題，以便改善文件或調查問題。
重建方案。在修正所有建置錯誤或警告之後，就可以對您的應用程式進行其他變更，以利用的功能。

重大變更

由於程式庫和 API 發生全面變更，升級至第 11 版非常重要且會造成中斷性變更，也就是說，您的程式碼將不再具有第 10 版和更早版本的回溯相容性。如需完整檢閱差異，請參閱 Azure.Search.Documents 的變更記錄。

在服務版本更新方面，第 11 版中的程式碼變更與現有功能相關 (不只是重構 API)，您會發現下列行為變更：

BM25 排名演算法會以較新的技術取代先前的排名演算法。新的服務會自動使用此演算法。針對現有的服務，您必須設定參數以使用新的演算法。
此版本中已變更 Null 值的已排序結果，如果排序為 asc，則會先顯示 Null 值，如果排序為 desc，則會最後顯示 Null 值。如果您撰寫程式碼來處理 Null 值的排序方式，則應檢閱程式碼，且若該程式碼已不再需要，則可能需要加以移除。

由於這些行為變更，經排名的結果可能會有些許不同。

共用方式為