Uaktualnij do wersji 9 zestawu SDK .NET dla usługi Azure Search

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

Aby uzyskać bardziej ogólny przewodnik po SDK, w tym przykłady, zobacz Jak używać usługi Azure Search z aplikacji platformy .NET.

Wersja 9 zestawu .NET SDK usługi Azure Search zawiera wiele zmian z wcześniejszych wersji. Niektóre z nich są zmianami naruszającymi kompatybilność, ale powinny wymagać tylko stosunkowo niewielkich modyfikacji w kodzie. Aby uzyskać instrukcje dotyczące zmiany kodu w celu korzystania z nowej wersji zestawu SDK, zobacz Kroki uaktualniania.

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 — wzbogacanie zawartości w celu zwiększenia możliwości wyszukiwania w indeksie usługi Azure Search.
• Obsługa złożonych typów umożliwia modelowanie niemal każdej zagnieżdżonej struktury JSON w indeksie usługi Azure Search.
• Autouzupełnianie stanowi alternatywę dla interfejsu API Suggest do implementowania wyszukiwania w czasie rzeczywistym podczas pisania. Autouzupełnianie "kończy" wyraz lub frazę, którą użytkownik obecnie wpisuje.
• Tryb analizowania JsonLines, część indeksowania obiektów blob, tworzy jeden dokument wyszukiwania dla jednostki JSON oddzielonej nową linią.

Nowe funkcje zapoznawcze w wersji 8.0-preview

Wersja 8.0-preview zestawu SDK dla platformy .NET 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 w spoczynku to nowa funkcja w wersji zapoznawczej. Oprócz wbudowanego szyfrowania spoczynkowego zarządzanego przez Microsoft, można zastosować dodatkową warstwę szyfrowania, gdzie jesteś jedynym właścicielem kluczy.

Kroki uaktualniania

Najpierw zaktualizuj odwołanie NuGet dla Microsoft.Azure.Search za pomocą Konsoli Menedżera pakietów NuGet lub kliknij prawym przyciskiem myszy odwołania do projektu i wybierz pozycję "Zarządzaj pakietami NuGet..." w programie Visual Studio.

Gdy NuGet pobierze nowe pakiety i ich zależności, przebuduj projekt. W zależności od struktury kodu, może on zostać pomyślnie odbudowany. Jeśli tak, możesz zacząć!

Jeśli kompilacja zakończy się niepowodzeniem, należy naprawić każdy błąd kompilacji. Zobacz Istotne zmiany w wersji 9 , aby uzyskać szczegółowe informacje na temat sposobu rozwiązywania każdego potencjalnego błędu kompilacji.

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 tego, co użyć 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 zostały 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.

Niezmienne właściwości

Publiczne właściwości kilku klas modelu są teraz niezmienne. Jeśli chcesz 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.

bool Następujące właściwości mogą przyjmować wartość null:

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

Wynika to z faktu, że te właściwości muszą teraz znajdować się null w przypadku pól złożonych. Jeśli masz kod, który odczytuje te właściwości, musi być przygotowany do obsługi null. 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 będą null również miały wartość w przypadku złożonych pól — w szczególności następujących:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

Konstruktor bez parametrów Field został internal. Od tej pory każde Field wymaga jawnej nazwy i typu danych w czasie tworzenia.

Uproszczone typy serii i wyników

W wersji 7.0-preview i starszych różne klasy obejmujące grupy dokumentów zostały zorganizowane w równoległe hierarchie klas.

• 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 były przeznaczone do użycia w scenariuszach z dynamicznie typowanymi kontekstami i zakładano użycie typu Document.

Począwszy od wersji 8.0-preview, wszystkie klasy bazowe i klasy pochodne inne niż ogólne zostały usunięte. W przypadku scenariuszy dynamicznie typowanych możesz użyć 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 zostały również usunięte. Możesz 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 pośrednictwem rzutowania w celu uściślania typów. Możesz na przykład 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 }
    },
    ...
}

w tym celu:

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 miały opcjonalne wartości tych typów, są teraz jawnie określane jako akceptujące wartość null, aby nadal pozostał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>> wyróżnione i wyróżnione 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 korzystającego z 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 SynonimMapa

Konstruktor SynonymMap nie ma już parametru enum dla .SynonymMapFormat Wyliczenie miało tylko jedną wartość i dlatego było zbędne. Jeśli w wyniku tego wystąpią błędy kompilacji, po prostu usuń odwołania do parametru SynonymMapFormat .

Różne zmiany klas modelu

Właściwość AutocompleteMode elementu AutocompleteParameters przestała być możliwa do ustawienia jako null. Jeśli masz kod, który przypisuje tę właściwość do null, 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.Mergei tak dalej.

Usunięto funkcje w wersji zapoznawczej

Jeśli uaktualniasz wersję 8.0-preview do wersji 9, pamiętaj, że szyfrowanie przy użyciu kluczy zarządzanych przez klienta zostało usunięte, ponieważ ta funkcja jest nadal dostępna w wersji zapoznawczej. Szczególnie usunięto właściwości EncryptionKey z Index i SynonymMap.

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 wersji zapoznawczych SDK w aplikacjach produkcyjnych. Funkcje w wersji zapoznawczej są przeznaczone tylko do oceny i mogą ulec zmianie.

Zmiana zachowania pobierania danych

Jeśli używasz API "dynamicznie typizowane" Search, Suggest, lub Get, które zwracają wystąpienia typu Document, należy pamiętać, że teraz deserializują puste tablice JSON do object[] zamiast string[].

Podsumowanie

Jeśli potrzebujesz dodatkowych informacji na temat korzystania z Azure Search .NET SDK, zobacz .NET How-to.

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

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