Frissítés az Azure Search .NET SDK 9-es verziójára

Ha az Azure Search .NET SDK 7.0-s vagy újabb verzióját használja, ez a cikk segít frissíteni az alkalmazást a 9-es verzió használatára.

Az SDK általánosabb, példákat is tartalmazó bemutatóját a .NET-alkalmazásból származó Azure Search használata című témakörben találja.

Az Azure Search .NET SDK 9-es verziója számos módosítást tartalmaz a korábbi verziókban. Ezek némelyike kompatibilitástörő módosítás, de csak viszonylag kisebb módosításokat igényelnek a kódban. A kód új SDK-verzió használatára való módosítására vonatkozó útmutatásért tekintse meg frissítésének lépéseit.

A 9-es verzió újdonságai

Az Azure Search .NET SDK 9-es verziója az Azure Search REST API 2019-05-06-os verzióját célozza meg, a következő funkciókkal:

• Az AI-bővítés lehetővé teszi a képekből, blobokból és más strukturálatlan adatforrásokból származó szöveg kinyerését – a tartalom bővítésével pedig könnyebben kereshetőbbé teheti az Azure Search-indexekben.
• Az összetett típusok támogatása lehetővé teszi, hogy szinte minden beágyazott JSON-struktúrát modellezhet egy Azure Search-indexben.
• Az automatikus kiegészítés alternatívát kínál a Javaslat API-ra a keresési típus szerinti viselkedés implementálásához. Az automatikus kiegészítés "befejezi" a felhasználó által éppen beírt szót vagy kifejezést.
• A blobindexelés részét képező JsonLines-elemzési mód JSON-entitásonként egy keresési dokumentumot hoz létre, amelyet egy új vonal választ el egymástól.

Új előzetes verziójú funkciók a 8.0-s verzióban

Az Azure Search .NET SDK 8.0-preview verziója az API 2017-11-11-preview verzióját célozza meg. Ez a verzió a 9-es verzió összes funkcióját tartalmazza, valamint:

• A szolgáltatásoldali titkosításokhoz tartozó, ügyfél által felügyelt titkosítási kulcsok az adatok nyugalmi állapotban történő titkosításához egy új előzetes verziós funkció. A Microsoft által felügyelt beépített titkosítás mellett további titkosítási réteget is alkalmazhat, ahol Ön a kulcsok kizárólagos tulajdonosa.

A frissítés lépései

Először is frissítse a Microsoft.Azure.Search NuGet hivatkozást a NuGet csomagkezelő konzol használatával, vagy kattintson a jobb gombbal a projekt hivatkozásaira, és válassza a "NuGet-csomagok kezelése..." lehetőséget a Visual Studio-ban.

Miután a NuGet letöltötte az új csomagokat és azok függőségeit, építse újra a projektet. A kód felépítésétől függően a kód újraépítése sikeres lehet. Ha igen, készen áll az indulásra!

Ha a build sikertelen, minden egyes buildelési hibát ki kell javítania. Lásd a A 9-es verzió kompatibilitástörő változásait további részletekért, hogyan lehet megoldani az egyes lehetséges buildelési hibát.

Az elavult metódusokkal vagy tulajdonságokkal kapcsolatos további összeállítási figyelmeztetések is megjelenhetnek. A figyelmeztetések az elavult funkció helyett a használatukra vonatkozó utasításokat is tartalmazzák. Ha például az alkalmazás használja a DataSourceType.DocumentDb tulajdonságot, figyelmeztetést kell kapnia, amely szerint "Ez a tag elavult. Használja inkább a CosmosDb-t".

Miután kijavított minden buildelési hibát vagy figyelmeztetést, módosíthatja az alkalmazást, hogy igény szerint kihasználhassa az új funkciókat. Az SDK új funkcióit a 9-es verzió újdonságai ismertetik.

Kompatibilitástörő változások a 9-es verzióban

A 9-es verzióban több kompatibilitástörő változás is előfordulhat, amelyek az alkalmazás újraépítése mellett kódmódosítást is igényelhetnek.

Nem módosítható tulajdonságok

Több modellosztály nyilvános tulajdonságai mostantól nem módosíthatók. Ha a teszteléshez egyéni példányokat kell létrehoznia ezeknek az osztályoknak, használhatja az új paraméteres konstruktorokat:

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

Mező változásai

Az Field osztály most megváltozott, hogy összetett mezőket is képviselhet.

A következő bool tulajdonságok mostantól null értékűek:

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

Ennek az az oka, hogy ezeknek a tulajdonságoknak most már összetett mezők esetén kell lenniük null . Ha olyan kóddal rendelkezik, amely beolvassa ezeket a tulajdonságokat, készüljön fel null kezelésére. Vegye figyelembe, hogy az összes többi tulajdonság Field mindig is null értékű volt és továbbra is null értékű, és ezek némelyike összetett mezők esetén is jelen lesz null – különösen a következők esetében:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

A paraméter nélküli konstruktor Field meg lett internal. Mostantól minden Field-nek explicit nevet és adattípust kell megadni a létrehozáskor.

Egyszerűsített köteg- és eredménytípusok

A 7.0-s és korábbi verzióban a dokumentumcsoportokat tartalmazó különböző osztályok párhuzamos osztályhierarchiákba lettek strukturálva:

• DocumentSearchResult és DocumentSearchResult<T> örökölte DocumentSearchResultBase
• DocumentSuggestResult és DocumentSuggestResult<T> örökölte DocumentSuggestResultBase
• IndexAction és IndexAction<T> örökölte IndexActionBase
• IndexBatch és IndexBatch<T> örökölte IndexBatchBase
• SearchResult és SearchResult<T> örökölte SearchResultBase
• SuggestResult és SuggestResult<T> örökölte SuggestResultBase

Az általános típusparaméter nélküli származtatott típusokat a "dinamikusan gépelt" forgatókönyvekben és a Document típus feltételezett használatában kellett használni.

A 8.0-s verziótól kezdve az alaposztályok és a nem általános származtatott osztályok mind el lettek távolítva. Dinamikusan gépelt forgatókönyvek esetén használhatja IndexBatch<Document>a , DocumentSearchResult<Document>és így tovább.

Eltávolítva extensibleEnum

Az ExtensibleEnum alaposztály el lett távolítva. Az ebből származtatott osztályok most már szerkezetek, például AnalyzerName: , DataTypeés DataSourceType például. A módszereiket Create is eltávolították. Egyszerűen eltávolíthatja a hívásokat Create, mivel ezek a típusok implicit módon konvertálhatók a szövegből. Ha ez fordítóhibákat eredményez, explicit módon meghívhatja a konvertálási operátort a típusok egyértelműsítése érdekében. Módosíthatja például a következőhöz hasonló kódot:

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

erre:

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

Az ilyen típusú opcionális értékeket tartalmazó tulajdonságok mostantól explicit módon null értékűek, így továbbra is nem kötelezőek.

Eltávolított FacetResults és HitHighlights

A FacetResults és a HitHighlights osztály el lett távolítva. Az arculati eredmények mostantól a következőképpen vannak beírva IDictionary<string, IList<FacetResult>> , és a kiemeléseket IDictionary<string, IList<string>>a következőképpen adhatja meg. A módosítás által bevezetett buildelési hibák gyors megoldásának egyik módja, ha aliasokat ad hozzá using az eltávolított típusokat használó összes fájl tetején. Például:

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

Váltás szinonimaképre

A SynonymMap konstruktor már nem rendelkezik enum paraméterrel SynonymMapFormat. Ez a szám csak egy értékkel rendelkezett, ezért redundáns volt. Ha ennek eredményeként buildelési hibákat lát, egyszerűen távolítsa el a SynonymMapFormat paraméterre mutató hivatkozásokat.

Eltérő modellosztályok változásai

A AutocompleteMode tulajdonság AutocompleteParameters többé nem lehet null értékű. Ha rendelkezik a tulajdonságot nullhozzárendelő kóddal, egyszerűen eltávolíthatja, és a tulajdonság automatikusan inicializálva lesz az alapértelmezett értékre.

A IndexAction konstruktor paramétereinek sorrendje meg lett változtatva, mivel ez a konstruktor most automatikusan generálódik. A konstruktor használata helyett javasoljuk a gyári metódusok IndexAction.Uploadhasználatát, IndexAction.Mergeés így tovább.

Eltávolított előzetes verziójú funkciók

Ha a 8.0-s verzióról a 9-es verzióra frissít, vegye figyelembe, hogy az ügyfél által felügyelt kulcsokkal rendelkező titkosítás el lett távolítva, mivel ez a funkció még előzetes verzióban érhető el. Pontosabban, a EncryptionKey tulajdonságai a Index és a SynonymMap el lettek távolítva.

Ha az alkalmazás erősen függ a funkciótól, nem fog tudni frissíteni az Azure Search .NET SDK 9-es verziójára. Továbbra is használhatja a 8.0-s verzió előzetes verzióját. Ne feledje azonban, hogy éles alkalmazásokban nem javasoljuk az előzetes verziójú SDK-k használatát. Az előzetes verziójú funkciók csak kiértékelhetők, és változhatnak.

Viselkedésbeli változás az adatlekérésben

Ha a "dinamikusan típusos" Search, Suggest vagy Get API-kat használja, amelyek Document típusú példányokat adnak vissza, vegye figyelembe, hogy mostantól az üres JSON-tömböket object[]-ként deszerializálják string[] helyett.

Következtetés

Ha további részletekre van szüksége az Azure Search .NET SDK használatával kapcsolatban, tekintse meg a .NET útmutatóját.

Örömmel vesszük visszajelzését az SDK-val kapcsolatban. Ha problémákba ütközik, kérjen segítséget a Stack Overflow-hoz. Ha hibát talál, az Azure .NET SDK GitHub-adattárában is elküldheti a problémát. Győződjön meg arról, hogy a probléma címét az "[Azure Search]" előtaggal használja.

Köszönjük, hogy az Azure Search szolgáltatást használta!