Upgrade uitvoeren naar Azure AI Search .NET SDK versie 11

Als uw zoekoplossing is gebouwd op de Azure SDK voor .NET, helpt dit artikel u bij het migreren van uw code van eerdere versies van Microsoft.Azure.Search naar versie 11, de nieuwe Azure.Search.Documents-clientbibliotheek. Versie 11 is een volledig opnieuw ontworpen clientbibliotheek, uitgebracht door het Azure SDK-ontwikkelteam (vorige versies zijn geproduceerd door het Azure AI Search-ontwikkelteam).

Alle functies van versie 10 worden geïmplementeerd in versie 11. Belangrijke verschillen zijn onder andere:

• Eén pakket (Azure.Search.Documents) in plaats van vier
• Drie clients in plaats van twee: SearchClient, SearchIndexClient, SearchIndexerClient
• Naamgevingsverschillen tussen verschillende API's en kleine structurele verschillen die sommige taken vereenvoudigen

Het wijzigingenlogboek van de clientbibliotheek bevat een geitemiseerde lijst met updates. U kunt een samengevatte versie in dit artikel bekijken.

Alle C#-codevoorbeelden en -fragmenten in de Azure AI Search-productdocumentatie zijn herzien om de nieuwe Azure.Search.Documents-clientbibliotheek te gebruiken.

Waarom upgraden?

De voordelen van een upgrade worden als volgt samengevat:

• Nieuwe functies worden alleen toegevoegd aan Azure.Search.Documents . De vorige versie, Microsoft.Azure.Search, is nu buiten gebruik gesteld. Updates voor afgeschafte bibliotheken zijn alleen beperkt tot oplossingen voor problemen met hoge prioriteit.

• Consistentie met andere Azure-clientbibliotheken. Azure.Search.Documents heeft een afhankelijkheid van Azure.Core en System.Text.Json en volgt conventionele benaderingen voor veelvoorkomende taken, zoals clientverbindingen en autorisatie.

Microsoft.Azure.Search is officieel buiten gebruik gesteld. Als u een oude versie gebruikt, raden we u aan een upgrade uit te voeren naar de volgende hogere versie, waarbij het proces na elkaar wordt herhaald totdat u versie 11 en Azure.Search.Documents hebt bereikt. Een incrementele upgradestrategie maakt het gemakkelijker om blokkeringsproblemen te vinden en op te lossen. Zie Eerdere versiedocumenten voor hulp.

Pakketvergelijking

Versie 11 consolideert en vereenvoudigt pakketbeheer, zodat er minder te beheren zijn.

Versie 10 en eerder	Versie 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Pakket Azure.Search.Documents

Clientvergelijking

Waar van toepassing wijst de volgende tabel de clientbibliotheken toe tussen de twee versies.

Clientbewerkingen	Microsoft.Azure.Search (v10)	Azure.Search.Documents (v11)
Is gericht op het verzamelen van documenten van een index (query's en gegevensimport)	SearchIndexClient	SearchClient
Doelen voor indexgerelateerde objecten (indexen, analyses, synoniemenkaarten)	SearchServiceClient	SearchIndexClient
Doelen voor indexeerfunctiegerelateerde objecten (indexeerfuncties, gegevensbronnen, vaardighedensets)	SearchServiceClient	SearchIndexerClient (nieuw)

Let op

U ziet dat SearchIndexClient bestaat in beide versies, maar is gericht op verschillende bewerkingen. In versie 10 maakt SearchIndexClient indexen en andere objecten. In versie 11 werkt SearchIndexClient met bestaande indexen, gericht op de verzameling documenten met query- en gegevensopname-API's. Houd rekening met de volgorde waarin clientverwijzingen worden bijgewerkt om verwarring te voorkomen bij het bijwerken van code. Als u de volgorde in stappen voor de upgrade volgt, kunt u problemen met het vervangen van tekenreeksen oplossen.

Naamgeving en andere API-verschillen

Naast de verschillen tussen clients (eerder vermeld en dus hier weggelaten), zijn meerdere andere API's hernoemd en in sommige gevallen opnieuw ontworpen. Verschillen in klassenamen worden samengevat in de volgende secties. Deze lijst is niet volledig, maar groepeert API-wijzigingen per taak, wat handig kan zijn voor revisies van specifieke codeblokken. Zie het wijzigingslogboek voor gitHub voor Azure.Search.Documents een geitemiseerde lijst met API-updates.

Verificatie en versleuteling

Versie 10	Equivalent van versie 11
SearchCredentials	AzureKeyCredential
EncryptionKey (niet-gedocumenteerd in API-verwijzing. Ondersteuning voor deze API is overgezet naar algemeen beschikbaar in v10, maar was alleen beschikbaar in de preview-SDK)	SearchResourceEncryptionKey

Indexen, analyses, synoniemenkaarten

Versie 10	Equivalent van versie 11
Index	SearchIndex
Veld	SearchField
Datatype	SearchFieldDataType
ItemError	SearchIndexerError
Analyzer	LexicalAnalyzer (ook AnalyzerName naar LexicalAnalyzerName)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (ook StandardTokenizerV2 , aan LuceneStandardTokenizerV2)
TokenInfo	AnalyzedTokenInfo
Tokenizer	LexicalTokenizer (ook TokenizerName , naar LexicalTokenizerName)
SynonymMap.Format	Geen. Verwijzingen naar Format.

Velddefinities zijn gestroomlijnd: SearchableField, SimpleField, ComplexField zijn nieuwe API's voor het maken van velddefinities.

Indexeerfuncties, gegevensbronnen, vaardighedensets

Versie 10	Equivalent van versie 11
Indexeerfunctie	SearchIndexer
DataSource	SearchIndexerDataSourceConnection
Vaardigheid	SearchIndexerSkill
Vaardighedenset	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

Gegevensimport

Versie 10	Equivalent van versie 11
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

Queryaanvragen en antwoorden

Versie 10	Equivalent van versie 11
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult of SearchResults, afhankelijk van of het resultaat één document of meerdere is.
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (een nieuwe klasse voor het maken van OData-filterexpressies)

JSON-serialisatie

De Azure SDK maakt standaard gebruik van System.Text.Json voor JSON-serialisatie, afhankelijk van de mogelijkheden van deze API's om teksttransformaties te verwerken die eerder zijn geïmplementeerd via een systeemeigen SerializePropertyNamesAsCamelCaseAttribute-klasse , die geen tegenhanger in de nieuwe bibliotheek heeft.

Als u eigenschapsnamen in camelCase wilt serialiseren, kunt u de JsonPropertyNameAttribute (vergelijkbaar met dit voorbeeld) gebruiken.

U kunt ook een JsonNamingPolicy instellen in JsonSerializerOptions. In het volgende codevoorbeeld System.Text.Json, afkomstig uit het leesmij-bestand Microsoft.Azure.Core.Spatial, wordt het gebruik van camelCase gedemonstreert zonder dat u elke eigenschap hoeft toe te schrijven:

// Get the Azure AI Search service endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

Als u Newtonsoft.Json gebruikt voor JSON-serialisatie, kunt u globale naamgevingsbeleidsregels doorgeven met vergelijkbare kenmerken of met behulp van eigenschappen op JsonSerializerSettings. Zie het voorbeeld van het deserialiseren van documenten in de readme Newtonsoft.Json voor een voorbeeld dat gelijk is aan de vorige versie.

Binnen v11

Elke versie van een Azure AI Search-clientbibliotheek is gericht op een bijbehorende versie van de REST API. De REST API wordt beschouwd als basis voor de service, waarbij afzonderlijke SDK's een versie van de REST API verpakken. Als .NET-ontwikkelaar kan het handig zijn om de uitgebreidere REST API-documentatie te bekijken voor uitgebreidere dekking van specifieke objecten of bewerkingen. Versie 11 is gericht op de zoekservicespecificatie 2020-06-30.

Versie 11.0 ondersteunt de volgende objecten en bewerkingen volledig:

• Index maken en beheren
• Synoniem voor het maken en beheren van kaarten
• Indexeerfunctie maken en beheren
• Indexeerfunctie voor het maken en beheren van gegevensbronnen
• Vaardighedenset maken en beheren
• Alle querytypen en syntaxis

Toevoegingen van versie 11.1 (wijzigingslogboekdetails ):

• FieldBuilder (toegevoegd in 11.1)
• Serializer-eigenschap (toegevoegd in 11.1) ter ondersteuning van aangepaste serialisatie

Toevoegingen van versie 11.2 (wijzigingslogboekdetails ):

• De eigenschap EncryptionKey heeft indexeerfuncties, gegevensbronnen en vaardighedensets toegevoegd

• Ondersteuning voor de eigenschap IndexingParameters.IndexingParametersConfiguration

• Georuimtelijke typen worden systeemeigen ondersteund in FieldBuilder. SearchFilter kan geometrische typen coderen van Microsoft.Spatial zonder expliciete assembly-afhankelijkheid.

  U kunt ook expliciet een afhankelijkheid van Microsoft.Spatial declareren. Voorbeelden van deze techniek zijn beschikbaar voor System.Text.Json en Newtonsoft.Json.

Toevoegingen van versie 11.3 (details van wijzigingenlogboek ):

• KnowledgeStore
• Er is ondersteuning toegevoegd voor Azure.Core.GeoJson-typen in SearchDocument, SearchFilter en FieldBuilder.
• Logboekregistratie op basis van EventSource toegevoegd. De naam van de gebeurtenisbron is Azure-Search-Documents. De huidige reeks gebeurtenissen is gericht op het afstemmen van batchgrootten voor SearchIndexingBufferedSender.
• CustomEntityLookupSkill en DocumentExtractionSkill toegevoegd. DefaultCountryHint toegevoegd in LanguageDetectionSkill.

Voordat u een upgrade uitvoert

• Quickstarts, zelfstudies en C#-voorbeelden zijn bijgewerkt om het pakket Azure.Search.Documents te gebruiken. We raden u aan de voorbeelden en stapsgewijze instructies te bekijken voor meer informatie over de nieuwe API's voordat u aan een migratieoefening begint.

• Het gebruik van Azure.Search.Documents introduceert de meest gebruikte API's. Zelfs deskundige gebruikers van Azure AI Search willen deze inleiding tot de nieuwe bibliotheek misschien bekijken als voorloper van migratie.

Stappen voor het upgraden

Met de volgende stappen kunt u aan de slag met een codemigratie door de eerste set vereiste taken te doorlopen, met name met betrekking tot clientverwijzingen.

1. Installeer het pakket Azure.Search.Documents door met de rechtermuisknop op uw projectverwijzingen te klikken en NuGet-pakketten beheren te selecteren... in Visual Studio.

2. Vervang het gebruik van instructies voor Microsoft.Azure.Search door de volgende using-instructies:

   using Azure;
   using Azure.Search.Documents;
   using Azure.Search.Documents.Indexes;
   using Azure.Search.Documents.Indexes.Models;
   using Azure.Search.Documents.Models;
   

3. Voor klassen waarvoor JSON-serialisatie is vereist, vervangt u door using Newtonsoft.Json using System.Text.Json.Serialization.

4. Wijzig de code voor clientverificatie. In eerdere versies gebruikt u eigenschappen voor het clientobject om de API-sleutel in te stellen (bijvoorbeeld de eigenschap SearchServiceClient.Credentials ). Gebruik in de huidige versie de klasse AzureKeyCredential om de sleutel als referentie door te geven, zodat u, indien nodig, de API-sleutel kunt bijwerken zonder nieuwe clientobjecten te maken.

   Clienteigenschappen zijn gestroomlijnd tot alleen Endpoint, ServiceNameen IndexName (indien van toepassing). In het volgende voorbeeld wordt de systeem-URI-klasse gebruikt om het eindpunt en de omgevingsklasse op te geven om de sleutelwaarde te lezen:

   Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
   AzureKeyCredential credential = new AzureKeyCredential(
      Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
   SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
   

5. Voeg nieuwe clientverwijzingen toe voor indexeerobjecten. Als u indexeerfuncties, gegevensbronnen of vaardighedensets gebruikt, wijzigt u de clientverwijzingen in SearchIndexerClient. Deze client is nieuw in versie 11 en heeft geen antecedent.

6. Verzamelingen en lijsten herzien. In de nieuwe SDK zijn alle lijsten alleen-lezen om downstreamproblemen te voorkomen als de lijst null-waarden bevat. De codewijziging is het toevoegen van items aan een lijst. In plaats van tekenreeksen toe te wijzen aan een eigenschap Selecteren, voegt u deze bijvoorbeeld als volgt toe:

   var options = new SearchOptions
    {
       SearchMode = SearchMode.All,
       IncludeTotalCount = true
    };
   
    // Select fields to return in results.
    options.Select.Add("HotelName");
    options.Select.Add("Description");
    options.Select.Add("Tags");
    options.Select.Add("Rooms");
    options.Select.Add("Rating");
    options.Select.Add("LastRenovationDate");
   

   Select, Facets, SearchFields, SourceFields, ScoringParameters en OrderBy zijn alle lijsten die nu moeten worden gereconstrueerd.

7. Werk clientverwijzingen voor query's en gegevensimport bij. Exemplaren van SearchIndexClient moeten worden gewijzigd in SearchClient. Om verwarring over naam te voorkomen, moet u ervoor zorgen dat u alle exemplaren onderscheppen voordat u doorgaat met de volgende stap.

8. Werk clientverwijzingen bij voor index-, synoniemtoewijzings- en analyseobjecten. Exemplaren van SearchServiceClient moeten worden gewijzigd in SearchIndexClient.

9. Werk voor de rest van uw code klassen, methoden en eigenschappen bij om de API's van de nieuwe bibliotheek te gebruiken. De sectie naamgevingsverschillen is een plek om te beginnen, maar u kunt het wijzigingslogboek ook bekijken.

   Als u problemen ondervindt bij het vinden van equivalente API's, raden we u aan een probleem aan https://github.com/MicrosoftDocs/azure-docs/issues te melden, zodat we de documentatie kunnen verbeteren of het probleem kunnen onderzoeken.

10. Bouw de oplossing opnieuw. Nadat u eventuele buildfouten of waarschuwingen hebt opgelost, kunt u aanvullende wijzigingen aanbrengen in uw toepassing om te profiteren van nieuwe functionaliteit.

Wijzigingen die fouten veroorzaken

Gezien de opruimende wijzigingen in bibliotheken en API's, is een upgrade naar versie 11 niet triviaal en vormt dit een belangrijke wijziging in de zin dat uw code niet langer compatibel is met versie 10 en eerder. Zie het wijzigingenlogboek voor Azure.Search.Documentseen grondige beoordeling van de verschillen.

In termen van serviceversie-updates, waarbij codewijzigingen in versie 11 betrekking hebben op bestaande functionaliteit (en niet alleen een herstructurering van de API's), vindt u de volgende gedragswijzigingen:

• BM25-classificatiealgoritmen vervangen het vorige classificatie-algoritme door nieuwere technologie. Nieuwe services gebruiken dit algoritme automatisch. Voor bestaande services moet u parameters instellen om het nieuwe algoritme te gebruiken.

• Geordende resultaten voor null-waarden zijn in deze versie gewijzigd, waarbij null-waarden eerst worden weergegeven als de sortering asc en laatste als de sortering is desc. Als u code hebt geschreven om te bepalen hoe null-waarden worden gesorteerd, moet u die code controleren en mogelijk verwijderen als deze niet meer nodig is.

Vanwege deze gedragswijzigingen is het waarschijnlijk dat er lichte variaties zijn in gerangschikte resultaten.

Volgende stappen

• Azure.Search.Documents gebruiken in een C# .NET-toepassing
• Zelfstudie: Zoeken toevoegen aan web-apps
• Pakket Azure.Search.Documents
• Voorbeelden op GitHub
• Naslaginformatie over azure.Search.Document-API