Atualizar para o SDK do .NET do Azure Search versão 3

Se você estiver usando a versão 2.0 prévia ou anterior do SDK do .NET do Azure Search, este artigo ajudará você a atualizar seu aplicativo para usar a versão 3.

Para obter um passo a passo mais geral do SDK, incluindo exemplos, consulte Como usar o Azure Search de um aplicativo .NET.

A versão 3 do SDK do .NET do Azure Search contém algumas alterações de versões anteriores. Eles são principalmente menores, portanto, a alteração do código deve exigir apenas esforço mínimo. Consulte As Etapas para atualizar para obter instruções sobre como alterar seu código para usar a nova versão do SDK.

Novidades na versão 3

A versão 3 do Azure Search .NET SDK é direcionada para a versão mais recente geralmente disponível da API REST do Azure Search, especificamente 2016-09-01. Isso possibilita o uso de muitos novos recursos do Azure Search de um aplicativo .NET, incluindo o seguinte:

• Analisadores personalizados
• Suporte ao indexador para Armazenamento de Blobs do Azure e Armazenamento de Tabelas do Azure
• Personalização do indexador por meio de mapeamentos de campo
• Suporte a ETags para habilitar a atualização simultânea segura de definições de índice, indexadores e fontes de dados
• Suporte para criar definições de campo de índice declarativamente decorando a classe do seu modelo e usando a nova classe FieldBuilder.
• Suporte para .NET Core e .NET Portable Profile 111

Etapas da atualização

Primeiro, atualize a referência do 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 baixar os novos pacotes e suas dependências, recompile seu projeto. Dependendo de como o código é estruturado, ele pode ser recriado com êxito. Se sim, você está pronto para ir!

Se o build falhar, você deverá ver um erro de build como o seguinte:

Program.cs(31,45,31,86): error CS0266: Cannot implicitly convert type 'Microsoft.Azure.Search.ISearchIndexClient' to 'Microsoft.Azure.Search.SearchIndexClient'. An explicit conversion exists (are you missing a cast?)

A próxima etapa é corrigir esse erro de build. Consulte mudanças drásticas na versão 3 para obter detalhes sobre as causas do erro e como corrigi-lo.

Você pode ver avisos de build adicionais relacionados a métodos ou propriedades obsoletas. Os avisos incluirão instruções sobre o que usar em vez do recurso preterido. Por exemplo, se o aplicativo usar a IndexingParameters.Base64EncodeKeys propriedade, você deverá receber um aviso que diz "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead."

Depois de corrigir erros de build, você pode fazer alterações em seu aplicativo para aproveitar a nova funcionalidade, se desejar. Novos recursos no SDK são detalhados nas novidades da versão 3.

Alterações significativas na versão 3

Há um pequeno número de alterações significativas na versão 3 que podem exigir alterações de código além de recriar seu aplicativo.

Tipo de retorno da função Indexes.GetClient

O Indexes.GetClient método tem um novo tipo de retorno. Anteriormente, ele retornava SearchIndexClient, mas isso foi alterado para ISearchIndexClient a versão 2.0-preview, e essa alteração passa para a versão 3. Isso é para dar suporte a clientes que desejam simular o GetClient método para testes de unidade retornando uma implementação simulada de ISearchIndexClient.

Exemplo

Se o código tiver esta aparência:

SearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

Você pode alterá-lo para corrigir erros de build:

ISearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

AnalyzerName, DataType e outros não são mais implicitamente conversíveis em cadeias de caracteres

Há muitos tipos no SDK do .NET do Azure Search que derivam de ExtensibleEnum. Anteriormente, esses tipos eram todos implicitamente conversíveis para o tipo string. No entanto, um bug foi descoberto na Object.Equals implementação dessas classes, e corrigir o bug exigiu desabilitar essa conversão implícita. A conversão string explícita ainda é permitida.

Exemplo

Se o código tiver esta aparência:

var customTokenizerName = TokenizerName.Create("my_tokenizer"); 
var customTokenFilterName = TokenFilterName.Create("my_tokenfilter"); 
var customCharFilterName = CharFilterName.Create("my_charfilter"); 
 
var index = new Index();
index.Analyzers = new Analyzer[] 
{ 
    new CustomAnalyzer( 
        "my_analyzer",  
        customTokenizerName,  
        new[] { customTokenFilterName },  
        new[] { customCharFilterName }), 
}; 

Você pode alterá-lo para corrigir erros de build:

const string CustomTokenizerName = "my_tokenizer"; 
const string CustomTokenFilterName = "my_tokenfilter"; 
const string CustomCharFilterName = "my_charfilter"; 
 
var index = new Index();
index.Analyzers = new Analyzer[] 
{ 
    new CustomAnalyzer( 
        "my_analyzer",  
        CustomTokenizerName,  
        new TokenFilterName[] { CustomTokenFilterName },  
        new CharFilterName[] { CustomCharFilterName })
}; 

Membros obsoletos removidos

Você pode ver erros de build relacionados a métodos ou propriedades que foram marcados como obsoletos na versão 2.0-preview e posteriormente removidos na versão 3. Se você encontrar esses erros, veja como resolvê-los:

• Se você estava usando este construtor: ScoringParameter(string name, string value)use este em vez disso: ScoringParameter(string name, IEnumerable<string> values)
• Se você estiver usando a propriedade ScoringParameter.Value, use a propriedade ScoringParameter.Values ou o método ToString.
• Se você estiver usando a SearchRequestOptions.RequestId propriedade, use a ClientRequestId propriedade em vez disso.

Recursos de visualização removidos

Se você estiver atualizando da versão 2.0-preview para a versão 3, lembre-se de que o suporte de análise JSON e CSV para Indexadores de Blob foi removido, pois esses recursos ainda estão em versão prévia. Especificamente, os seguintes métodos da classe IndexingParametersExtensions foram removidos:

• ParseJson
• ParseJsonArrays
• ParseDelimitedTextFiles

Se o aplicativo tiver uma dependência rígida desses recursos, você não poderá atualizar para a versão 3 do SDK do .NET do Azure Search. Você pode continuar a usar a versão 2.0-preview. No entanto, tenha em mente que não recomendamos o uso de SDKs de versão prévia em aplicativos de produção. Os recursos de visualização são apenas para avaliação e podem ser alterados.

Conclusão

Se você precisar de mais detalhes sobre como usar o SDK do .NET do Azure Search, consulte o instruções do .NET.

Damos as boas-vindas aos seus comentários sobre o SDK. Se você encontrar problemas, fique à vontade para nos pedir ajuda no Stack Overflow. Se encontrar um bug, você poderá registrar um problema no repositório GitHub do SDK do .NET do Azure. Certifique-se de prefixar o título do problema com "[Azure Search]".

Obrigado por usar o Azure Search!