Upgrade na sadu .NET SDK služby Azure Search verze 1.1

Článek
09/16/2021

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

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

Poznámka

Po upgradu na verzi 1.1 nebo pokud už používáte verzi mezi verzemi 1.1 a 2.0-Preview, měli byste upgradovat na verzi 3. Pokyny najdete v tématu Upgrade na sadu .NET SDK služby Azure Search verze 3 .

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

Jakmile NuGet stáhne nové balíčky a jejich závislosti, znovu sestavte projekt.

Pokud jste dříve používali verzi 1.0.0-preview, 1.0.1-preview nebo 1.0.2-preview, měl by build proběhnout úspěšně a jste připravení!

Pokud jste dříve používali verzi 0.13.0-Preview nebo starší, měli byste vidět chyby sestavení, jako je následující:

Program.cs(137,56,137,62): error CS0117: 'Microsoft.Azure.Search.Models.IndexBatch' does not contain a definition for 'Create'
Program.cs(137,99,137,105): error CS0117: 'Microsoft.Azure.Search.Models.IndexAction' does not contain a definition for 'Create'
Program.cs(146,41,146,54): error CS1061: 'Microsoft.Azure.Search.IndexBatchException' does not contain a definition for 'IndexResponse' and no extension method 'IndexResponse' accepting a first argument of type 'Microsoft.Azure.Search.IndexBatchException' could be found (are you missing a using directive or an assembly reference?)
Program.cs(163,13,163,42): error CS0246: The type or namespace name 'DocumentSearchResponse' could not be found (are you missing a using directive or an assembly reference?)

Dalším krokem je oprava chyb sestavení o jeden po druhém. Většina bude vyžadovat změnu některých názvů tříd a metod, které byly přejmenovány v sadě SDK. Seznam zásadních změn ve verzi 1.1 obsahuje seznam těchto změn názvů.

Pokud k modelování dokumentů používáte vlastní třídy a tyto třídy mají vlastnosti nenulových primitivních typů (například int v bool jazyce C#), ve verzi 1.1 sady SDK, o které byste měli vědět, existuje oprava chyby. Další podrobnosti najdete v tématu Opravy chyb ve verzi 1.1 .

Nakonec, jakmile opravíte chyby sestavení, můžete v aplikaci udělat změny, abyste mohli využít nové funkce, pokud chcete.

Seznam zásadních změn ve verzi 1.1

Následující seznam je seřazený pravděpodobností, že změna ovlivní váš kód aplikace.

Změny IndexBatch a IndexAction

IndexBatch.Create byl přejmenován IndexBatch.New na a už nemá params argument. Můžete použít IndexBatch.New dávky, které kombinují různé typy akcí (sloučení, odstranění atd.). Kromě toho existují nové statické metody pro vytváření dávek, kde jsou všechny akce stejné: Delete, , Mergea MergeOrUploadUpload.

IndexAction už nemá veřejné konstruktory a jeho vlastnosti jsou nyní neměnné. Nové statické metody byste měli použít k vytváření akcí pro různé účely: Delete, Merge, a MergeOrUploadUpload. IndexAction.Create byla odebrána. Pokud jste použili přetížení, které přebírá jenom dokument, nezapomeňte místo toho použít Upload .

Příklad

Pokud váš kód vypadá takto:

var batch = IndexBatch.Create(documents.Select(doc => IndexAction.Create(doc)));
indexClient.Documents.Index(batch);

Můžete ho změnit tak, aby se opravily případné chyby sestavení:

var batch = IndexBatch.New(documents.Select(doc => IndexAction.Upload(doc)));
indexClient.Documents.Index(batch);

Pokud chcete, můžete to ještě zjednodušit:

var batch = IndexBatch.Upload(documents);
indexClient.Documents.Index(batch);

Změny indexBatchException

Vlastnost IndexBatchException.IndexResponse byla přejmenována na IndexingResults, a jeho typ je nyní IList<IndexingResult>.

Příklad

Pokud váš kód vypadá takto:

catch (IndexBatchException e)
{
    Console.WriteLine(
        "Failed to index some of the documents: {0}",
        String.Join(", ", e.IndexResponse.Results.Where(r => !r.Succeeded).Select(r => r.Key)));
}

Můžete ho změnit tak, aby se opravily případné chyby sestavení:

catch (IndexBatchException e)
{
    Console.WriteLine(
        "Failed to index some of the documents: {0}",
        String.Join(", ", e.IndexingResults.Where(r => !r.Succeeded).Select(r => r.Key)));
}

Změny metody operace

Každá operace v sadě .NET SDK služby Azure Search je vystavena jako sada přetížení metod pro synchronní a asynchronní volající. Podpisy a faktoring těchto přetížení metody se změnily ve verzi 1.1.

Například operace Získat statistiku indexu ve starších verzích sady SDK odhalila tyto podpisy:

V IIndexOperations:

// Asynchronous operation with all parameters
Task<IndexGetStatisticsResponse> GetStatisticsAsync(
    string indexName,
    CancellationToken cancellationToken);

V IndexOperationsExtensions:

// Asynchronous operation with only required parameters
public static Task<IndexGetStatisticsResponse> GetStatisticsAsync(
    this IIndexOperations operations,
    string indexName);

// Synchronous operation with only required parameters
public static IndexGetStatisticsResponse GetStatistics(
    this IIndexOperations operations,
    string indexName);

Podpisy metody pro stejnou operaci ve verzi 1.1 vypadají takto:

V IIndexesOperations:

// Asynchronous operation with lower-level HTTP features exposed
Task<AzureOperationResponse<IndexGetStatisticsResult>> GetStatisticsWithHttpMessagesAsync(
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions),
    Dictionary<string, List<string>> customHeaders = null,
    CancellationToken cancellationToken = default(CancellationToken));

V IndexesOperationsExtensions:

// Simplified asynchronous operation
public static Task<IndexGetStatisticsResult> GetStatisticsAsync(
    this IIndexesOperations operations,
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions),
    CancellationToken cancellationToken = default(CancellationToken));

// Simplified synchronous operation
public static IndexGetStatisticsResult GetStatistics(
    this IIndexesOperations operations,
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions));

Počínaje verzí 1.1 uspořádá sada Azure Search .NET SDK metody operací odlišně:

Volitelné parametry jsou nyní modelovány jako výchozí parametry, nikoli jako další přetížení metody. To snižuje počet přetížení metod, někdy dramaticky.
Metody rozšíření teď skryjí spoustu nadbytečných podrobností PROTOKOLU HTTP od volajícího. Například starší verze sady SDK vrátily objekt odpovědi se stavovým kódem HTTP, který jste často nemuseli zkontrolovat, protože metody operace vyvolá CloudException všechny stavové kódy, které značí chybu. Nové metody rozšíření jenom vracejí objekty modelu, což vám ušetří potíže s tím, že je budete muset v kódu odbalit.
Naopak základní rozhraní teď zpřístupňují metody, které poskytují větší kontrolu na úrovni HTTP, pokud ho potřebujete. Teď můžete předat vlastní hlavičky HTTP, které se mají zahrnout do požadavků, a nový AzureOperationResponse<T> návratový typ vám poskytne přímý přístup k operaci HttpRequestMessage a HttpResponseMessage pro tuto operaci. AzureOperationResponse je definován v Microsoft.Rest.Azure oboru názvů a nahrazuje Hyak.Common.OperationResponse.

Změny bodováníParameters

V nejnovější sadě SDK byla přidána nová třída s názvem ScoringParameter , která usnadňuje zadávání parametrů pro bodování profilů ve vyhledávacím dotazu. ScoringProfiles Dříve byla vlastnost SearchParameters třídy zadána jako IList<string>; Nyní je zadán jako IList<ScoringParameter>.

Příklad

Pokud váš kód vypadá takto:

var sp = new SearchParameters();
sp.ScoringProfile = "jobsScoringFeatured";      // Use a scoring profile
sp.ScoringParameters = new[] { "featuredParam-featured", "mapCenterParam-" + lon + "," + lat };

Můžete ho změnit tak, aby se opravily případné chyby sestavení:

var sp = new SearchParameters();
sp.ScoringProfile = "jobsScoringFeatured";      // Use a scoring profile
sp.ScoringParameters =
    new[]
    {
        new ScoringParameter("featuredParam", new[] { "featured" }),
        new ScoringParameter("mapCenterParam", GeographyPoint.Create(lat, lon))
    };

Změny třídy modelu

Vzhledem ke změnám podpisů popsaných v metodě Operace se mnoho tříd v Microsoft.Azure.Search.Models oboru názvů přejmenovalo nebo odebralo. Příklad:

IndexDefinitionResponse byla nahrazena AzureOperationResponse<Index>
Přejmenování DocumentSearchResponse na DocumentSearchResult
Přejmenování IndexResult na IndexingResult
Documents.Count() Nyní vrátí long počet dokumentů místo počtu dokumentů. DocumentCountResponse
Přejmenování IndexGetStatisticsResponse na IndexGetStatisticsResult
Přejmenování IndexListResponse na IndexListResult

Pokud chcete sumarizovat, OperationResponsebyly odebrány odvozené třídy, které existovaly pouze k zabalení objektu modelu. Zbývající třídy měly jejich příponu změněnou od Response na Result.

Příklad

Pokud váš kód vypadá takto:

IndexerGetStatusResponse statusResponse = null;

try
{
    statusResponse = _searchClient.Indexers.GetStatus(indexer.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Error polling for indexer status: {0}", ex.Message);
    return;
}

IndexerExecutionResult lastResult = statusResponse.ExecutionInfo.LastResult;

Můžete ho změnit tak, aby se opravily případné chyby sestavení:

IndexerExecutionInfo status = null;

try
{
    status = _searchClient.Indexers.GetStatus(indexer.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Error polling for indexer status: {0}", ex.Message);
    return;
}

IndexerExecutionResult lastResult = status.LastResult;

Třídy odpovědí a IEnumerable

Další změna, která může ovlivnit váš kód, je, že třídy odpovědí, které obsahují kolekce, už neimplementují IEnumerable<T>. Místo toho můžete k vlastnosti kolekce přistupovat přímo. Pokud například váš kód vypadá takto:

DocumentSearchResponse<Hotel> response = indexClient.Documents.Search<Hotel>(searchText, sp);
foreach (SearchResult<Hotel> result in response)
{
    Console.WriteLine(result.Document);
}

Můžete ho změnit tak, aby se opravily případné chyby sestavení:

DocumentSearchResult<Hotel> response = indexClient.Documents.Search<Hotel>(searchText, sp);
foreach (SearchResult<Hotel> result in response.Results)
{
    Console.WriteLine(result.Document);
}

Speciální případ pro webové aplikace

Pokud máte webovou aplikaci, která serializuje DocumentSearchResponse přímo pro odesílání výsledků hledání do prohlížeče, budete muset změnit kód nebo výsledky nebudou serializovat správně. Pokud například váš kód vypadá takto:

public ActionResult Search(string q = "")
{
    // If blank search, assume they want to search everything
    if (string.IsNullOrWhiteSpace(q))
        q = "*";

    return new JsonResult
    {
        JsonRequestBehavior = JsonRequestBehavior.AllowGet,
        Data = _featuresSearch.Search(q)
    };
}

Můžete ho změnit tak, že .Results získáte vlastnost odpovědi vyhledávání a opravíte vykreslování výsledků hledání:

public ActionResult Search(string q = "")
{
    // If blank search, assume they want to search everything
    if (string.IsNullOrWhiteSpace(q))
        q = "*";

    return new JsonResult
    {
        JsonRequestBehavior = JsonRequestBehavior.AllowGet,
        Data = _featuresSearch.Search(q).Results
    };
}

V kódu budete muset hledat takové případy sami; Kompilátor vás nebude varovat , protože JsonResult.Data je typ object.

Změny cloudexceptionu

Třída CloudException se přesunula z Hyak.Common oboru názvů do Microsoft.Rest.Azure oboru názvů. Také jeho Error vlastnost byla přejmenována na Body.

Změny SearchServiceClient a SearchIndexClient

Typ Credentials vlastnosti se změnil z SearchCredentials jeho základní třídy, ServiceClientCredentials. Pokud potřebujete získat přístup k SearchCredentialsSearchIndexClient nebo SearchServiceClient, použijte novou SearchCredentials vlastnost.

Ve starších verzích sady SDK a SearchIndexClient měl konstruktory, SearchServiceClient které vzaly HttpClient parametr. Tyto objekty byly nahrazeny konstruktory, které přebírají HttpClientHandler pole DelegatingHandler objektů. To usnadňuje instalaci vlastních obslužných rutin pro předběžné zpracování požadavků HTTP v případě potřeby.

Nakonec konstruktory, které vzaly Uri a SearchCredentials změnily se. Pokud máte například kód, který vypadá takto:

var client =
    new SearchServiceClient(
        new SearchCredentials("abc123"),
        new Uri("http://myservice.search.windows.net"));

Můžete ho změnit tak, aby se opravily případné chyby sestavení:

var client =
    new SearchServiceClient(
        new Uri("http://myservice.search.windows.net"),
        new SearchCredentials("abc123"));

Všimněte si také, že typ parametru přihlašovacích údajů se změnil na ServiceClientCredentials. To není pravděpodobné, že by to ovlivnilo váš kód, protože SearchCredentials je odvozen z ServiceClientCredentials.

Předání ID požadavku

Ve starších verzích sady SDK můžete nastavit ID požadavku na SearchServiceClient rozhraní REST API nebo SearchIndexClient ho zahrnout do každého požadavku rozhraní REST API. To je užitečné pro řešení problémů s vyhledávací službou, pokud potřebujete kontaktovat podporu. Je ale užitečnější nastavit jedinečné ID požadavku pro každou operaci, nikoli použít stejné ID pro všechny operace. Z tohoto důvodu SetClientRequestId byly metody SearchServiceClient a SearchIndexClient byly odebrány. Místo toho můžete předat ID požadavku každé metodě operace prostřednictvím volitelného SearchRequestOptions parametru.

Poznámka

V budoucí verzi sady SDK přidáme nový mechanismus pro globální nastavení ID požadavku na objekty klienta, který je konzistentní s přístupem používaným jinými sadami AZURE SDK.

Příklad

Pokud máte kód, který vypadá takto:

client.SetClientRequestId(Guid.NewGuid());
...
long count = client.Documents.Count();

Pokud chcete opravit případné chyby sestavení, můžete ho změnit na tento postup:

long count = client.Documents.Count(new SearchRequestOptions(requestId: Guid.NewGuid()));

Změny názvu rozhraní

Názvy rozhraní skupiny operací se změnily tak, aby byly konzistentní s odpovídajícími názvy vlastností:

Typ ISearchServiceClient.Indexes se přejmenoval z IIndexOperations na IIndexesOperations.
Typ ISearchServiceClient.Indexers se přejmenoval z IIndexerOperations na IIndexersOperations.
Typ ISearchServiceClient.DataSources se přejmenoval z IDataSourceOperations na IDataSourcesOperations.
Typ ISearchIndexClient.Documents se přejmenoval z IDocumentOperations na IDocumentsOperations.

Tato změna pravděpodobně nemá vliv na váš kód, pokud jste pro účely testování nevytvořili napodobení těchto rozhraní.

Opravy chyb ve verzi 1.1

Ve starších verzích sady .NET SDK služby Azure Search došlo k chybě související se serializací vlastních tříd modelů. K chybě může dojít v případě, že jste vytvořili vlastní třídu modelu s vlastností typu hodnoty, která nemá hodnotu null.

Kroky pro reprodukci

Vytvořte vlastní třídu modelu s vlastností typu hodnoty, která není nullable. Přidejte například veřejnou UnitCount vlastnost typu int místo int?.

Pokud indexujete dokument s výchozí hodnotou tohoto typu (například 0 pro int), bude pole ve službě Azure Search null. Pokud následně vyhledáte tento dokument, Search hovor si stěžuje JsonSerializationException , že se nedá převést null na int.

Filtry také nemusí fungovat podle očekávání, protože hodnota null byla zapsána do indexu místo zamýšlené hodnoty.

Oprava podrobností

Tento problém jsme opravili ve verzi 1.1 sady SDK. Pokud teď máte třídu modelu takto:

public class Model
{
    public string Key { get; set; }

    public int IntValue { get; set; }
}

a nastavíte IntValue hodnotu 0, tato hodnota je nyní správně serializována jako 0 na drátě a uložena jako 0 v indexu. Zaokrouhlování funguje podle očekávání.

Při použití tohoto přístupu je možné zjistit jeden potenciální problém: Pokud používáte typ modelu s nenulovou vlastností, musíte zaručit , že žádné dokumenty v indexu neobsahují hodnotu null pro odpovídající pole. S vynucování této sady vám pomůže sada SDK ani rozhraní REST API služby Azure Search.

Nejedná se pouze o hypotetický problém: představte si situaci, kdy přidáte nové pole do stávajícího indexu typu Edm.Int32. Po aktualizaci definice indexu budou mít všechny dokumenty pro toto nové pole hodnotu null (protože všechny typy jsou ve službě Azure Search s možností null). Pokud pak použijete třídu modelu s vlastností int se zakázanou hodnotou null, při pokusu o načtení dokumentů dojde k vyvolání podobné výjimky JsonSerializationException:

Error converting value {null} to type 'System.Int32'. Path 'IntValue'.

Z tohoto důvodu stále doporučujeme používat typy s možnou hodnotou null ve třídách modelu jako osvědčený postup.

Další podrobnosti o této chybě a opravě najdete v tomto problému v GitHub.

Sdílet prostřednictvím

Upgrade na sadu .NET SDK služby Azure Search verze 1.1

Seznam zásadních změn ve verzi 1.1

Změny IndexBatch a IndexAction

Příklad

Změny indexBatchException

Příklad

Změny metody operace

Změny bodováníParameters

Příklad

Změny třídy modelu

Příklad

Třídy odpovědí a IEnumerable

Speciální případ pro webové aplikace

Změny cloudexceptionu

Změny SearchServiceClient a SearchIndexClient

Předání ID požadavku

Příklad

Změny názvu rozhraní

Opravy chyb ve verzi 1.1

Kroky pro reprodukci

Oprava podrobností

Další materiály