Upgrade auf Version 11 des Azure AI Search .NET SDK

Artikel
12/10/2024

Wenn Ihre Suchlösung auf dem Azure SDK für .NET basiert, hilft Ihnen dieser Artikel bei der Migration Ihres Codes von früheren Versionen von Microsoft.Azure.Search zu Version 11, der neuen Azure.Search.Documents-Clientbibliothek. Version 11 ist eine vollständig neu gestaltete Clientbibliothek, die vom Azure SDK-Entwicklungsteam freigegeben wurde (frühere Versionen wurden vom Azure AI Search-Entwicklungsteam erstellt).

Alle Features von Version 10 werden in Version 11 implementiert. Zu den wichtigsten Unterschieden gehören:

Ein Paket (Azure.Search.Documents) anstelle von vier Paketen
Drei Clients anstelle von zwei: SearchClient, SearchIndexClient, SearchIndexerClient
Benennungsunterschiede bei verschiedenen APIs und kleine strukturelle Unterschiede, die einige Aufgaben vereinfachen

Das Änderungsprotokoll der Clientbibliothek umfasst eine detaillierte Liste mit Updates. Eine Zusammenfassung finden Sie in diesem Artikel.

Alle C#-Codebeispiele und -Codeausschnitte in der Azure AI Search-Produktdokumentation wurden überarbeitet, um die neue Azure.Search.Documents-Clientbibliothek zu verwenden.

Gründe für ein Upgrade

Die Vorteile des Upgrades werden wie folgt zusammengefasst:

Neue Features werden nur zu Azure.Search.Documents hinzugefügt. Die vorherige Version (Microsoft.Azure.Search) wurde ausgemustert. Updates für veraltete Bibliotheken sind nur auf Fehlerbehebungen mit hoher Priorität beschränkt.
Konsistenz mit anderen Azure-Clientbibliotheken. Azure.Search.Documents ist abhängig von Azure.Core und System.Text.Json und folgt herkömmlichen Ansätzen für allgemeine Aufgaben wie Clientverbindungen und die Autorisierung.

Microsoft.Azure.Search wurde offiziell eingestellt. Wenn Sie eine alte Version verwenden, empfehlen wir, ein Upgrade auf die jeweils nächsthöhere Version durchzuführen und den Prozess so oft zu wiederholen, bis Sie Version 11 und Azure.Search.Documents erreichen. Eine inkrementelle Upgradestrategie erleichtert das Auffinden und Beheben von Blockierungsproblemen. Anleitungen finden Sie in den Dokumenten der vorherigen Version.

Paketvergleich

Version 11 konsolidiert und vereinfacht die Paketverwaltung, sodass weniger verwaltet werden muss.

Version 10 und früher	Version 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Azure.Search.Documents-Paket

Clientvergleich

In der folgenden Tabelle werden die Clientbibliotheken soweit möglich einer der beiden Versionen zugeordnet.

Clientvorgänge	Microsoft.Azure.Search (v10)	Azure.Search.Documents (v11)
Zielt auf die Dokumentensammlung eines Indexes ab (Abfragen und Datenimport)	SearchIndexClient	SearchClient
Zielt auf indexbezogene Objekte (Indizes, Analysetools, Synonymzuordnungen) ab.	SearchServiceClient	SearchIndexClient
Zielt auf indexerbezogene Objekte (Indexer, Datenquellen, Skillsets) ab.	SearchServiceClient	SearchIndexerClient (neu)

Achtung

Beachten Sie, dass SearchIndexClient in beiden Versionen vorhanden ist, aber unterschiedliche Vorgänge als Ziel verwendet. In Version 10 erstellt SearchIndexClient Indizes und andere Objekte. In Version 11 arbeitet SearchIndexClient mit vorhandenen Indizes, die auf die Dokumentensammlung mit Abfrage- und Datenerfassungs-APIs abzielen. Achten Sie auf die Reihenfolge, in der die Clientverweise aktualisiert werden, damit keine Unklarheiten entstehen. Befolgen Sie die Reihenfolge in den Schritten zum Aktualisieren, um Probleme beim Ersetzen von Zeichenfolgen zu vermeiden.

Benennung und andere API-Unterschiede

Abgesehen von den Clientunterschieden (die bereits erwähnt und daher hier weggelassen werden), wurden mehrere andere APIs umbenannt und in einigen Fällen überarbeitet. Klassennamenunterschiede werden in den folgenden Abschnitten zusammengefasst. Diese Liste ist nicht vollständig, aber darin werden API-Änderungen nach Aufgaben gruppiert, was für Revisionen bei bestimmten Codeblöcken hilfreich sein kann. Eine detaillierte Liste der API-Updates finden Sie im Änderungsprotokoll für Azure.Search.Documents auf GitHub.

Authentifizierung und Verschlüsselung

Version 10	Entsprechung in Version 11
SearchCredentials	AzureKeyCredential
EncryptionKey (In API-Referenz nicht dokumentiert. Die Unterstützung für diese API wurde in v10 allgemein verfügbar, war aber nur im Vorschau-SDK verfügbar.)	SearchResourceEncryptionKey

Indizes, Analysetools, Synonymzuordnungen

Version 10	Entsprechung in Version 11
Index	SearchIndex
Feld	SearchField
DataType	SearchFieldDataType
ItemError	SearchIndexerError
Analyzer	LexicalAnalyzer (auch `AnalyzerName` in `LexicalAnalyzerName`)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (auch `StandardTokenizerV2` in `LuceneStandardTokenizerV2`)
TokenInfo	AnalyzedTokenInfo
Tokenizer	LexicalTokenizer (auch `TokenizerName` in `LexicalTokenizerName`)
SynonymMap.Format	Keine. Verweise auf `Format` entfernen.

Felddefinitionen sind optimiert: SearchableField, SimpleField, ComplexField sind neue APIs zum Erstellen von Felddefinitionen.

Indexer, Datenquellen, Skillsets

Version 10	Entsprechung in Version 11
Indexer	SearchIndexer
DataSource	SearchIndexerDataSourceConnection
Skill	SearchIndexerSkill
Qualifikationsgruppe	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

Datenimport

Version 10	Entsprechung in Version 11
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

Abfrageanforderungen und -antworten

Version 10	Entsprechung in Version 11
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult oder SearchResults, abhängig davon, ob das Ergebnis ein einziges Dokument oder mehrere Dokumente ist.
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (neue Klasse zum Erstellen von OData-Filterausdrücken)

JSON-Serialisierung

Standardmäßig verwendet das Azure SDK System.Text.Json für die JSON-Serialisierung und nutzt dabei die Funktionen dieser APIs zur Verarbeitung von Texttransformationen. Diese war zuvor über eine native SerializePropertyNamesAsCamelCaseAttribute-Klasse implementiert, für die es in der neuen Bibliothek kein Pendant gibt.

Zum Serialisieren von Eigenschaftsnamen in die CamelCase-Schreibweise können Sie das JsonPropertyNameAttribute verwenden (ähnlich wie in diesem Beispiel).

Alternativ dazu können Sie eine JsonNamingPolicy festlegen, die in JsonSerializerOptions angegeben ist. Das folgende System.Text.Json-Codebeispiel aus der Infodatei zu „Microsoft.Azure.Core.Spatial“ veranschaulicht die Verwendung von CamelCase, ohne für jede Eigenschaft Attribute angeben zu müssen:

// 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");

Wenn Sie Newtonsoft.Json für die JSON-Serialisierung verwenden, können Sie globale Benennungsrichtlinien mithilfe ähnlicher Attribute oder mithilfe von Eigenschaften in JsonSerializerSettings übergeben. Ein Beispiel entsprechend dem vorherigen finden Sie im Beispiel für die Deserialisierung von Dokumenten in der Newtonsoft.Json-Infodatei.

In v11

Jede Version einer Azure AI Search-Clientbibliothek ist auf eine entsprechende Version der REST-API ausgelegt. Die REST-API gilt als Basis für den Dienst, wobei einzelne SDKs eine Version der REST-API umschließen. Als .NET-Entwickler kann es hilfreich sein, die ausführlichere REST-API-Dokumentation zu lesen, um detailliertere Informationen zu bestimmten Objekten oder Vorgängen zu erhalten. Version 11 zielt auf die Suchdienstspezifikation 2020-06-30 ab.

Version 11.0 bietet vollständige Unterstützung für die folgenden Objekte und Vorgänge:

Indexerstellung und -verwaltung
Erstellung und Verwaltung von Synonymzuordnungen
Erstellung und Verwaltung von Indexern
Erstellung und Verwaltung von Indexerdatenquellen
Erstellung und Verwaltung von Skillsets
Alle Abfragetypen und Syntax

Ergänzungen zu Version 11.1 (Details zum Änderungsprotokoll):

FieldBuilder (in 11.1 hinzugefügt)
Serialisierungseigenschaft (in 11.1 hinzugefügt) zur Unterstützung der benutzerdefinierten Serialisierung

Ergänzungen zu Version 11.2 (Details zum Änderungsprotokoll):

Mit der EncryptionKey-Eigenschaft wurden Indexer, Datenquellen und Skillsets hinzugefügt.
Unterstützung für die Eigenschaft IndexingParameters.IndexingParametersConfiguration
Räumliche Typen werden in FieldBuilder nativ unterstützt. SearchFilter kann geometrische Typen aus „Microsoft.Spatial“ ohne explizite Assemblyabhängigkeit codieren.

Sie können auch weiterhin explizit die Abhängigkeit von Microsoft.Spatial deklarieren. Beispiele für dieses Verfahren sind für System.Text.Json und Newtonsoft.Json verfügbar.

Ergänzungen zu Version 11.3 (Details zum Änderungsprotokoll):

KnowledgeStore
Support für Azure.Core.GeoJson-Typen in SearchDocument,,SearchFilter und FieldBuilder wurde hinzugefügt.
EventSource-basierte Protokollierung wurde hinzugefügt. Der Name der Ereignisquelle ist Azure-Search-Documents. Die aktuelle Gruppe von Ereignissen konzentriert sich auf die Optimierung der Batchgrößen für SearchIndexingBufferedSender.
CustomEntityLookupSkill und und DocumentExtractionSkill wurden hinzugefügt. DefaultCountryHint wurde in LanguageDetectionSkill hinzugefügt.

Vor dem Upgrade

Schnellstarts, Tutorials und C#-Beispiele wurden aktualisiert, um das Azure.Search.Documents-Paket zu verwenden. Es wird empfohlen, dass Sie sich die Beispiele und exemplarischen Vorgehensweisen ansehen, um vor einer Migration mehr über die neuen APIs zu erfahren.
Im Artikel Verwenden von Azure.Search.Documents in einer in C# geschriebenen .NET-Anwendung werden die am häufigsten verwendeten APIs erläutert. Selbst Benutzer mit fundierten Kenntnissen im Zusammenhang mit Azure AI Search sollten diese Einführung in die neue Bibliothek als Vorstufe zur Migration lesen.

Schritte zum Upgrade

Mit den folgenden Schritten können Sie eine Codemigration beginnen, indem Sie die ersten erforderlichen Aufgaben durchgehen, insbesondere im Hinblick auf die Clientverweise.

Installieren Sie das Azure.Search.Documents-Paket, indem Sie mit der rechten Maustaste auf Ihre Projektreferenzen klicken und in Visual Studio „NuGet-Pakete verwalten...“ auswählen.

Ersetzen Sie die using-Anweisungen für Microsoft.Azure.Search durch die folgenden using-Anweisungen:

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

Ersetzen Sie für Klassen, die eine JSON-Serialisierung erfordern, using Newtonsoft.Json durch using System.Text.Json.Serialization.
Überarbeiten Sie den Authentifizierungscode für den Client. In früheren Versionen verwendeten Sie Eigenschaften im Clientobjekt, um den API-Schlüssel festzulegen (z. B. die SearchServiceClient.Credentials-Eigenschaft). In der aktuellen Version verwenden Sie die AzureKeyCredential-Klasse, um den Schlüssel als Anmeldeinformationen zu übergeben, sodass Sie bei Bedarf den API-Schlüssel aktualisieren können, ohne neue Clientobjekte zu erstellen.

Clienteigenschaften wurden (soweit möglich) auf Endpoint, ServiceName und IndexName optimiert. Im folgenden Beispiel wird die Uri-Systemklasse verwendet, um den Endpunkt anzugeben, und die Environment-Klasse, um den Schlüsselwert einzulesen:
```
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
```
Fügen Sie neue Clientverweise für indexerbezogene Objekte hinzu. Wenn Sie Indexer, Datenquellen oder Skillsets verwenden, ändern Sie die Clientverweise in SearchIndexerClient. Dieser Client ist in Version 11 neu und hat keine Vorgängerversion.
Überarbeiten Sie Sammlungen und Listen. Im neuen SDK sind alle Listen schreibgeschützt, um Downstreamprobleme zu vermeiden, wenn die Liste NULL-Werte enthält. Der Code muss so geändert werden, dass Elemente in eine Liste eingefügt werden. Anstatt beispielsweise einer Select-Eigenschaft Zeichenfolgen zuzuweisen, fügen Sie diese wie folgt hinzu:
```
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“ und „OrderBy“ sind jeweils Listen, die nun rekonstruiert werden müssen.
Aktualisieren Sie Clientverweise für Abfragen und Datenimport. Instanzen von SearchIndexClient müssen in SearchClient geändert werden. Stellen Sie sicher, dass Sie alle Instanzen abfangen, bevor Sie mit dem nächsten Schritt fortfahren, um Namensverwechslungen zu vermeiden.
Aktualisieren Sie Clientverweise für Index-, Synonymzuordnungs- und Analysetoolobjekte. Instanzen von SearchServiceClient müssen in SearchIndexClient geändert werden.
Aktualisieren Sie in Ihrem restlichen Code die Klassen, Methoden und Eigenschaften, um die APIs der neuen Bibliothek zu verwenden. Sie können mit dem Abschnitt Benennungsunterschiede beginnen oder auch das Änderungsprotokoll einsehen.

Wenn Sie Schwierigkeiten haben, entsprechende APIs zu finden, schlagen wir vor, ein Problem unter https://github.com/MicrosoftDocs/azure-docs/issues zu melden, damit wir die Dokumentation verbessern oder das Problem untersuchen können.
Erstellen Sie die Lösung neu. Wenn Sie alle Buildfehler bzw. Warnungen behoben haben, können Sie weitere Änderungen an Ihrer Anwendung vornehmen, um die neue Funktionalität zu nutzen.

Aktuelle Änderungen

Angesichts der tiefgreifenden Änderungen an Bibliotheken und APIs ist ein Upgrade auf Version 11 nicht trivial und stellt einen Breaking Change in der Hinsicht dar, dass Ihr Code nicht mehr abwärtskompatibel mit Version 10 und früheren Versionen ist. Eine ausführliche Übersicht über die Unterschiede finden Sie in dem Änderungsprotokoll für Azure.Search.Documents.

Hinsichtlich der Dienstversionsupdates, die Codeänderungen in Version 11 für vorhandene Funktionen (und nicht nur ein Refactoring der APIs) nach sich ziehen, treten die folgenden Verhaltensänderungen auf:

Der BM25-Ähnlichkeitsalgorithmus für die Rangfolge ersetzt den bisherigen Rangfolgealgorithmus durch neuere Technologie. Neue Dienste verwenden diesen Algorithmus automatisch. Für vorhandene Dienste müssen Sie Parameter festlegen, um den neuen Algorithmus zu verwenden.
Die Behandlung von Nullwerten in sortierten Ergebnissen hat sich in dieser Version geändert, Nullwerte werden bei asc-Sortierung zuerst und bei desc-Sortierung zuletzt angezeigt. Wenn Sie die Handhabung von Nullwerten in Code geschrieben haben, sollten Sie diesen überprüfen und möglicherweise entfernen, wenn er nicht mehr erforderlich ist.

Aufgrund dieser Verhaltensänderungen ist es wahrscheinlich, dass es geringfügige Abweichungen in Rangergebnissen gibt.

Freigeben über