Delen via

Upgrade uitvoeren naar Azure Search .NET SDK versie 9

  • Artikel

Als u versie 7.0 of ouder van de Azure Search .NET SDK gebruikt, helpt dit artikel u bij het upgraden van uw toepassing om versie 9 te gebruiken.

Notitie

Als u versie 8.0-preview wilt gebruiken om functies te evalueren die nog niet algemeen beschikbaar zijn, kunt u ook de instructies in dit artikel volgen om een upgrade uit te voeren naar 8.0 preview van eerdere versies.

Zie Azure Search gebruiken vanuit een .NET-toepassing voor een algemeen overzicht van de SDK, inclusief voorbeelden.

Versie 9 van de Azure Search .NET SDK bevat veel wijzigingen uit eerdere versies. Sommige van deze wijzigingen zijn belangrijke wijzigingen, maar ze moeten alleen relatief kleine wijzigingen in uw code vereisen. Zie Stappen voor het upgraden voor instructies over het wijzigen van uw code voor het gebruik van de nieuwe SDK-versie.

Notitie

Als u versie 4.0-preview of ouder gebruikt, moet u eerst upgraden naar versie 5 en vervolgens upgraden naar versie 9. Zie Upgraden naar azure Search .NET SDK versie 5 voor instructies.

Uw Azure Search-service-exemplaar ondersteunt verschillende REST API-versies, waaronder de nieuwste versie. U kunt een versie blijven gebruiken wanneer deze niet langer de nieuwste versie is, maar u wordt aangeraden uw code te migreren om de nieuwste versie te gebruiken. Wanneer u de REST API gebruikt, moet u de API-versie in elke aanvraag opgeven via de parameter api-versie. Wanneer u de .NET SDK gebruikt, bepaalt de versie van de SDK die u gebruikt de bijbehorende versie van de REST API. Als u een oudere SDK gebruikt, kunt u die code zonder wijzigingen blijven uitvoeren, zelfs als de service wordt bijgewerkt om een nieuwere API-versie te ondersteunen.

Nieuw in versie 9

Versie 9 van de Azure Search .NET SDK is gericht op 2019-05-06-versie van Azure Search REST API, met de volgende functies:

  • AI-verrijking is de mogelijkheid om tekst te extraheren uit afbeeldingen, blobs en andere ongestructureerde gegevensbronnen: de inhoud verrijken om deze beter doorzoekbaar te maken in een Azure Search-index.
  • Met ondersteuning voor complexe typen kunt u vrijwel elke geneste JSON-structuur modelleren in een Azure Search-index.
  • Automatisch aanvullen biedt een alternatief voor de Suggestie-API voor het implementeren van het gedrag van search-as-you-type. Het woord of de woordgroep die een gebruiker momenteel typt, wordt automatisch aangevuld.
  • JsonLines parseringsmodus, onderdeel van blobindexering, maakt één zoekdocument per JSON-entiteit die wordt gescheiden door een nieuwe regel.

Nieuwe preview-functies in versie 8.0-preview

Versie 8.0-preview van de Azure Search .NET SDK is gericht op API-versie 2017-11-11-Preview. Deze versie bevat dezelfde functies van versie 9, plus:

Stappen om een upgrade uit te voeren

Werk eerst uw NuGet-verwijzing bij voor Microsoft.Azure.Search het gebruik van de NuGet Pakketbeheer Console of door met de rechtermuisknop op uw projectverwijzingen te klikken en NuGet-pakketten beheren te selecteren... in Visual Studio.

Zodra NuGet de nieuwe pakketten en hun afhankelijkheden heeft gedownload, bouwt u uw project opnieuw. Afhankelijk van hoe uw code is gestructureerd, kan deze opnieuw worden opgebouwd. Zo ja, dan ben je klaar om te gaan!

Als uw build mislukt, moet u elke buildfout oplossen. Zie Belangrijke wijzigingen in versie 9 voor meer informatie over het oplossen van elke mogelijke buildfout.

Mogelijk ziet u aanvullende buildwaarschuwingen met betrekking tot verouderde methoden of eigenschappen. De waarschuwingen bevatten instructies voor wat u moet gebruiken in plaats van de afgeschafte functie. Als uw toepassing bijvoorbeeld de DataSourceType.DocumentDb eigenschap gebruikt, krijgt u een waarschuwing met de tekst 'Dit lid is afgeschaft.' Gebruik in plaats daarvan CosmosDb.

Zodra u buildfouten of waarschuwingen hebt opgelost, kunt u desgewenst wijzigingen aanbrengen in uw toepassing om te profiteren van nieuwe functionaliteit. Nieuwe functies in de SDK worden beschreven in Wat is er nieuw in versie 9.

Belangrijke wijzigingen in versie 9

Er zijn verschillende belangrijke wijzigingen in versie 9 die mogelijk codewijzigingen vereisen, naast het opnieuw samenstellen van uw toepassing.

Notitie

De onderstaande lijst met wijzigingen is niet volledig. Sommige wijzigingen leiden waarschijnlijk niet tot buildfouten, maar zijn technisch belangrijk omdat ze binaire compatibiliteit met assembly's verbreken die afhankelijk zijn van eerdere versies van de .NET SDK-assembly's van Azure Search. Dergelijke wijzigingen worden hieronder niet vermeld. Bouw uw toepassing opnieuw wanneer u een upgrade uitvoert naar versie 9 om binaire compatibiliteitsproblemen te voorkomen.

Onveranderbare eigenschappen

De openbare eigenschappen van verschillende modelklassen zijn nu onveranderbaar. Als u aangepaste exemplaren van deze klassen wilt maken om te testen, kunt u de nieuwe geparameteriseerde constructors gebruiken:

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

Wijzigingen in veld

De Field klasse is gewijzigd nu deze ook complexe velden kan vertegenwoordigen.

De volgende bool eigenschappen zijn nu null-waarde:

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

Dit komt omdat deze eigenschappen nu moeten zijn null in het geval van complexe velden. Als u code hebt die deze eigenschappen leest, moet deze worden voorbereid om af te handelen null. Houd er rekening mee dat alle andere eigenschappen van Field altijd en blijven null-able zijn, en sommige van deze eigenschappen zullen ook in het geval van complexe velden zijn null , met name het volgende:

  • Analyzer
  • SearchAnalyzer
  • IndexAnalyzer
  • SynonymMaps

De parameterloze constructor van Field is gemaakt internal. Vanaf nu vereist elk Field een expliciete naam en een gegevenstype op het moment van de bouw.

Vereenvoudigde batch- en resultatentypen

In versie 7.0 en eerder zijn de verschillende klassen die groepen documenten inkapselen, gestructureerd in parallelle klassenhiërarchieën:

  • DocumentSearchResult overgenomen DocumentSearchResult<T> van DocumentSearchResultBase
  • DocumentSuggestResult overgenomen DocumentSuggestResult<T> van DocumentSuggestResultBase
  • IndexAction overgenomen IndexAction<T> van IndexActionBase
  • IndexBatch overgenomen IndexBatch<T> van IndexBatchBase
  • SearchResult overgenomen SearchResult<T> van SearchResultBase
  • SuggestResult overgenomen SuggestResult<T> van SuggestResultBase

De afgeleide typen zonder een algemene typeparameter zijn bedoeld voor gebruik in 'dynamisch getypte' scenario's en gaan ervan uit dat het gebruik van het Document type wordt gebruikt.

Vanaf versie 8.0 preview zijn de basisklassen en niet-algemene afgeleide klassen allemaal verwijderd. Voor dynamisch getypte scenario's kunt u , DocumentSearchResult<Document>enzovoort, gebruikenIndexBatch<Document>.

ExtensibleEnum verwijderd

De ExtensibleEnum basisklasse is verwijderd. Alle klassen die hiervan zijn afgeleid, zijn nu structs, zoals AnalyzerNameDataType, en DataSourceType bijvoorbeeld. Hun Create methoden zijn ook verwijderd. U kunt alleen aanroepen Create verwijderen omdat deze typen impliciet converteerbaar zijn uit tekenreeksen. Als dat resulteert in compilerfouten, kunt u de conversieoperator expliciet aanroepen via casten om verschillende typen niet duidelijk te maken. U kunt bijvoorbeeld code als volgt wijzigen:

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

in deze:

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

Eigenschappen die optionele waarden van deze typen bevatten, worden nu expliciet getypt als nullable, zodat ze optioneel blijven.

FacetResults en HitHighlights verwijderd

De FacetResults en HitHighlights klassen zijn verwijderd. Facetresultaten worden nu getypt als IDictionary<string, IList<FacetResult>> en worden gemarkeerd als IDictionary<string, IList<string>>. Een snelle manier om buildfouten op te lossen die door deze wijziging zijn geïntroduceerd, is het toevoegen using van aliassen boven aan elk bestand dat gebruikmaakt van de verwijderde typen. Bijvoorbeeld:

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

Wijzigen in SynonymMap

De SynonymMap constructor heeft enum geen parameter meer voor SynonymMapFormat. Deze opsomming had slechts één waarde en was daarom redundant. Als u als gevolg hiervan buildfouten ziet, verwijdert u gewoon verwijzingen naar de SynonymMapFormat parameter.

Diverse wijzigingen in modelklassen

De AutocompleteMode eigenschap van AutocompleteParameters is niet meer nullable. Als u code hebt waaraan deze eigenschap nullwordt toegewezen, kunt u deze gewoon verwijderen en wordt de eigenschap automatisch geïnitialiseerd op de standaardwaarde.

De volgorde van de parameters voor de IndexAction constructor is gewijzigd nu deze constructor automatisch wordt gegenereerd. In plaats van de constructor te gebruiken, raden we u aan de fabrieksmethoden IndexAction.UploadIndexAction.Mergete gebruiken, enzovoort.

Preview-functies verwijderd

Als u een upgrade uitvoert van versie 8.0-preview naar versie 9, moet u er rekening mee houden dat versleuteling met door de klant beheerde sleutels is verwijderd omdat deze functie nog in preview is. Met name de EncryptionKey eigenschappen van Index en SynonymMap zijn verwijderd.

Als uw toepassing een vaste afhankelijkheid van deze functie heeft, kunt u geen upgrade uitvoeren naar versie 9 van de Azure Search .NET SDK. U kunt versie 8.0-preview blijven gebruiken. Houd er echter rekening mee dat we het gebruik van preview-SDK's in productietoepassingen niet aanbevelen. Preview-functies zijn alleen bedoeld voor evaluatie en kunnen worden gewijzigd.

Notitie

Als u versleutelde indexen of synoniementoewijzingen hebt gemaakt met versie 8.0-preview van de SDK, kunt u deze nog steeds gebruiken en hun definities wijzigen met versie 9 van de SDK zonder dat dit de versleutelingsstatus nadelig beïnvloedt. Versie 9 van de SDK verzendt de encryptionKey eigenschap niet naar de REST API. Hierdoor wordt de versleutelingsstatus van de resource niet gewijzigd door de REST API.

Gedragswijziging bij het ophalen van gegevens

Als u de 'dynamisch getypte' Searchof API's gebruikt die exemplaren van het type Documentretourneren, moet u er rekening mee houden dat ze nu lege JSON-matrices deserialiseren naar object[] in plaats van string[].GetSuggest

Conclusie

Als u meer informatie nodig hebt over het gebruik van de .NET SDK voor Azure Search, raadpleegt u de instructies voor .NET.

We verwelkomen uw feedback over de SDK. Als u problemen ondervindt, kunt u ons vragen om hulp op Stack Overflow. Als u een fout vindt, kunt u een probleem indienen in de Azure .NET SDK GitHub opslagplaats. Zorg ervoor dat u de titel van het probleem voorafzet met [Azure Search].

Bedankt voor het gebruik van Azure Search!