Upgrade auf Azure Search .NET SDK, Version 9

Wenn Sie Version 7.0-Preview oder älter des Azure Search .NET SDK verwenden, hilft Ihnen dieser Artikel, Ihre Anwendung auf die Verwendung von Version 9 zu aktualisieren.

Eine allgemeinere exemplarische Vorgehensweise des SDK, einschließlich Beispiele, finden Sie unter Verwenden von Azure Search aus einer .NET-Anwendung.

Version 9 des Azure Search .NET SDK enthält viele Änderungen aus früheren Versionen. Einige dieser Änderungen sind inkompatibel, erfordern jedoch nur relativ geringfügige Anpassungen an Ihrem Code. Anweisungen zum Ändern des Codes zur Verwendung der neuen SDK-Version finden Sie in den Schritten zum Upgrade .

Neuerungen in Version 9

Version 9 des Azure Search .NET SDK zielt auf die Version 2019-05-06 der Azure Search-REST-API mit den folgenden Features ab:

• DIE KI-Anreicherung ist die Möglichkeit, Text aus Bildern, Blobs und anderen unstrukturierten Datenquellen zu extrahieren – die Inhalte bereichern, um sie in einem Azure Search-Index besser durchsuchbar zu machen.
• Die Unterstützung für komplexe Typen ermöglicht es Ihnen, nahezu jede geschachtelte JSON-Struktur in einem Azure Search-Index zu modellieren.
• AutoVervollständigen bietet eine Alternative zur Suggest-API zum Implementieren des Suchverhaltens während des Tippens. AutoVervollständigen "beendet" das Wort oder den Ausdruck, den ein Benutzer gerade eingibt.
• Der JsonLines-Analysemodus, Teil der BLOB-Indizierung, erstellt ein Suchdokument pro JSON-Entität, das durch eine Neueinline getrennt ist.

Neue Vorschaufeatures in Version 8.0-Preview

Version 8.0-Preview des Azure Search .NET SDK zielt auf API Version 2017-11-11-Preview ab. Diese Version enthält alle gleichen Features von Version 9, plus:

• Vom Kunden verwaltete Verschlüsselungsschlüssel für dienstseitige Verschlüsselung im Ruhezustand ist eine neue Vorschaufunktion. Zusätzlich zur integrierten Verschlüsselung im Ruhezustand, die von Microsoft verwaltet wird, können Sie eine zusätzliche Verschlüsselungsschicht anwenden, wobei Sie der alleinige Besitzer der Schlüssel sind.

Schritte zum Upgrade

Aktualisieren Sie zuerst Ihre NuGet-Referenz für Microsoft.Azure.Search, indem Sie entweder die NuGet-Paket-Manager-Konsole verwenden oder indem Sie mit der rechten Maustaste auf Ihre Projektverweise klicken und "NuGet-Pakete verwalten..." in Visual Studio auswählen.

Nachdem NuGet die neuen Pakete und ihre Abhängigkeiten heruntergeladen hat, erstellen Sie Ihr Projekt neu. Je nachdem, wie Ihr Code strukturiert ist, kann er erfolgreich neu erstellt werden. Wenn ja, sind Sie bereit loszulegen!

Wenn ihr Build fehlschlägt, müssen Sie jeden Buildfehler beheben. Ausführliche Informationen zum Beheben jedes potenziellen Buildfehlers finden Sie unter "Breaking Changes in Version 9".

Im Zusammenhang mit veralteten Methoden oder Eigenschaften können zusätzliche Build-Warnungen angezeigt werden. Die Warnungen enthalten Anweisungen dazu, was anstelle des veralteten Features verwendet werden soll. Wenn Ihre Anwendung beispielsweise die DataSourceType.DocumentDb Eigenschaft verwendet, sollten Sie eine Warnung mit der Meldung "Dieses Element ist veraltet" erhalten. Verwenden Sie stattdessen CosmosDb".

Nachdem Sie Buildfehler oder Warnungen behoben haben, können Sie Änderungen an Ihrer Anwendung vornehmen, um bei Bedarf neue Funktionen nutzen zu können. Neue Features im SDK sind in Version 9 ausführlich beschrieben.

Unterbrechen von Änderungen in Version 9

Es gibt mehrere wichtige Änderungen in Version 9, die möglicherweise Codeänderungen erfordern, zusätzlich zur Neuerstellung Der Anwendung.

Unveränderliche Eigenschaften

Die öffentlichen Eigenschaften mehrerer Modellklassen sind jetzt unveränderlich. Wenn Sie benutzerdefinierte Instanzen dieser Klassen zum Testen erstellen müssen, können Sie die neuen parametrisierten Konstruktoren verwenden:

• AutocompleteItem
• DocumentSearchResult
• DocumentSuggestResult
• FacetResult
• SearchResult
• SuggestResult

Änderungen am Feld

Die Field Klasse hat sich jetzt geändert, da sie auch komplexe Felder darstellen kann.

Die folgenden bool Eigenschaften können jetzt null sein:

• IsFilterable
• IsFacetable
• IsSearchable
• IsSortable
• IsRetrievable
• IsKey

Dies liegt daran, dass diese Eigenschaften im Fall komplexer Felder jetzt null sein müssen. Wenn Sie Code haben, der diese Eigenschaften liest, muss er für die Verarbeitung nullvorbereitet sein. Beachten Sie, dass alle anderen Eigenschaften von Field immer nullfähig waren und es auch bleiben. Im Fall komplexer Felder werden einige davon auch null sein, insbesondere die folgenden:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Der parameterlose Konstruktor von Field wurde internal gemacht. Ab sofort erfordert jeder Field zum Zeitpunkt der Konstruktion einen expliziten Namen und Datentyp.

Vereinfachte Batch- und Ergebnistypen

In Version 7.0-Preview und früheren Versionen wurden die verschiedenen Klassen, die Gruppen von Dokumenten kapseln, in parallele Klassenhierarchien strukturiert:

• DocumentSearchResult und DocumentSearchResult<T> geerbt von DocumentSearchResultBase
• DocumentSuggestResult und DocumentSuggestResult<T> geerbt von DocumentSuggestResultBase
• IndexAction und IndexAction<T> geerbt von IndexActionBase
• IndexBatch und IndexBatch<T> geerbt von IndexBatchBase
• SearchResult und SearchResult<T> geerbt von SearchResultBase
• SuggestResult und SuggestResult<T> geerbt von SuggestResultBase

Die abgeleiteten Typen ohne einen generischen Typparameter waren für den Einsatz in dynamisch typisierten Szenarien vorgesehen und setzten die Verwendung des Document Typs voraus.

Ab Version 8.0-Preview wurden alle Basisklassen und nicht generische abgeleitete Klassen entfernt. Für dynamisch typisierte Szenarien können Sie IndexBatch<Document>, DocumentSearchResult<Document> und so weiter verwenden.

ExtensibleEnum entfernt

Die ExtensibleEnum Basisklasse wurde entfernt. Alle von ihr abgeleiteten Klassen sind jetzt Strukturen, wie AnalyzerName, DataType und DataSourceType beispielsweise. Ihre Create Methoden wurden ebenfalls entfernt. Sie können die Aufrufe von Create einfach entfernen, da diese Typen implizit aus Zeichenfolgen konvertierbar sind. Wenn dies zu Compilerfehlern führt, können Sie den Konvertierungsoperator explizit durch Typumwandlung aufrufen, um Typen zu unterscheiden. Sie können z. B. Code wie folgt ändern:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", AnalyzerName.Create("my_email_analyzer")) { IsSearchable = true }
    },
    ...
}

zu diesem:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", (AnalyzerName)"my_email_analyzer") { IsSearchable = true }
    },
    ...
}

Eigenschaften, die optionale Werte dieser Typen enthalten, werden jetzt explizit als NULL-Werte eingegeben, sodass sie weiterhin optional sind.

FacetResults und HitHighlights entfernt

Die FacetResults Klassen wurden HitHighlights entfernt. Facet-Ergebnisse werden jetzt als IDictionary<string, IList<FacetResult>> Hervorhebungen eingegeben und treffert als IDictionary<string, IList<string>>. Eine schnelle Möglichkeit zum Beheben von Buildfehlern, die durch diese Änderung eingeführt wurden, ist das Hinzufügen using von Aliasen am Anfang jeder Datei, die die entfernten Typen verwendet. Beispiel:

using FacetResults = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<Models.FacetResult>>;
using HitHighlights = System.Collections.Generic.IDictionary<string, System.Collections.Generic.IList<string>>;

In SynonymMap ändern

Der SynonymMap Konstruktor verfügt nicht mehr über einen enum Parameter für SynonymMapFormat. Dieses Enum hatte nur einen Wert und war daher redundant. Wenn Buildfehler als Ergebnis dieser Fehlermeldungen angezeigt werden, entfernen Sie einfach Verweise auf den SynonymMapFormat Parameter.

Verschiedene Modellklassenänderungen

Die AutocompleteMode Eigenschaft von AutocompleteParameters ist nicht mehr nullfähig. Wenn Sie Code haben, der diese Eigenschaft nullzuweist, können Sie sie einfach entfernen und die Eigenschaft wird automatisch auf den Standardwert initialisiert.

Die Reihenfolge der Parameter für den IndexAction Konstruktor hat sich geändert, da dieser Konstruktor automatisch generiert wird. Anstatt den Konstruktor zu verwenden, empfehlen wir die Verwendung der Factorymethoden IndexAction.Upload, IndexAction.Mergeusw.

Entfernte Vorschaufeatures

Wenn Sie ein Upgrade von Version 8.0-Preview auf Version 9 durchführen, beachten Sie, dass die Verschlüsselung mit vom Kunden verwalteten Schlüsseln entfernt wurde, da sich dieses Feature noch in der Vorschau befindet. Insbesondere wurden die EncryptionKey Eigenschaften von Index und SynonymMap entfernt.

Wenn Ihre Anwendung eine harte Abhängigkeit von diesem Feature hat, können Sie kein Upgrade auf Version 9 des Azure Search .NET SDK durchführen. Sie können weiterhin Version 8.0-Preview verwenden. Beachten Sie jedoch, dass wir die Verwendung von Vorschau-SDKs in Produktionsanwendungen nicht empfehlen. Vorschaufeatures dienen nur zur Auswertung und können sich ändern.

Verhaltensänderung beim Datenempfang

Wenn Sie die "dynamisch typisiert" Searchoder GetSuggestAPIs verwenden, die Instanzen vom Typ Documentzurückgeben, beachten Sie, dass sie jetzt leere JSON-Arrays object[] anstelle von string[].

Schlussfolgerung

Wenn Sie weitere Details zur Verwendung des Azure Search .NET SDK benötigen, lesen Sie .NET How-to.

Wir freuen uns über Ihr Feedback zum SDK. Wenn Sie Probleme haben, bitten Sie uns gerne um Hilfe zu Stack Overflow. Wenn Sie einen Fehler finden, können Sie das Problem im Azure .NET SDK-GitHub-Repositorymelden. Stellen Sie sicher, dass Sie den Titel Ihres Problems mit "[Azure Search]" beginnen.

Vielen Dank für die Verwendung von Azure Search!