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

Se você estiver usando a versão 2.0-preview ou mais antiga do SDK .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 a Pesquisa do Azure a partir de um aplicativo .NET.

A versão 3 do SDK .NET do Azure Search contém algumas alterações de versões anteriores. Estes são, na sua maioria, menores, pelo que alterar o seu código deve exigir apenas um esforço mínimo. Consulte etapas para atualizar para obter instruções sobre como alterar seu código para usar a nova versão do SDK.

O que há de novo na versão 3

A versão 3 do SDK .NET do Azure Search destina-se à versão mais recente disponível em geral da API REST do Azure Search, especificamente 2016-09-01. Isso torna possível usar muitos recursos novos da Pesquisa do Azure a partir de um aplicativo .NET, incluindo o seguinte:

• Analisadores personalizados
• Suporte ao indexador do Armazenamento de Blobs do Azure e do Armazenamento de Tabela do Azure
• Personalização do indexador através de mapeamentos de campo
• Suporte a ETags para permitir 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 de forma declarativa, decorando a sua classe de modelo e usando a nova classe FieldBuilder.
• Suporte para .NET Core e .NET Portable Profile 111

Passos para atualizar

Primeiro, atualize sua 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 tiver baixado os novos pacotes e suas dependências, reconstrua seu projeto. Dependendo de como seu código está estruturado, ele pode ser reconstruído com êxito. Se sim, você está pronto para ir!

Se sua compilação falhar, você verá um erro de compilação 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?)

O próximo passo é corrigir esse erro de compilação. Consulte Alterações significativas na versão 3 para obter detalhes sobre o que causa o erro e como corrigi-lo.

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

Depois de corrigir quaisquer erros de compilação, você pode fazer alterações em seu aplicativo para aproveitar a nova funcionalidade, se desejar. Os novos recursos do SDK são detalhados em Novidades na versão 3.

Alterações significativas na versão 3

Há um pequeno número de alterações críticas na versão 3 que podem exigir alterações de código, além de reconstruir a sua aplicação.

Tipo de retorno do Indexes.GetClient

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

Exemplo

Se o seu código tiver esta aparência:

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

Você pode alterá-lo para isso para corrigir quaisquer erros de compilação:

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 .NET do Azure Search que derivam do ExtensibleEnum. Anteriormente, estes tipos eram todos implicitamente convertíveis em tipo string. No entanto, um bug foi descoberto na Object.Equals implementação para essas classes, e a correção do bug exigiu desativar essa conversão implícita. A conversão explícita para string ainda é permitida.

Exemplo

Se o seu 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 isso para corrigir quaisquer erros de compilação:

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 compilação relacionados a métodos ou propriedades que foram marcados como obsoletos na versão 2.0-preview e subsequentemente removidos na versão 3. Se você encontrar tais erros, aqui está 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ê estava usando a ScoringParameter.Value propriedade, use a ScoringParameter.Values propriedade ou o ToString método em vez disso.
• Se usavas a propriedade SearchRequestOptions.RequestId, usa antes a propriedade ClientRequestId.

Recursos de visualização removidos

Se estiver a atualizar da versão 2.0-preview para a versão 3, esteja ciente de que o suporte à análise de JSON e CSV para os Indexadores de Blob foi removido, uma vez que estas funcionalidades ainda estão em pré-visualização. Especificamente, os seguintes métodos da classe IndexingParametersExtensions foram removidos:

• ParseJson
• ParseJsonArrays
• ParseDelimitedTextFiles

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

Conclusão

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

Agradecemos o seu feedback sobre o SDK. Se você encontrar problemas, sinta-se à vontade para nos pedir ajuda sobre Stack Overflow. Se você encontrar um bug, poderá registrar um problema no repositório GitHub do SDK do Azure .NET. Certifique-se de prefixar o título do problema com "[Azure Search]".

Obrigado por usar o Azure Search!