Atualização para o SDK do .NET do Azure Search versão 9

Se você estiver usando a versão prévia 7.0 ou uma mais antiga do SDK .NET do Azure Search, este artigo irá ajudá-lo a atualizar seu aplicativo para usar a versão 9.

Observação

Se quiser usar a versão prévia 8.0 para avaliar recursos que ainda não estão disponíveis, você também poderá seguir as instruções neste artigo para fazer a atualização de versões anteriores para a versão prévia 8.0.

Para obter uma explicação mais geral do SDK, incluindo exemplos, confira Como usar o Azure Search de um aplicativo .NET.

A versão 9 do SDK do .NET do Azure Search contém várias alterações das versões anteriores. Algumas são alterações interruptivas, mas devem exigir apenas alterações relativamente secundárias no código. Confira Etapas da atualização para obter instruções sobre como alterar o seu código para usar a nova versão do SDK.

Observação

Se estiver usando a versão prévia 4.0 ou versões mais antigas, será necessário primeiro atualizar para a versão 5 e, em seguida, atualizar para a versão 9. Consulte Atualização para o SDK do .NET do Azure Search versão 5 para obter instruções.

Sua instância de serviço do Azure Search dá suporte a várias versões da API REST, incluindo a última. Você pode continuar usando uma versão quando ela não for mais a última, mas aconselhamos a migrar seu código para usar a versão mais recente. Ao usar a API REST, você deve especificar a versão da API em cada solicitação por meio do parâmetro api-version. Ao usar o SDK do .NET, a versão do SDK que você está usando determina a versão correspondente da API REST. Se estiver usando um SDK mais antigo, você poderá continuar executando esse código sem alterações, mesmo se o serviço for atualizado para dar suporte a uma versão de API mais recente.

Novidades na versão 9

A versão 9 do SDK do .NET do Azure Search tem como destino a versão 06–05–2019 da API REST do Azure Search, com os seguintes recursos:

• Enriquecimento de IA – capacidade de extrair texto de imagens, blobs e outras fontes de dados não estruturados – enriquecendo o conteúdo para facilitar a pesquisa no índice do Azure Search.
• Suporte para tipos complexos – permite modelar quase todas as estruturas JSON aninhadas em um índice do Azure Search.
• Preenchimento automático – fornece uma alternativa para a API de Sugestão para implementar o comportamento search-as-you-type (pesquisar ao digitar). O preenchimento automático "termina" a palavra ou expressão que um usuário está digitando no momento.
• O modo de análise de JsonLines, parte da indexação de blobs, cria um documento de pesquisa por entidade JSON que é separada por uma nova linha.

Novos recursos na versão prévia 8.0

A Versão prévia 8.0 do SDK do .NET do Azure Search tem como destino a versão prévia 11–11–2017 da API. Além de todos os recursos da versão 9, ela também inclui:

• Chaves de criptografia gerenciadas pelo cliente – novo recurso da versão prévia para a criptografia em repouso do lado do serviço. Além da criptografia interna em repouso gerenciada pela Microsoft, você pode aplicar uma camada adicional de criptografia onde for o único proprietário das chaves.

Etapas da atualização

Primeiro, atualize sua referência NuGet para Microsoft.Azure.Search usando o Console do Gerenciador de Pacotes NuGet ou clicando com o botão direito do mouse nas referências do projeto e selecionando “Gerenciar pacotes NuGet...” no Visual Studio.

Depois que o NuGet tiver baixado os novos pacotes e suas dependências, recompile o projeto. Dependendo de como o código está estruturado, ele poderá ser recriado com êxito. Nesse caso, você está pronto para começar!

Se sua compilação falhar, você precisará corrigir cada erro de compilação. Consulte Alterações interruptivas na versão 9 para obter detalhes sobre como resolver cada erro de compilação em potencial.

Você pode ver avisos de build adicionais relacionados a propriedades ou métodos obsoletos. Os avisos incluirão instruções sobre o que deve ser usado no lugar do recurso preterido. Por exemplo, se seu aplicativo usar a propriedade DataSourceType.DocumentDb, você deverá obter um aviso que diz "Este membro é preterido. Use CosmosDb no lugar".

Após corrigir todos os avisos ou erros de build, você poderá fazer alterações no aplicativo para aproveitar as novas funcionalidades, se desejar. Os novos recursos no SDK estão detalhados em Novidades na versão 9.

Alterações interruptivas na versão 9

Há várias alterações interruptivas na versão 9 que podem exigir alterações de código, além da recompilação do aplicativo.

Observação

A lista de alterações abaixo não é exaustiva. Algumas alterações provavelmente não resultarão em erros de compilação, mas são tecnicamente interruptivas, pois interrompem a compatibilidade binária com assemblies que dependem de versões anteriores dos assemblies do SDK do .NET do Azure Search. Essas alterações não estão listadas abaixo. Recompile o aplicativo ao atualizar para a versão 9, para evitar problemas de compatibilidade binária.

Propriedades imutáveis

As propriedades públicas de várias classes de modelo agora são imutáveis. Se precisar criar instâncias personalizadas dessas classes para teste, você poderá usar os novos construtores com parâmetros:

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

Alterações em Campo

A classe Field foi alterada pois ela também pode representar campos complexos.

As propriedades bool a seguir são agora anuláveis:

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

Isso ocorre porque agora elas devem ser null no caso de campos complexos. Se tiver um código que leia essas propriedades, ele precisará estar preparado para tratar null. Observe que todas as outras propriedades de Field sempre foram e continuam anuláveis e algumas também serão null no caso de campos complexos – especificamente os seguintes:

• Analyzer
• SearchAnalyzer
• IndexAnalyzer
• SynonymMaps

O construtor sem parâmetros de Field torna-se internal. De agora em diante, cada Field exige um nome explícito e um tipo de dados no momento da construção.

Tipos de resultados e lote simplificados

Na versão prévia 7.0 e nas anteriores, as várias classes que encapsulam grupos de documentos foram estruturadas em hierarquias de classe paralelas:

• DocumentSearchResult e DocumentSearchResult<T> são herdadas de DocumentSearchResultBase
• DocumentSuggestResult e DocumentSuggestResult<T> são herdadas de DocumentSuggestResultBase
• IndexAction e IndexAction<T> são herdadas de IndexActionBase
• IndexBatch e IndexBatch<T> são herdadas de IndexBatchBase
• SearchResult e SearchResult<T> são herdadas de SearchResultBase
• SuggestResult e SuggestResult<T> são herdadas de SuggestResultBase

Os tipos derivados sem um parâmetro de tipo genérico foram destinados a serem usados em cenários "tipados dinamicamente" e uso assumido do tipo Document.

A partir da versão prévia 8.0, as classes base e as classes derivadas não genéricas foram removidas. Para cenários tipados dinamicamente, você pode usar IndexBatch<Document>, DocumentSearchResult<Document> e assim por diante.

ExtensibleEnum removida

A classe de base ExtensibleEnum foi removida. Todas as classes derivadas dela são agora structs, como AnalyzerName, DataType e DataSourceType, por exemplo. Os métodos Create também foram removidos. É possível apenas remover chamadas para Create, pois esses tipos podem ser convertidos implicitamente de cadeias. Se isso resultar em erros de compilador, você poderá invocar explicitamente o operador de conversão por transmissão para desfazer a ambiguidade de tipos. Por exemplo, você pode alterar um código como este:

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

para isto:

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

As propriedades que mantinham valores opcionais desses tipos são agora tipadas explicitamente como anuláveis, para que continuem a ser opcionais.

FacetResults e HitHighlights removidos

As classes FacetResults e HitHighlights foram removidas. Os resultados da faceta são agora tipados como IDictionary<string, IList<FacetResult>> e os realces de clique como IDictionary<string, IList<string>>. Uma maneira rápida de resolver os erros de compilação apresentados por essa alteração é adicionar aliases using na parte superior de cada arquivo que use os tipos removidos. Por exemplo:

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

Alterar para SynonymMap

O construtor SynonymMap não tem mais um parâmetro enum para SynonymMapFormat. Essa enumeração tinha apenas um valor e, portanto, era redundante. Se você observar erros de build como um resultado disso, basta remover as referências para o parâmetro SynonymMapFormat.

Alterações diversas de classe de modelo

A propriedade AutocompleteMode de AutocompleteParameters não é mais anulável. Se tiver um código que atribua essa propriedade a null, você poderá simplesmente removê-la e a propriedade será inicializada automaticamente no valor padrão.

A ordem dos parâmetros para o construtor IndexAction foi alterada, pois agora esse construtor é gerado automaticamente. Em vez de usar o construtor, é recomendável usar os métodos de fábrica IndexAction.Upload, IndexAction.Merge e assim por diante.

Recursos de visualização removidos

Se estiver atualizando da versão prévia 8.0 para a versão 9, lembre-se de que a criptografia com chaves gerenciadas pelo cliente foi removida, pois esse recurso ainda está em versão prévia. Especificamente, as propriedades EncryptionKey de Index e SynonymMap foram removidas.

Se seu aplicativo tiver uma dependência rígida desse recurso, você não poderá atualizar para a versão 9 do SDK do .NET do Azure Search. Você pode continuar a usar a versão prévia 8.0. No entanto, lembre-se que não é recomendável usar SDKs de visualização em aplicativos de produção. Os recursos de visualização destinam-se apenas a fins de avaliação e podem ser alterados.

Observação

Se você criou índices criptografados ou mapas de sinônimos usando a versão prévia 8.0 do SDK, ainda poderá usá-los e modificar suas definições usando a versão 9 do SDK, sem afetar negativamente o status da criptografia. A versão 9 do SDK não enviará a propriedade encryptionKey para a API REST e, como resultado, a API REST não alterará o status da criptografia do recurso.

Alteração comportamental na recuperação de dados

Se estiver usando as APIs "tipadas dinamicamente" Search, Suggest ou Get que retornam instâncias do tipoDocument, lembre-se de que agora elas desserializam matrizes JSON vazias emobject[] no lugar de string[].

Conclusão

Se precisar de mais detalhes sobre como usar o SDK do .NET do Azure Search, confira o Tutorial .NET.

Apreciamos os seus comentários sobre o SDK. Se você encontrar problemas, sinta-se à vontade para pedir ajuda no Stack Overflow. Se encontrar um bug, você poderá apresentar um problema no repositório GitHub sobre o SDK do .NET do Azure. Não deixe de colocar o prefixo "[Azure Search]" no título do problema.

Obrigado por usar o Azure Search!