Upgrade uitvoeren naar Azure Search .NET SDK versie 9

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.

Zie Azure Search gebruiken vanuit een .NET-toepassingvoor 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 van voor instructies over het wijzigen van uw code voor het gebruik van de nieuwe SDK-versie.

Wat is er 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 het type Search-as-you. Automatisch aanvullen 'voltooit' het woord of de woordgroep die een gebruiker momenteel typt.
• 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:

• Door klanten beheerde versleutelingssleutels voor versleuteling in rusttoestand aan de servicezijde is een nieuwe preview-versie. Naast de ingebouwde versleuteling-at-rest die wordt beheerd door Microsoft, kunt u een extra versleutelingslaag toepassen waarbij u de enige eigenaar van de sleutels bent.

Stappen voor het upgraden

Werk eerst uw NuGet-verwijzing voor Microsoft.Azure.Search bij met behulp van de NuGet Package Manager-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 op. 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 extra buildwaarschuwingen met betrekking tot verouderde methoden of eigenschappen. De waarschuwingen bevatten instructies over wat u moet gebruiken in plaats van de afgeschafte functie. Als uw toepassing bijvoorbeeld gebruikmaakt van de DataSourceType.DocumentDb eigenschap, 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 wijzigingen aanbrengen in uw toepassing om te profiteren van nieuwe functionaliteit als u dat wilt. Nieuwe functies in de SDK worden beschreven in wat er nieuw is in versie 9.

Belangrijke wijzigingen in versie 9

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

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 het veld

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

De volgende bool eigenschappen zijn nu nullable:

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

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

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

De parameterloze constructor van Field is internal gemaakt. Vanaf nu vereist elk Field een expliciete naam en 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 en DocumentSearchResult<T> overgenomen van DocumentSearchResultBase
• DocumentSuggestResult en DocumentSuggestResult<T> overgenomen van DocumentSuggestResultBase
• IndexAction en IndexAction<T> overgenomen van IndexActionBase
• IndexBatch en IndexBatch<T> overgenomen van IndexBatchBase
• SearchResult en SearchResult<T> overgenomen van SearchResultBase
• SuggestResult en SuggestResult<T> overgenomen van SuggestResultBase

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

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

ExtensibleEnum verwijderd

De ExtensibleEnum basisklasse is verwijderd. Alle klassen die ermee zijn afgeleid, zijn nu structs, zoals AnalyzerName, DataTypeen DataSourceType bijvoorbeeld. Hun Create methoden zijn ook verwijderd. U kunt de aanroepen van Create gewoon verwijderen aangezien deze typen impliciet converteerbaar zijn van tekenreeksen. Als dit resulteert in compilerfouten, kunt u de conversieoperator expliciet aanroepen door gebruik te maken van casting om typen te onderscheiden. 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 }
    },
    ...
}

naar dit:

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 door boven aan elk bestand aliassen toe te voegen using dat gebruikmaakt van de verwijderde typen. Voorbeeld:

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 naar SynonymMap

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

Wijzigingen in diverse 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.Uploadte gebruiken, IndexAction.Mergeenzovoort.

Preview-functies verwijderd

Als u een upgrade uitvoert van versie 8.0 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 harde afhankelijkheid van deze functie heeft, kunt u geen upgrade uitvoeren naar versie 9 van de .NET SDK van Azure Search. U kunt versie 8.0-preview blijven gebruiken. Houd er echter rekening mee dat we geen preview-SDK's in productietoepassingengebruiken. Preview-functies zijn alleen bedoeld voor evaluatie en kunnen worden gewijzigd.

Gedragswijziging bij het ophalen van gegevens

Als u de 'dynamisch getypte' Searchof SuggestGet 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[].

Conclusie

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

We verwelkomen uw feedback over de SDK. Als u problemen ondervindt, kunt u ons vragen om hulp bij Stack Overflow-. Als u een fout vindt, kunt u een probleem indienen in de GitHub-opslagplaats van de Azure .NET SDK. Zorg ervoor dat u uw probleemtitel laat voorafgaan door "[Azure Search]".

Bedankt voor het gebruik van Azure Search.