Uaktualnianie do zestawu .NET SDK usługi Azure Search w wersji 9

Jeśli używasz wersji 7.0-preview lub starszej zestawu .NET SDK usługi Azure Search, ten artykuł pomoże Ci uaktualnić aplikację do korzystania z wersji 9.

Uwaga

Jeśli chcesz użyć wersji 8.0-preview do oceny funkcji, które nie są jeszcze ogólnie dostępne, możesz również postępować zgodnie z instrukcjami w tym artykule, aby uaktualnić do wersji 8.0-preview z poprzednich wersji.

Aby zapoznać się z bardziej ogólnym przewodnikiem po zestawie SDK, w tym przykładami, zobacz How to use Azure Search from a .NET Application (Jak używać usługi Azure Search z poziomu aplikacji .NET).

Wersja 9 zestawu .NET SDK usługi Azure Search zawiera wiele zmian z wcześniejszych wersji. Niektóre z nich to zmiany powodujące niezgodność, ale powinny wymagać tylko stosunkowo niewielkich zmian w kodzie. Zobacz Kroki uaktualniania, aby uzyskać instrukcje dotyczące zmiany kodu w celu korzystania z nowej wersji zestawu SDK.

Uwaga

Jeśli używasz wersji 4.0-preview lub starszej, najpierw należy przeprowadzić uaktualnienie do wersji 5, a następnie przeprowadzić uaktualnienie do wersji 9. Aby uzyskać instrukcje, zobacz Uaktualnianie do zestawu .NET SDK usługi Azure Search w wersji 5 .

Wystąpienie usługi Azure usługa wyszukiwania obsługuje kilka wersji interfejsu API REST, w tym najnowsze. Możesz nadal używać wersji, gdy nie jest już najnowsza, ale zalecamy przeprowadzenie migracji kodu w celu korzystania z najnowszej wersji. W przypadku korzystania z interfejsu API REST należy określić wersję interfejsu API w każdym żądaniu za pomocą parametru api-version. W przypadku korzystania z zestawu SDK platformy .NET używana wersja zestawu SDK określa odpowiednią wersję interfejsu API REST. Jeśli używasz starszego zestawu SDK, możesz nadal uruchamiać ten kod bez żadnych zmian, nawet jeśli usługa zostanie uaktualniona do obsługi nowszej wersji interfejsu API.

Co nowego w wersji 9

Wersja 9 zestawu .NET SDK usługi Azure Search jest przeznaczona dla wersji 2019-05-06 interfejsu API REST usługi Azure Search z następującymi funkcjami:

• Wzbogacanie sztucznej inteligencji to możliwość wyodrębniania tekstu z obrazów, obiektów blob i innych źródeł danych bez struktury — wzbogacania zawartości w celu zwiększenia możliwości wyszukiwania w indeksie usługi Azure Search.
• Obsługa typów złożonych umożliwia modelowanie niemal każdej zagnieżdżonej struktury JSON w indeksie usługi Azure Search.
• Funkcja autouzupełniania stanowi alternatywę dla interfejsu API sugerowanego do implementowania zachowania wyszukiwania zgodnie z typem. Autouzupełnianie "kończy" wyraz lub frazę, którą użytkownik aktualnie wpisuje.
• Tryb analizowania JsonLines, część indeksowania obiektów blob, tworzy jeden dokument wyszukiwania na jednostkę JSON oddzieloną nową linią.

Nowe funkcje w wersji zapoznawczej w wersji 8.0-preview

Wersja 8.0 w wersji zapoznawczej zestawu .NET SDK usługi Azure Search jest przeznaczona dla interfejsu API w wersji 2017-11-11-Preview. Ta wersja obejmuje wszystkie te same funkcje wersji 9, a także:

• Klucze szyfrowania zarządzane przez klienta na potrzeby szyfrowania po stronie usługi magazynowanych to nowa funkcja w wersji zapoznawczej. Oprócz wbudowanego szyfrowania magazynowanych zarządzanego przez firmę Microsoft możesz zastosować dodatkową warstwę szyfrowania, w której jesteś jedynym właścicielem kluczy.

Kroki uaktualniania

Najpierw zaktualizuj odwołanie do NuGet przy Microsoft.Azure.Search użyciu konsoli NuGet Menedżer pakietów lub klikając prawym przyciskiem myszy odwołania do projektu i wybierając pozycję "Zarządzaj pakietami NuGet..." w Visual Studio.

Po NuGet pobrać nowe pakiety i ich zależności ponownie skompiluj projekt. W zależności od struktury kodu może ona zostać pomyślnie ponownie skompilowana. Jeśli tak, możesz zacząć!

Jeśli kompilacja zakończy się niepowodzeniem, należy naprawić każdy błąd kompilacji. Aby uzyskać szczegółowe informacje na temat rozwiązywania problemów z każdym potencjalnym błędem kompilacji, zobacz Istotne zmiany w wersji 9 .

Mogą zostać wyświetlone dodatkowe ostrzeżenia kompilacji związane z przestarzałymi metodami lub właściwościami. Ostrzeżenia będą zawierać instrukcje dotyczące sposobu użycia zamiast przestarzałej funkcji. Jeśli na przykład aplikacja używa DataSourceType.DocumentDb właściwości , powinien zostać wyświetlone ostrzeżenie z informacją "Ten element członkowski jest przestarzały. Zamiast tego użyj usługi CosmosDb".

Po usunięciu błędów kompilacji lub ostrzeżeń możesz wprowadzić zmiany w aplikacji, aby skorzystać z nowych funkcji, jeśli chcesz. Nowe funkcje w zestawie SDK są szczegółowo opisane w temacie Co nowego w wersji 9.

Istotne zmiany w wersji 9

Istnieje kilka zmian powodujących niezgodność w wersji 9, które mogą wymagać zmian kodu oprócz ponownego kompilowania aplikacji.

Uwaga

Poniższa lista zmian nie jest wyczerpująca. Niektóre zmiany prawdopodobnie nie spowodują błędów kompilacji, ale z technicznego powodu przerywają zgodność binarną z zestawami zależnymi od wcześniejszych wersji zestawów SDK platformy .NET usługi Azure Search. Takie zmiany nie są wymienione poniżej. Ponownie skompiluj aplikację podczas uaktualniania do wersji 9, aby uniknąć problemów ze zgodnością binarną.

Niezmienne właściwości

Publiczne właściwości kilku klas modelu są teraz niezmienne. Jeśli musisz utworzyć wystąpienia niestandardowe tych klas do testowania, możesz użyć nowych konstruktorów sparametryzowanych:

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

Zmiany w polu

Klasa Field zmieniła się teraz, gdy może również reprezentować złożone pola.

Następujące bool właściwości są teraz dopuszczane do wartości null:

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

Wynika to z tego, że te właściwości muszą teraz znajdować się null w przypadku pól złożonych. Jeśli masz kod odczytujący te właściwości, musi być przygotowany do obsługi nullelementu . Należy pamiętać, że wszystkie inne właściwości Field zawsze były i nadal miały wartość null, a niektóre z nich również będą null miały znaczenie w przypadku złożonych pól — w szczególności następujących:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Konstruktor bez parametrów Field klasy został wykonany .internal Od teraz każda z tych Field metod wymaga jawnej nazwy i typu danych w momencie konstruowania.

Uproszczone typy partii i wyników

W wersji 7.0-preview i starszych różne klasy hermetyzowane grupy dokumentów miały strukturę w hierarchiach klas równoległych:

• DocumentSearchResult i DocumentSearchResult<T> dziedziczone z DocumentSearchResultBase
• DocumentSuggestResult i DocumentSuggestResult<T> dziedziczone z DocumentSuggestResultBase
• IndexAction i IndexAction<T> dziedziczone z IndexActionBase
• IndexBatch i IndexBatch<T> dziedziczone z IndexBatchBase
• SearchResult i SearchResult<T> dziedziczone z SearchResultBase
• SuggestResult i SuggestResult<T> dziedziczone z SuggestResultBase

Typy pochodne bez parametru typu ogólnego miały być używane w scenariuszach typu "dynamicznie" i zakładano użycie Document typu.

Począwszy od wersji 8.0-preview, wszystkie klasy bazowe i klasy pochodne niegeneryczne zostały usunięte. W przypadku scenariuszy typizowanego dynamicznie można użyć poleceń IndexBatch<Document>, DocumentSearchResult<Document>i tak dalej.

Usunięto extensibleEnum

Klasa ExtensibleEnum bazowa została usunięta. Wszystkie klasy, które pochodzą z niego, są teraz strukturami, takimi jak AnalyzerName, DataTypei DataSourceType na przykład. Ich Create metody również zostały usunięte. Można po prostu usunąć wywołania, Create ponieważ te typy są niejawnie konwertowane z ciągów. Jeśli spowoduje to błędy kompilatora, można jawnie wywołać operator konwersji za pomocą rzutowania w celu uściślania typów. Na przykład możesz zmienić kod w następujący sposób:

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

wprowadź następujące zmiany:

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

Właściwości, które posiadały opcjonalne wartości tych typów, są teraz jawnie wpisywane jako dopuszczające wartość null, aby nadal były opcjonalne.

Usunięto element FacetResults i HitHighlights

Klasy FacetResults i HitHighlights zostały usunięte. Wyniki aspektów są teraz wpisywane jako IDictionary<string, IList<FacetResult>> i wyróżniane trafienia jako IDictionary<string, IList<string>>. Szybkim sposobem rozwiązywania błędów kompilacji wprowadzonych przez tę zmianę jest dodanie using aliasów u góry każdego pliku, który używa usuniętych typów. Przykład:

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

Zmień na SynonimMap

Konstruktor SynonymMap nie ma już parametru enum dla .SynonymMapFormat To wyliczenie miało tylko jedną wartość i dlatego było nadmiarowe. Jeśli w wyniku tego zostaną wyświetlone błędy kompilacji, po prostu usuń odwołania do parametru SynonymMapFormat .

Różne zmiany klasy modelu

Właściwość AutocompleteMode elementu AutocompleteParameters nie może już dopuszczać wartości null. Jeśli masz kod, który przypisuje tę właściwość do nullelementu , możesz go po prostu usunąć, a właściwość zostanie automatycznie zainicjowana do wartości domyślnej.

Kolejność parametrów IndexAction konstruktora zmieniła się teraz, gdy ten konstruktor jest generowany automatycznie. Zamiast używać konstruktora, zalecamy użycie metod IndexAction.Uploadfabrycznych , IndexAction.Mergeitd.

Usunięto funkcje w wersji zapoznawczej

Jeśli uaktualniasz wersję 8.0-preview do wersji 9, pamiętaj, że szyfrowanie za pomocą kluczy zarządzanych przez klienta zostało usunięte, ponieważ ta funkcja jest nadal dostępna w wersji zapoznawczej. W szczególności EncryptionKey właściwości Index i SynonymMap zostały usunięte.

Jeśli aplikacja ma twardą zależność od tej funkcji, nie będzie można uaktualnić do wersji 9 zestawu .NET SDK usługi Azure Search. Możesz nadal używać wersji 8.0-preview. Należy jednak pamiętać, że nie zalecamy używania zestawów SDK w wersji zapoznawczej w aplikacjach produkcyjnych. Funkcje w wersji zapoznawczej są przeznaczone tylko do oceny i mogą ulec zmianie.

Uwaga

Jeśli utworzono zaszyfrowane indeksy lub mapy synonimów przy użyciu wersji 8.0-preview zestawu SDK, nadal będzie można ich używać i modyfikować przy użyciu wersji 9 zestawu SDK bez negatywnego wpływu na ich stan szyfrowania. Wersja 9 zestawu SDK nie wyśle encryptionKey właściwości do interfejsu API REST, a w związku z tym interfejs API REST nie zmieni stanu szyfrowania zasobu.

Zmiana behawioralna pobierania danych

Jeśli używasz interfejsów API typu "dynamicznie typizowane" Search, Suggestlub Get interfejsów API, które zwracają wystąpienia typu Document, należy pamiętać, że teraz deserializuje puste tablice JSON na wartość object[] zamiast string[].

Podsumowanie

Jeśli potrzebujesz dodatkowych informacji na temat korzystania z zestawu .NET SDK usługi Azure Search, zobacz instrukcje dotyczące platformy .NET.

Z zadowoleniem przyjmujemy Twoją opinię na temat zestawu SDK. Jeśli napotkasz problemy, możesz poprosić nas o pomoc w witrynie Stack Overflow. Jeśli znajdziesz usterkę, możesz zgłosić problem w repozytorium GitHub zestawu Azure .NET SDK. Pamiętaj, aby prefiksować tytuł problemu z ciągiem "[Azure Search]".

Dziękujemy za korzystanie z usługi Azure Search!