Partilhar via

Upgrade para Azure Search .NET SDK versão 3

  • Artigo

Se estiver a utilizar a versão 2.0 pré-visualização ou mais antiga do Azure Search .NET SDK, este artigo irá ajudá-lo a atualizar a sua aplicação para utilizar a versão 3.

Para uma passagem mais geral do SDK, incluindo exemplos, consulte Como utilizar a Azure Search a partir de uma aplicação .NET.

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

Nota

Se estiver a utilizar a versão 1.0.2 pré-visualização ou mais antiga, deve atualizar para a versão 1.1 primeiro e, em seguida, atualizar para a versão 3. Consulte a atualização para a versão 1.1 da Azure Search .NET SDK para obter instruções.

O seu Azure Serviço de pesquisa exemplo suporta várias versões REST API, incluindo a mais recente. Pode continuar a utilizar uma versão quando já não é a mais recente, mas recomendamos que emigre o seu código para utilizar a versão mais recente. Ao utilizar a API REST, deve especificar a versão API em cada pedido através do parâmetro versão API. Ao utilizar o .NET SDK, a versão do SDK que está a utilizar determina a versão correspondente da API REST. Se estiver a utilizar um SDK mais antigo, pode continuar a executar esse código sem alterações, mesmo que o serviço seja atualizado para suportar uma versão API mais recente.

Novidades na versão 3

A versão 3 do Azure Search .NET SDK tem como alvo a versão mais recente geralmente disponível da Azure Search REST API, especificamente 2016-09-01. Isto permite utilizar muitas novas funcionalidades da Azure Search a partir de uma aplicação .NET, incluindo as seguintes:

Passos para atualizar

Em primeiro lugar, atualize a sua referência NuGet para Microsoft.Azure.Search utilizar a Consola nuGet Gestor de Pacotes ou clicando à direita nas referências do seu projeto e selecionando "Gerir pacotes nuget..." em Visual Studio.

Assim que o NuGet tiver descarregado os novos pacotes e as suas dependências, reconstrua o seu projeto. Dependendo da estrutura do seu código, pode reconstruir com sucesso. Se sim, está pronto para ir!

Se a sua construção falhar, deverá ver um erro de construçã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 este erro de construção. Consulte Breaking changes na versão 3 para obter detalhes sobre o que causa o erro e como corrigi-lo.

Pode ver avisos adicionais de construção relacionados com métodos ou propriedades obsoletos. As advertências incluirão instruções sobre o que usar em vez da função prevada. Por exemplo, se a sua aplicação usar a IndexingParameters.Base64EncodeKeys propriedade, deve receber um aviso que diz "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead."

Uma vez corrigido quaisquer erros de construção, pode escoar alterações na sua aplicação para tirar partido de novas funcionalidades, se assim o desejar. As novas funcionalidades no SDK são detalhadas no que há de novo na versão 3.

Quebra de mudanças na versão 3

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

Índices.Tipo de retorno de obter mente

O Indexes.GetClient método tem um novo tipo de retorno. Anteriormente, voltou SearchIndexClient- mas este foi alterado para ISearchIndexClient a versão 2.0-preview, e essa mudança passa para a versão 3. Isto é para apoiar os clientes que desejem gozar com o método para GetClient os testes unitários, devolvendo uma implementação simulada de ISearchIndexClient.

Exemplo

Se o seu código se parece com isto:

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

Pode alterá-lo para isto para corrigir quaisquer erros de construção:

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

Analisador Nome, DataType e outros já não são implicitamente convertíveis para cordas

Existem muitos tipos no Azure Search .NET SDK que derivam de ExtensibleEnum. Anteriormente, estes tipos eram todos implicitamente convertíveis para escrever string. No entanto, foi descoberto um bug na implementação Object.Equals destas classes, e a correção do bug exigia desativar esta conversão implícita. A conversão string explícita ainda é permitida.

Exemplo

Se o seu código se parece com isto:

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 }), 
};

Pode alterá-lo para isto para corrigir quaisquer erros de construçã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

Pode ver erros de construção relacionados com métodos ou propriedades que foram marcados como obsoletos na versão 2.0-pré-visualização e posteriormente removidos na versão 3. Se encontrar tais erros, eis como resolvê-los:

  • Se estava a usar 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 você estava usando a SearchRequestOptions.RequestId propriedade, use a ClientRequestId propriedade em vez disso.

Funcionalidades de pré-visualização removidas

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

  • ParseJson
  • ParseJsonArrays
  • ParseDelimitedTextFiles

Se a sua aplicação tiver uma forte dependência destas funcionalidades, não poderá fazer upgrade para a versão 3 do Azure Search .NET SDK. Pode continuar a utilizar a versão 2.0-pré-visualização. No entanto, tenha em mente que não recomendamos a utilização de SDKs de pré-visualização em aplicações de produção. As funcionalidades de pré-visualização são apenas para avaliação e podem ser alteradas.

Conclusão

Se precisar de mais detalhes sobre a utilização do Azure Search .NET SDK, consulte o .NET How-to.

Congratulamo-nos com o seu feedback sobre o SDK. Se encontrar problemas, sinta-se à vontade para nos pedir ajuda no Stack Overflow. Se encontrar um bug, pode arquivar um problema no repositório Azure .NET SDK GitHub. Certifique-se de pré-afixar o seu título de emissão com "[Azure Search]".

Obrigado por usar a Azure Search!