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

如果您使用 4.0 版或舊版 的 .NET SDK，本文將協助您將應用程式升級為使用第 5 版。

如需 SDK 的更一般逐步解說，包括範例，請參閱 如何使用 .NET 應用程式的 Azure 搜尋服務。

Azure 搜尋服務 .NET SDK 第 5 版包含舊版的一些變更。 這些大多是次要的，因此變更您的程式代碼只需要最少的工作。 如需如何變更程式代碼以使用新 SDK 版本的指示，請參閱升級 步驟。

第 5 版的新功能

Azure 搜尋服務 .NET SDK 第 5 版是以最新正式運作的 Azure 搜尋服務 REST API 版本為目標，特別是 2017-11-11。 這可讓您從 .NET 應用程式使用 Azure 搜尋服務的新功能，包括下列各項：

• 同義字。
• 您現在可以以程式設計方式存取索引器執行歷程記錄中的警告（如需詳細資訊，請參閱 WarningIndexerExecutionResult中的 屬性）。
• .NET Core 2 的支援。
• 新的套件結構僅支援使用您需要的 SDK 部分（如需詳細資訊，請參閱 第 5 版的重大變更 ）。

升級步驟

首先，在 Visual Studio 中，使用 NuGet 套件管理員控制台或以滑鼠右鍵單擊專案參考，然後選取「管理 NuGet 套件...」來更新 Microsoft.Azure.Search 的 NuGet 參考。

一旦 NuGet 下載新的套件及其相依性，請重建您的專案。 視程式代碼的結構方式而定，它可能會成功重建。 如果是這樣，您就準備好出發了！

如果您的組建失敗，您應該會看到組建錯誤，如下所示：

The name 'SuggesterSearchMode' does not exist in the current context

下一個步驟是修正此建置錯誤。 如需造成錯誤的原因以及如何修正錯誤的詳細資訊，請參閱 第 5 版的重大變更 。

請注意，由於 Azure 搜尋服務 .NET SDK 的封裝變更，您必須重建應用程式，才能使用第 5 版。 這些變更詳述於 第 5 版的重大變更中。

您可能會看到與過時方法或屬性相關的其他建置警告。 警告會包含要使用的指示，而不是已被取代的功能。 例如，如果您的應用程式使用 IndexingParametersExtensions.DoNotFailOnUnsupportedContentType 方法，您應該會收到警告，指出「預設會啟用此行為，因此不再需要呼叫這個方法」。

修正任何建置錯誤或警告之後，您可以變更應用程式，以視需要利用新功能。 SDK 中的新功能詳述於 第 5 版的新功能。

第 5 版的重大變更

新套件結構

第 5 版中最重大的變更是，Microsoft.Azure.Search 元件及其內容已分成四個不同的元件，這些元件現在會以四個不同的 NuGet 套件分發：

• Microsoft.Azure.Search：這是一個將所有其他 Azure 搜尋套件作為相依性的中繼套件。 如果您要從舊版 SDK 升級，只要升級此套件並重新建置就足以開始使用新版本。
• Microsoft.Azure.Search.Data：如果您要使用 Azure 搜尋服務開發 .NET 應用程式，而且只需要查詢或更新索引中的檔案，請使用此套件。 如果您也需要建立或更新索引、同義字對應或其他服務層級資源，請改用 Microsoft.Azure.Search 套件。
• Microsoft.Azure.Search.Service：如果您要在 .NET 中開發自動化，以管理 Azure 搜尋服務索引、同義字對應、索引器、數據源或其他服務層級資源，請使用此套件。 如果您只需要查詢或更新索引中的檔，請改用 Microsoft.Azure.Search.Data 套件。 如果您需要 Azure 搜尋服務的所有功能，請改用 Microsoft.Azure.Search 套件。
• Microsoft.Azure.Search.Common：Azure 搜尋服務 .NET 連結庫所需的常見類型。 您不應該直接在應用程式中使用此套件;它只是用來作為相依性。

這項變更在技術上屬於技術性中斷，因為許多類型已在組件之間轉移。 這就是為什麼需要重建應用程式才能升級至 SDK 第 5 版的原因。

第 5 版中有少數其他重大變更，除了重建應用程式之外，還需要變更程序代碼。

變更為建議者

Suggester 建構函式不再具有 enum的 SuggesterSearchMode 參數。 這個列舉只有一個值，因此是多餘的。 如果您看到建置錯誤，只要移除 SuggesterSearchMode 參數的參考即可。

已移除過時的成員

您可能會看到與舊版中標示為過時的方法或屬性相關的建置錯誤，並在第 5 版中後續移除。 如果您遇到這類錯誤，以下是如何解決這些錯誤：

• 如果您使用 IndexingParametersExtensions.IndexStorageMetadataOnly 方法，請改用 SetBlobExtractionMode(BlobExtractionMode.StorageMetadata) 。
• 如果您使用 IndexingParametersExtensions.SkipContent 方法，請改用 SetBlobExtractionMode(BlobExtractionMode.AllMetadata) 。

已移除預覽功能

如果您要從 4.0-preview 版升級至第 5 版，請注意，已移除 Blob 索引器的 JSON 陣列和 CSV 剖析支援，因為這些功能仍處於預覽狀態。 具體而言，已移除下列 IndexingParametersExtensions 類別的方法：

• ParseJsonArrays
• ParseDelimitedTextFiles

如果您的應用程式與這些功能有硬式相依性，您將無法升級至 Azure 搜尋服務 .NET SDK 第 5 版。 您可以繼續使用 4.0-preview 版。 不過，請記住，不建議在生產應用程式中使用預覽 SDK。 預覽功能僅供評估，且可能會變更。

結論

如果您需要使用 Azure 搜尋服務 .NET SDK 的詳細資訊，請參閱 .NET作說明。

歡迎您對 SDK 的意見反應。 如果您遇到問題，請放心地在 Stack Overflow上尋求協助。 如果您發現錯誤，您可以在 Azure .NET SDK GitHub 儲存機制中提出問題。 請務必在問題標題前面加上 “[Azure 搜尋服務]”。

感謝您使用 Azure 搜尋服務！