Uppgradera till Azure Search .NET SDK version 9

Om du använder version 7.0-preview eller äldre av Azure Search .NET SDK hjälper den här artikeln dig att uppgradera ditt program till att använda version 9.

En mer allmän genomgång av SDK inklusive exempel finns i Så här använder du Azure Search från ett .NET-program.

Version 9 av Azure Search .NET SDK innehåller många ändringar från tidigare versioner. Vissa av dessa är stora ändringar, men de bör bara kräva relativt små ändringar i din kod. Se Steg för att uppgradera för instruktioner om hur du ändrar din kod för att använda den nya SDK-versionen.

Nyheter i version 9

Version 9 av Azure Search .NET SDK riktar sig mot 2019-05-06-versionen av Azure Search REST API med följande funktioner:

• AI-berikande är möjligheten att extrahera text från bilder, blobbar och andra ostrukturerade datakällor – vilket berikar innehållet så att det blir mer sökbart i ett Azure Search-index.
• Med stöd för komplexa typer kan du modellera nästan alla kapslade JSON-strukturer i ett Azure Search-index.
• Automatisk komplettering är ett alternativ till api:et Föreslå för implementering av beteendet search-as-you-type. Autokomplettering "avslutar" ordet eller frasen som en användare håller på att skriva.
• JsonLines parsningsläge, en del av blobindexering, skapar ett sökdokument per JSON-entitet som avgränsas med en ny rad.

Nya förhandsversionsfunktioner i version 8.0-preview

Version 8.0-preview av Azure Search .NET SDK riktar sig mot API version 2017-11-11-Preview. Den här versionen innehåller alla samma funktioner i version 9, plus:

• Kundhanterade krypteringsnycklar för kryptering av vilande data på tjänstsidan är en ny förhandsgranskningsfunktion. Förutom den inbyggda kryptering i vila som hanteras av Microsoft kan du använda ytterligare ett krypteringslager där du är ensam ägare till nycklarna.

Steg för att uppgradera

Uppdatera först NuGet-referensen för Microsoft.Azure.Search antingen med NuGet Package Manager-konsolen eller genom att högerklicka på dina projektreferenser och välja "Hantera NuGet-paket..." i Visual Studio.

När NuGet har laddat ned de nya paketen och deras beroenden återskapar du projektet. Beroende på hur koden är strukturerad kan den återskapas framgångsrikt. I så fall är du redo att gå!

Om bygget misslyckas måste du åtgärda varje byggfel. Se Breaking changes i version 9 för detaljer om hur du löser varje potentiellt byggfel.

Du kan se ytterligare byggvarningar relaterade till föråldrade metoder eller egenskaper. Varningarna innehåller instruktioner om vad du ska använda i stället för den inaktuella funktionen. Om ditt program till exempel använder DataSourceType.DocumentDb egenskapen bör du få en varning om att "Den här medlemmen är inaktuell. Använd CosmosDb i stället".

När du har åtgärdat eventuella byggfel eller varningar kan du göra ändringar i ditt program för att dra nytta av nya funktioner om du vill. Nya funktioner i SDK beskrivs i Nyheter i version 9.

Okompatibla ändringar i version 9

Det finns flera icke-bakåtkompatibla ändringar i version 9 som kan kräva kodändringar utöver att återskapa din applikation.

Oföränderliga egenskaper

De offentliga egenskaperna för flera modellklasser är nu oföränderliga. Om du behöver skapa anpassade instanser av dessa klasser för testning kan du använda de nya parametriserade konstruktorerna:

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

Ändringar i fält

Klassen Field har ändrats nu när den också kan representera komplexa fält.

Följande bool egenskaper kan nu vara null:

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

Detta beror på att dessa egenskaper nu måste vara null när det gäller komplexa fält. Om du har kod som läser dessa egenskaper måste den vara beredd att hantera null. Observera att alla andra egenskaper Field för alltid har varit och fortsätter att vara nullbara, och vissa av dessa kommer också att gälla null för komplexa fält – särskilt följande:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Den parameterlösa konstruktorn Field har gjorts internal. Från och med nu kräver varje Field explicit namn och datatyp vid tidpunkten för konstruktionen.

Förenklade batch- och resultattyper

I version 7.0-förhandsversion och tidigare var de olika klasser som kapslar in grupper av dokument strukturerade i parallella klasshierarkier:

• DocumentSearchResult och DocumentSearchResult<T> ärvda från DocumentSearchResultBase
• DocumentSuggestResult och DocumentSuggestResult<T> ärvda från DocumentSuggestResultBase
• IndexAction och IndexAction<T> ärvda från IndexActionBase
• IndexBatch och IndexBatch<T> ärvda från IndexBatchBase
• SearchResult och SearchResult<T> ärvda från SearchResultBase
• SuggestResult och SuggestResult<T> ärvda från SuggestResultBase

De härledda typerna utan en generisk typparameter var avsedda att användas i "dynamiskt skrivna" scenarier och antog användning av Document typen.

Från och med version 8.0-preview har basklasserna och icke-generiska härledda klasser tagits bort. För dynamiskt skrivna scenarier kan du använda IndexBatch<Document>, DocumentSearchResult<Document>och så vidare.

ExtensibleEnum har tagits bort

Basklassen ExtensibleEnum har tagits bort. Alla klasser som härleds från den är nu structs, till exempel AnalyzerName, DataTypeoch DataSourceType till exempel. Deras Create metoder har också tagits bort. Du kan bara ta bort anrop till Create eftersom dessa typer kan konverteras implicit från strängar. Om det resulterar i kompilatorfel kan du uttryckligen anropa konverteringsoperatorn genom att kasta för att lösa upp tvetydigheter av typer. Du kan till exempel ändra kod så här:

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

till detta:

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

Egenskaper som innehåller valfria värden för dessa typer skrivs nu uttryckligen som nullbara så att de fortsätter att vara valfria.

FacetResults och HitHighlights har tagits bort

Klasserna FacetResults och HitHighlights har tagits bort. Resultat för facetter skrivs nu som IDictionary<string, IList<FacetResult>> och träffhöjdpunkter som IDictionary<string, IList<string>>. Ett snabbt sätt att lösa byggfel som introduceras genom den här ändringen är att lägga using till alias överst i varje fil som använder de borttagna typerna. Till exempel:

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>>;

Ändra till SynonymMap

Konstruktorn SynonymMap har inte längre en enum parameter för SynonymMapFormat. Den här uppräkningen hade bara ett värde och var därför onödig. Om du ser byggfel som ett resultat av detta tar du helt enkelt bort referenser till parametern SynonymMapFormat .

Diverse ändringar i modellklassen

Egenskapen AutocompleteMode för AutocompleteParameters är inte längre nullbar. Om du har kod som tilldelar den här egenskapen till nullkan du helt enkelt ta bort den och egenskapen initieras automatiskt till standardvärdet.

Ordningen på parametrarna IndexAction till konstruktorn har ändrats nu när konstruktorn genereras automatiskt. I stället för att använda konstruktorn rekommenderar vi att du använder fabriksmetoderna IndexAction.Upload, IndexAction.Mergeoch så vidare.

Förhandsgranskningsfunktioner har tagits bort

Om du uppgraderar från version 8.0-preview till version 9 bör du vara medveten om att kryptering med kundhanterade nycklar har tagits bort eftersom den här funktionen fortfarande är i förhandsversion. Mer specifikt har egenskaperna EncryptionKey för Index och SynonymMap tagits bort.

Om ditt program har ett hårt beroende av den här funktionen kan du inte uppgradera till version 9 av Azure Search .NET SDK. Du kan fortsätta att använda version 8.0-preview. Tänk dock på att vi inte rekommenderar att du använder förhandsversions-SDK:er i produktionsprogram. Förhandsversionsfunktioner är endast för utvärdering och kan ändras.

Beteendeförändring vid datahämtning

Om du använder de "dynamiskt typade" API:c0 />, Search, eller Suggest som returnerar instanser av typen Get, bör du tänka på att de nu deserialiserar tomma JSON-matriser till Document i stället för object[].

Slutsats

Om du behöver mer information om hur du använder Azure Search .NET SDK kan du läsa .NET-instruktioner.

Vi välkomnar din feedback om SDK:et. Om du stöter på problem kan du be oss om hjälp med Stack Overflow. Om du hittar en bugg kan du skapa ett problem på GitHub-lagringsplatsen för Azure .NET SDK. Se till att du lägger till prefixet "[Azure Search]" i problemrubriken.

Tack för att du använder Azure Search!