Dela via

Uppgradera till Azure Search .NET SDK version 9

  • Artikel

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 så att det använder version 9.

Anteckning

Om du vill använda version 8.0-preview för att utvärdera funktioner som inte är allmänt tillgängliga ännu kan du också följa anvisningarna i den här artikeln för att uppgradera till 8.0-förhandsversion från tidigare versioner.

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 icke-bakåtkompatibla ändringar, men de bör bara kräva relativt små ändringar i koden. Se Steg för att uppgradera för instruktioner om hur du ändrar din kod för att använda den nya SDK-versionen.

Anteckning

Om du använder version 4.0-preview eller äldre bör du först uppgradera till version 5 och sedan uppgradera till version 9. Instruktioner finns i Uppgradera till Azure Search .NET SDK version 5 .

Din Azure tjänsten Search-instans stöder flera REST API-versioner, inklusive den senaste. Du kan fortsätta att använda en version när den inte längre är den senaste, men vi rekommenderar att du migrerar koden för att använda den senaste versionen. När du använder REST-API:et måste du ange API-versionen i varje begäran via parametern api-version. När du använder .NET SDK avgör vilken version av SDK du använder motsvarande version av REST-API:et. Om du använder en äldre SDK kan du fortsätta att köra koden utan ändringar även om tjänsten uppgraderas för att stödja en nyare API-version.

Nyheter i version 9

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

  • AI-berikning är möjligheten att extrahera text från bilder, blobbar och andra ostrukturerade datakällor – berika 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 suggest-API :et för implementering av beteendet search-as-you-type. Komplettera automatiskt "avslutar" det ord eller den fras som en användare för närvarande skriver.
  • JsonLines parsningsläge, en del av blobindexering, skapar ett sökdokument per JSON-entitet som avgränsas med en ny rad.

Nya förhandsgranskningsfunktioner 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 samma funktioner i version 9, plus:

  • Kundhanterade krypteringsnycklar för kryptering på tjänstsidan i vila är en ny förhandsversionsfunktion. 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 att antingen använda 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. I så fall är du redo att gå!

Om bygget misslyckas måste du åtgärda varje byggfel. Se Icke-bakåtkompatibla ändringar i version 9 för mer information om hur du löser varje potentiellt byggfel.

Du kan se ytterligare build-varningar relaterade till föråldrade metoder eller egenskaper. Varningarna innehåller instruktioner om vad som ska användas 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.

Icke-bakåtkompatibla ändringar i version 9

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

Anteckning

Listan över ändringar nedan är inte uttömmande. Vissa ändringar resulterar sannolikt inte i byggfel, men är tekniskt felaktiga eftersom de bryter binär kompatibilitet med sammansättningar som är beroende av tidigare versioner av Azure Search .NET SDK-sammansättningar. Sådana ändringar visas inte nedan. Återskapa programmet när du uppgraderar till version 9 för att undvika eventuella problem med binär kompatibilitet.

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 även kan representera komplexa fält.

Följande bool egenskaper kan nu ha värdet null:

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

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

  • Analyzer
  • SearchAnalyzer
  • IndexAnalyzer
  • SynonymMaps

Den parameterlösa konstruktorn Field för 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-preview och tidigare var de olika klasser som kapslar in grupper av dokument strukturerade i parallella klasshierarkier:

  • DocumentSearchResult och DocumentSearchResult<T> ärvts från DocumentSearchResultBase
  • DocumentSuggestResult och DocumentSuggestResult<T> ärvts från DocumentSuggestResultBase
  • IndexAction och IndexAction<T> ärvts från IndexActionBase
  • IndexBatch och IndexBatch<T> ärvts från IndexBatchBase
  • SearchResult och SearchResult<T> ärvts från SearchResultBase
  • SuggestResult och SuggestResult<T> ärvts 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 alla basklasser och icke-generiska härledda klasser tagits bort. För dynamiskt typade 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 . Deras Create metoder har också tagits bort. Du kan bara ta bort anrop till Create eftersom dessa typer implicit kan konverteras från strängar. Om det resulterar i kompilatorfel kan du uttryckligen anropa konverteringsoperatorn via omvandling för att skilja typerna åt. 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 denna:

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öll 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. Fasetterade resultat skrivs nu som IDictionary<string, IList<FacetResult>> och träffar hö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. 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 SynonymMappa

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 redundant. Om du ser build-fel som ett resultat av detta tar du bara bort referenser till parametern SynonymMapFormat .

Diverse ändringar i modellklassen

Egenskapen AutocompleteModeAutocompleteParameters för kan inte längre vara null. Om du har kod som tilldelar den här egenskapen till nullkan du helt enkelt ta bort den så initieras egenskapen 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 Index för EncryptionKey och SynonymMap tagits bort.

Om ditt program är beroende av den här funktionen kommer du inte att kunna 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 till för utvärdering och kan ändras.

Anteckning

Om du har skapat krypterade index eller synonymkartor med version 8.0-förhandsversionen av SDK:t kommer du fortfarande att kunna använda dem och ändra deras definitioner med version 9 av SDK:t utan att krypteringsstatusen påverkas negativt. Version 9 av SDK skickar encryptionKey inte egenskapen till REST-API:et och därför ändrar INTE REST-API:et resursens krypteringsstatus.

Beteendeförändring vid datahämtning

Om du använder api:erna "dynamiskt inskrivna" Search, Suggesteller som Get returnerar instanser av typen Documentbör du vara medveten om att de nu deserialiserar tomma JSON-matriser till i stället för object[]string[].

Slutsats

Mer information om hur du använder Azure Search .NET SDK finns i instruktioner för .NET.

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

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