Uppgradera till Azure AI Search .NET SDK version 11

Artikel
12/10/2024

Om din söklösning bygger på Azure SDK för .NET hjälper den här artikeln dig att migrera koden från tidigare versioner av Microsoft.Azure.Search till version 11, det nya Azure.Search.Documents-klientbiblioteket. Version 11 är ett fullständigt omdesignat klientbibliotek som släpptes av Azure SDK-utvecklingsteamet (tidigare versioner producerades av Utvecklingsteamet för Azure AI Search).

Alla funktioner från version 10 implementeras i version 11. Viktiga skillnader är:

Ett paket (Azure.Search.Documents) i stället för fyra
Tre klienter i stället för två: SearchClient, SearchIndexClient, SearchIndexerClient
Namngivningsskillnader mellan en rad API:er och små strukturella skillnader som förenklar vissa uppgifter

Klientbibliotekets ändringslogg har en specificerad lista med uppdateringar. Du kan granska en sammanfattad version i den här artikeln.

Alla C#-kodexempel och kodfragment i produktdokumentationen för Azure AI Search har ändrats för att använda det nya Azure.Search.Documents-klientbiblioteket .

Varför uppgradera?

Fördelarna med att uppgradera sammanfattas på följande sätt:

Nya funktioner läggs endast till i Azure.Search.Documents . Den tidigare versionen, Microsoft.Azure.Search, har nu dragits tillbaka. Uppdateringar av inaktuella bibliotek är endast begränsade till buggkorrigeringar med hög prioritet.
Konsekvens med andra Azure-klientbibliotek. Azure.Search.Documents är beroende av Azure.Core och System.Text.Json och följer konventionella metoder för vanliga uppgifter som klientanslutningar och auktorisering.

Microsoft.Azure.Search har officiellt dragits tillbaka. Om du använder en gammal version rekommenderar vi att du uppgraderar till nästa högre version och upprepar processen i följd tills du når version 11 och Azure.Search.Documents. En inkrementell uppgraderingsstrategi gör det enklare att hitta och åtgärda blockeringsproblem. Mer information finns i Dokument för tidigare version.

Paketjämförelse

Version 11 konsoliderar och förenklar pakethanteringen så att det finns färre att hantera.

Version 10 och tidigare	Version 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Azure.Search.Documents-paket

Klientjämförelse

I tillämpliga fall mappar följande tabell klientbiblioteken mellan de två versionerna.

Klientåtgärder	Microsoft.Azure.Search (v10)	Azure.Search.Documents (v11)
Riktar in sig på dokumentsamlingen för ett index (frågor och dataimport)	SearchIndexClient	SearchClient
Mål för indexrelaterade objekt (index, analysverktyg, synonymkartor	SearchServiceClient	SearchIndexClient
Riktar sig till indexerarrelaterade objekt (indexerare, datakällor, kompetensuppsättningar)	SearchServiceClient	SearchIndexerClient (ny)

Varning

Observera att SearchIndexClient finns i båda versionerna, men riktar sig till olika åtgärder. I version 10 skapar SearchIndexClient index och andra objekt. I version 11 fungerar SearchIndexClient med befintliga index som riktar in sig på dokumentsamlingen med fråge- och datainmatnings-API:er. För att undvika förvirring vid uppdatering av kod bör du tänka på i vilken ordning klientreferenserna uppdateras. Om du följer sekvensen i Steg för att uppgradera bör du minimera eventuella problem med strängersättning.

Namngivning och andra API-skillnader

Förutom klientskillnaderna (som tidigare antecknades och därmed utelämnades här) har flera andra API:er bytt namn och i vissa fall gjorts om. Skillnader i klassnamn sammanfattas i följande avsnitt. Den här listan är inte fullständig, men den grupperar API-ändringar efter aktivitet, vilket kan vara användbart för revisioner av specifika kodblock. En specificerad lista över API-uppdateringar finns i ändringsloggen för Azure.Search.Documents på GitHub.

Autentisering och kryptering

Version 10	Motsvarande version 11
SearchCredentials	AzureKeyCredential
EncryptionKey (odokumenterad i API-referens. Stöd för det här API:et övergick till allmänt tillgängligt i v10, men var endast tillgängligt i förhandsversionens SDK)	SearchResourceEncryptionKey

Index, analysverktyg, synonymkartor

Version 10	Motsvarande version 11
Index	SearchIndex
Fält	SearchField
Datatyp	SearchFieldDataType
ItemError	SearchIndexerError
Analyzer	LexicalAnalyzer (också, `AnalyzerName` till `LexicalAnalyzerName`)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (också till `StandardTokenizerV2` `LuceneStandardTokenizerV2`)
TokenInfo	AnalyzedTokenInfo
Tokenizer	LexicalTokenizer (också, `TokenizerName` till `LexicalTokenizerName`)
SynonymMap.Format	Inga. Ta bort referenser till `Format`.

Fältdefinitioner effektiviseras: SearchableField, SimpleField, ComplexField är nya API:er för att skapa fältdefinitioner.

Indexerare, datakällor, kompetensuppsättningar

Version 10	Motsvarande version 11
Indexerare	SearchIndexer
DataSource	SearchIndexerDataSourceConnection
Färdighet	SearchIndexerSkill
Kompetensuppsättning	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

Dataimport

Version 10	Motsvarande version 11
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

Frågebegäranden och svar

Version 10	Motsvarande version 11
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult eller SearchResults, beroende på om resultatet är ett enda dokument eller flera.
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (en ny klass för att konstruera OData-filteruttryck)

JSON-serialisering

Som standard använder Azure SDK System.Text.Json för JSON-serialisering och förlitar sig på funktionerna i dessa API:er för att hantera texttransformeringar som tidigare implementerats via en intern SerializePropertyNamesAsCamelCaseAttribute-klass , som inte har någon motsvarighet i det nya biblioteket.

Om du vill serialisera egenskapsnamn till camelCase kan du använda JsonPropertyNameAttribute (liknar det här exemplet).

Du kan också ange en JsonNamingPolicy som anges i JsonSerializerOptions. Följande System.Text.Json-kodexempel, hämtat från Microsoft.Azure.Core.Spatial readme , visar användningen av camelCase utan att behöva tillskriva varje egenskap:

// 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");

Om du använder Newtonsoft.Json för JSON-serialisering kan du skicka in globala namngivningsprinciper med liknande attribut eller genom att använda egenskaper på JsonSerializerSettings. Ett exempel som motsvarar det föregående finns i exemplet deserialisera dokument i Newtonsoft.Json-readme.

Inuti v11

Varje version av ett Azure AI Search-klientbibliotek riktar sig mot en motsvarande version av REST-API:et. REST-API:et anses vara grundläggande för tjänsten, med enskilda SDK:er som omsluter en version av REST-API:et. Som .NET-utvecklare kan det vara bra att granska den mer utförliga REST API-dokumentationen för mer djupgående täckning av specifika objekt eller åtgärder. Version 11 är avsedd för specifikationen för söktjänsten 2020-06-30.

Version 11.0 stöder helt följande objekt och åtgärder:

Skapa och hantera index
Skapa och hantera synonymkarta
Skapande och hantering av indexerare
Skapande och hantering av indexerares datakälla
Skapande och hantering av kompetensuppsättningar
Alla frågetyper och syntax

Tillägg av version 11.1 (ändringslogginformation ):

FieldBuilder (läggs till i 11.1)
Serializer-egenskapen (läggs till i 11.1) för att stödja anpassad serialisering

Tillägg av version 11.2 (ändringslogginformation ):

Egenskapen EncryptionKey har lagt till indexerare, datakällor och kompetensuppsättningar
IndexingParameters.IndexingParametersConfiguration-egenskapsstöd
Geospatiala typer stöds internt i FieldBuilder. SearchFilter kan koda geometriska typer från Microsoft.Spatial utan ett explicit sammansättningsberoende.

Du kan också fortsätta att uttryckligen deklarera ett beroende av Microsoft.Spatial. Exempel på den här tekniken är tillgängliga för System.Text.Json och Newtonsoft.Json.

Tillägg av version 11.3 (ändringslogginformation ):

KnowledgeStore
Stöd har lagts till för Azure.Core.GeoJson-typer i SearchDocument, SearchFilter och FieldBuilder.
EventSource-baserad loggning har lagts till. Händelsekällans namn är Azure-Search-Documents. Den aktuella uppsättningen händelser fokuserar på att justera batchstorlekar för SearchIndexingBufferedSender.
CustomEntityLookupSkill och DocumentExtractionSkill har lagts till. DefaultCountryHint har lagts till i LanguageDetectionSkill.

Innan du uppgraderar

Snabbstarter, självstudier och C#-exempel har uppdaterats för att använda paketet Azure.Search.Documents. Vi rekommenderar att du granskar exemplen och genomgångarna för att lära dig mer om de nya API:erna innan du påbörjar en migreringsövning.
Hur du använder Azure.Search.Documents introducerar de vanligaste API:erna. Även kunniga användare av Azure AI Search kanske vill granska den här introduktionen till det nya biblioteket som en föregångare till migrering.

Steg för att uppgradera

Följande steg hjälper dig att komma igång med en kodmigrering genom att gå igenom den första uppsättningen obligatoriska uppgifter, särskilt när det gäller klientreferenser.

Installera paketet Azure.Search.Documents genom att högerklicka på dina projektreferenser och välja "Hantera NuGet-paket..." i Visual Studio.

Ersätt med direktiv för Microsoft.Azure.Search med följande instruktioner:

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

För klasser som kräver JSON-serialisering ersätter du using Newtonsoft.Json med using System.Text.Json.Serialization.
Ändra kod för klientautentisering. I tidigare versioner skulle du använda egenskaper för klientobjektet för att ange API-nyckeln (till exempel egenskapen SearchServiceClient.Credentials ). I den aktuella versionen använder du klassen AzureKeyCredential för att skicka nyckeln som en autentiseringsuppgift, så att du vid behov kan uppdatera API-nyckeln utan att skapa nya klientobjekt.

Klientegenskaperna har effektiviserats till bara Endpoint, ServiceNameoch IndexName (där det är lämpligt). I följande exempel används system-URI-klassen för att ange slutpunkten och klassen Miljö för att läsa in nyckelvärdet:
```
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
```
Lägg till nya klientreferenser för indexerarrelaterade objekt. Om du använder indexerare, datakällor eller kompetensuppsättningar ändrar du klientreferenserna till SearchIndexerClient. Den här klienten är ny i version 11 och har ingen föregående.
Ändra samlingar och listor. I den nya SDK:n är alla listor skrivskyddade för att undvika underordnade problem om listan råkar innehålla null-värden. Kodändringen är att lägga till objekt i en lista. I stället för att till exempel tilldela strängar till en Select-egenskap lägger du till dem på följande sätt:
```
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 och OrderBy är alla listor som nu måste rekonstrueras.
Uppdatera klientreferenser för frågor och dataimport. Instanser av SearchIndexClient bör ändras till SearchClient. Undvik namnförvirring genom att se till att du fångar alla instanser innan du fortsätter till nästa steg.
Uppdatera klientreferenser för index, synonymkarta och analysobjekt. Instanser av SearchServiceClient bör ändras till SearchIndexClient.
För resten av koden uppdaterar du klasser, metoder och egenskaper för att använda API:erna för det nya biblioteket. Avsnittet om namngivningsskillnader är en plats att börja på, men du kan också granska ändringsloggen.

Om du har problem med att hitta motsvarande API:er föreslår vi att du loggar in ett problem https://github.com/MicrosoftDocs/azure-docs/issues så att vi kan förbättra dokumentationen eller undersöka problemet.
Återskapa lösningen. När du har åtgärdat eventuella byggfel eller varningar kan du göra ytterligare ändringar i programmet för att dra nytta av nya funktioner.

Icke-bakåtkompatibla ändringar

Med tanke på de omfattande ändringarna av bibliotek och API:er är en uppgradering till version 11 icke-trivial och utgör en icke-trivial ändring i den meningen att koden inte längre är bakåtkompatibel med version 10 och tidigare. En grundlig genomgång av skillnaderna finns i ändringsloggen för Azure.Search.Documents.

När det gäller uppdateringar av tjänstversioner, där kodändringar i version 11 relaterar till befintliga funktioner (och inte bara en refaktorisering av API:erna), hittar du följande beteendeändringar:

BM25-rangordningsalgoritmen ersätter den tidigare rankningsalgoritmen med nyare teknik. Nya tjänster använder den här algoritmen automatiskt. För befintliga tjänster måste du ange parametrar för att använda den nya algoritmen.
Ordnade resultat för null-värden har ändrats i den här versionen, med null-värden som visas först om sorteringen är asc och sist om sorteringen är desc. Om du har skrivit kod för att hantera hur nullvärden sorteras bör du granska och eventuellt ta bort koden om den inte längre behövs.

På grund av dessa beteendeändringar är det troligt att det finns små variationer i rankade resultat.

Dela via