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

如果您的搜尋解決方案建置在適用於 .NET 的 Azure SDK 上，本文可協助您將程式代碼從舊版 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 （v10）	Azure.Search.Documents （v11）
以索引的檔案集合為目標（查詢和資料匯入）	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 的支援已轉換為 v10 中正式推出，但僅適用於 預覽 SDK）	SearchResourceEncryptionKey

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

版本 10	第 11 版對等專案
Index	SearchIndex
欄位	SearchField
DataType	SearchFieldDataType
ItemError	SearchIndexerError
分析器	LexicalAnalyzer （也， AnalyzerName 到 LexicalAnalyzerName）
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer （也， StandardTokenizerV2 到 LuceneStandardTokenizerV2）
TokenInfo	AnalyzedTokenInfo
Tokenizer	LexicalTokenizer （也， TokenizerName 至 LexicalTokenizerName）
SynonymMap.Format	無。 拿掉的 Format參考。

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

索引器、數據源、技能集

版本 10	第 11 版對等專案
索引子	SearchIndexer
DataSource	SearchIndexerDataSource 連線 ion
技能	SearchIndexerSkill
技能	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 串行化，您可以使用類似的屬性，或使用 JsonSerializer 上的屬性來傳入全域命名原則 設定。 如需相當於上一個範例的範例，請參閱 Newtonsoft.Json自述檔中的還原串行化檔範例 。

在 v11 內

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 搜尋知識淵博的使用者，也可能會想要檢閱新文檔庫的簡介，作為移轉的前身。

升級的步驟

下列步驟可讓您逐步完成第一組必要工作，特別是關於客戶端參考的程式代碼移轉。

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

2. 以下列 using 語句取代 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;
   

3. 對於需要 JSON 串行化的類別，請將 取代 using Newtonsoft.Json 為 using System.Text.Json.Serialization。

4. 修改客戶端驗證碼。 在舊版中，您會在客戶端物件上使用屬性來設定 API 金鑰（例如 SearchServiceClient.Credentials 屬性）。 在目前的版本中，使用 AzureKeyCredential 類別將密鑰傳遞為認證，因此如有需要，您可以更新 API 金鑰，而不需要建立新的客戶端物件。

   用戶端屬性已簡化為、EndpointServiceName、 和 IndexName （適當時）。 下列範例會使用系統 Uri 類別來提供端點和環境類別，以讀取金鑰值：

   Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
   AzureKeyCredential credential = new AzureKeyCredential(
      Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
   SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
   

5. 為索引器相關物件新增客戶端參考。 如果您使用索引器、數據源或技能集，請將客戶端參考變更為 SearchIndexerClient。 此用戶端是 11 版的新功能，且沒有前項。

6. 修改集合和清單。 在新 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");
   

   選取、Facet、SearchFields、SourceFields、ScoringParameters 和 OrderBy 都是現在需要重新建構的所有清單。

7. 更新查詢和數據匯入的客戶端參考。 SearchIndexClient 的實例應該變更為 SearchClient。 若要避免名稱混淆，請務必先攔截所有實例，再繼續進行下一個步驟。

8. 更新索引、同義字對應和分析器物件的客戶端參考。 SearchServiceClient 的實例應該變更為 SearchIndexClient。

9. 針對程式代碼的其餘部分，請更新類別、方法和屬性，以使用新連結庫的 API。 命名差異區段是開始的地方，但您也可以檢閱變更記錄檔。

   如果您在尋找對等 API 時遇到問題，建議您記錄問題 https://github.com/MicrosoftDocs/azure-docs/issues ，以便改善檔或調查問題。

10. 重建方案。 修正任何建置錯誤或警告之後，您可以對應用程式進行其他變更，以利用 新功能。

重大變更

鑒於連結庫和 API 的徹底變更，升級至第 11 版並不簡單，而且這表示您的程式代碼將不再與第 10 版和更早版本相容，因此構成重大變更。 如需差異的完整檢閱，請參閱 的Azure.Search.Documents變更記錄。

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

• BM25 排名演算法 會以較新的技術取代先前的排名演算法。 新的服務會自動使用此演算法。 對於現有的服務，您必須將參數設定為使用新的演算法。

• 在此版本中，Null 值的排序結果 已變更，如果排序為 asc ，則先出現 Null 值，如果排序為 ，則為最後一 desc個。 如果您撰寫程式代碼來處理 Null 值的排序方式，則如果不再需要，您應該檢閱並可能移除該程式碼。

由於這些行為變更，因此在排名結果中可能會有輕微的變化。

下一步

• 如何在 C# .NET 應用程式中使用 Azure.Search.Documents
• 教學課程：將搜尋新增至 Web 應用程式
• Azure.Search.Documents 套件
• GitHub 上的範例
• Azure.Search.Document API 參考