Aktualizace na .NET SDK Azure Search verzi 9

Pokud používáte verzi 7.0-preview nebo starší sady .NET SDK služby Azure Search, pomůže vám tento článek upgradovat aplikaci tak, aby používala verzi 9.

Obecnější návod k sadě SDK včetně příkladů najdete v tématu Použití služby Azure Search z aplikace .NET.

Verze 9 sady .NET SDK služby Azure Search obsahuje mnoho změn z předchozích verzí. Některé z nich jsou zásadní změny, ale měly by vyžadovat pouze relativně menší změny kódu. Pokyny, jak změnit svůj kód pro použití nové verze SDK, najdete v krocích pro upgrade.

Novinky ve verzi 9

Verze 9 sady Azure Search .NET SDK cílí na verzi rozhraní REST API služby Azure Search 2019-05-06 s následujícími funkcemi:

• AI enrichment je schopnost extrahovat text z obrázků, blobů a dalších nestrukturovaných zdrojů dat, čímž se obohacuje obsah a stává se lépe prohledávatelným v indexu Azure Search.
• Podpora složitých typů umožňuje modelovat téměř jakoukoli vnořenou strukturu JSON v indexu Služby Azure Search.
• Autocomplete nabízí alternativu k rozhraní API Suggest pro implementaci hledání v průběhu psaní. Automaticky dokončte slovo nebo frázi, které uživatel právě píše.
• Režim parsování JsonLines, který je součástí indexování blobů, vytvoří jeden vyhledávací dokument pro každou entitu JSON oddělenou novým řádkem.

Nové funkce preview ve verzi 8.0-preview

Verze 8.0-preview sady Azure Search .NET SDK cílí na rozhraní API verze 2017-11-11-Preview. Tato verze zahrnuje všechny stejné funkce verze 9 a navíc:

• Šifrovací klíče spravované zákazníkem pro šifrování na straně služby v klidovém stavu je nejnovější funkce ve verzi Preview. Kromě integrovaného šifrování uložených dat spravovaného Microsoftem můžete aplikovat další vrstvu šifrování, kde jste jediným vlastníkem klíčů.

Postup upgradu

Nejprve aktualizujte referenční informace NuGet pro Microsoft.Azure.Search pomocí konzoly Správce balíčků NuGet nebo kliknutím pravým tlačítkem myši na odkazy na projekt a výběrem možnosti Spravovat balíčky NuGet... v sadě Visual Studio.

Jakmile NuGet stáhne nové balíčky a jejich závislosti, znovu sestavte projekt. V závislosti na tom, jak je váš kód strukturován, se může úspěšně sestavit. Pokud ano, jste připraveni jít!

Pokud sestavení selže, budete muset opravit každou chybu sestavení. Podrobnosti o řešení jednotlivých potenciálních chyb sestavení najdete v zásadních změnách ve verzi 9.

Mohou se zobrazit další upozornění na sestavení týkající se zastaralých metod nebo vlastností. Upozornění budou obsahovat pokyny k tomu, co použít místo zastaralé funkce. Pokud například vaše aplikace používá vlastnost DataSourceType.DocumentDb, měli byste se zobrazit upozornění s informací, že tento člen je zastaralý. Místo toho použijte CosmosDb.

Jakmile opravíte chyby nebo upozornění sestavení, můžete v aplikaci provádět změny, abyste mohli využívat nové funkce, pokud chcete. Nové funkce v sadě SDK jsou podrobně popsány v Novinky ve verzi 9.

Zásadní změny ve verzi 9

Ve verzi 9 existuje několik zásadních změn, které můžou kromě opětovného sestavení aplikace vyžadovat změny kódu.

Neměnné vlastnosti

Veřejné vlastnosti několika tříd modelu jsou nyní neměnné. Pokud potřebujete vytvořit vlastní instance těchto tříd pro testování, můžete použít nové parametrizované konstruktory:

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

Změny v poli

Třída Field se teď změnila, protože může také představovat složitá pole.

Následující vlastnosti bool mohou mít nyní hodnotu null:

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

Důvodem je to, že tyto vlastnosti musí být nyní null v případě složitých polí. Pokud máte kód, který čte tyto vlastnosti, musí být připraven ke zpracování null. Všimněte si, že všechny ostatní vlastnosti Field byly vždy nulovatelné a nadále zůstanou, a některé z nich budou také null v případě složitých polí – konkrétně následující:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Konstruktor bez parametrů Field byl vytvořen internal. Od této chvíle vyžaduje každý Field explicitní název a datový typ v době výstavby.

Zjednodušené typy šarží a výsledků

Ve verzi 7.0-Preview a starších byly různé třídy, které zapouzdřují skupiny dokumentů, strukturovány do paralelních hierarchií tříd:

• DocumentSearchResult a DocumentSearchResult<T> zděděné z DocumentSearchResultBase
• DocumentSuggestResult a DocumentSuggestResult<T> zděděné z DocumentSuggestResultBase
• IndexAction a IndexAction<T> zděděné z IndexActionBase
• IndexBatch a IndexBatch<T> zděděné z IndexBatchBase
• SearchResult a SearchResult<T> zděděné z SearchResultBase
• SuggestResult a SuggestResult<T> zděděné z SuggestResultBase

Odvozené typy bez obecného parametru typu byly určeny k použití ve scénářích s dynamickým typem a předpokládat použití typu Document.

Od verze 8.0-preview byly všechny základní třídy a ne generické odvozené třídy odebrány. Pro dynamicky napsané scénáře můžete použít IndexBatch<Document>, DocumentSearchResult<Document>atd.

Odstraněno rozšiřitelný Enum

Základní třída ExtensibleEnum byla odebrána. Všechny třídy odvozené z něj jsou nyní struktury, například AnalyzerName, DataTypea DataSourceType například. Jejich metody Create byly také odebrány. Volání Create můžete jednoduše odebrat, protože tyto typy se dají implicitně převést z řetězců. Pokud dojde k chybám kompilátoru, můžete explicitně vyvolat operátor převodu pomocí přetypování pro vyřešení nejednoznačnosti typů. Kód můžete například změnit takto:

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

k tomuto:

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

Vlastnosti, které mají volitelné hodnoty těchto typů, jsou nyní explicitně zadány jako nullable, takže budou nadále volitelné.

Odebrané FacetResults a HitHighlights

Třídy FacetResults a HitHighlights byly odebrány. Výsledky aspektů se teď zadají jako IDictionary<string, IList<FacetResult>> a zvýrazněné prvky jako IDictionary<string, IList<string>>. Rychlý způsob, jak vyřešit chyby sestavení zavedené touto změnou, je přidat using aliasy v horní části každého souboru, který používá odebrané typy. Například:

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

Změnit na Synonymní mapu

Konstruktor SynonymMap již nemá parametr enum pro SynonymMapFormat. Tento výčt měl pouze jednu hodnotu a byl proto redundantní. Pokud se v důsledku toho zobrazí chyby sestavení, jednoduše odeberte odkazy na parametr SynonymMapFormat.

Různé změny třídy modelu

Vlastnost AutocompleteMode u AutocompleteParameters již není možné nastavit na nulu. Pokud máte kód, který tuto vlastnost přiřadí k null, můžete ji jednoduše odebrat a vlastnost se automaticky inicializuje na výchozí hodnotu.

Pořadí parametrů konstruktoru IndexAction se změnilo, když je tento konstruktor automaticky generován. Místo použití konstruktoru doporučujeme používat tovární metody IndexAction.Upload, IndexAction.Mergeatd.

Odebrané funkce ve verzi Preview

Pokud upgradujete z verze 8.0-Preview na verzi 9, mějte na paměti, že šifrování s klíči spravovanými zákazníkem bylo odebráno, protože tato funkce je stále ve verzi Preview. Konkrétně byly odebrány vlastnosti EncryptionKey objektů Index a SynonymMap.

Pokud má vaše aplikace pevnou závislost na této funkci, nebudete moct upgradovat na verzi 9 sady .NET SDK služby Azure Search. Můžete dál používat verzi 8.0-preview. Mějte však na paměti, že nedoporučujeme používat sady Preview SDK v produkčních aplikacích. Funkce ve verzi Preview jsou určené jenom pro vyhodnocení a můžou se změnit.

Změna chování při načítání dat

Pokud používáte rozhraní API Search, Suggestnebo Get, která vracejí instance typu Document, mějte na paměti, že nyní deserializují prázdné JSON pole na object[] místo string[].

Závěr

Pokud potřebujete další podrobnosti o použití .NET SDK Azure Search, podívejte se na návod .NET.

Uvítáme vaše názory na SDK. Pokud narazíte na problémy, neváhejte nás požádat o pomoc na Stack Overflow. Pokud zjistíte chybu, můžete problém podat v úložišti GitHub sady Azure .NET SDK. Nezapomeňte přidat předponu "[Azure Search]" k názvu vašeho problému.

Děkujeme, že jste používali Azure Search!