Partilhar via

Upgrade para Azure Search .NET SDK versão 5

  • Artigo

Se estiver a utilizar a versão 4.0 ou mais antiga do .NET SDK, este artigo irá ajudá-lo a atualizar a sua aplicação para utilizar a versão 5.

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 5 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 2.0 pré-visualização ou mais antiga, deve atualizar para a versão 3 primeiro e, em seguida, atualizar para a versão 5. Consulte a atualização para a versão 3 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 5

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

  • Sinónimos.
  • Pode agora aceder programáticamente aos avisos no histórico de execução do indexante (ver a Warning propriedade da IndexerExecutionResultreferência .NET para obter mais detalhes).
  • Suporte para .NET Core 2.
  • A nova estrutura do pacote suporta usando apenas as partes do SDK de que necessita (ver Alterações de Rutura na versão 5 para mais detalhes).

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:

The name 'SuggesterSearchMode' does not exist in the current context

O próximo passo é corrigir este erro de construção. Consulte Alterações de Breaking na versão 5 para obter mais detalhes sobre o que causa o erro e como corrigi-lo.

Tenha em atenção que, devido a alterações na embalagem do Azure Search .NET SDK, tem de reconstruir a sua aplicação para utilizar a versão 5. Estas alterações são detalhadas em Breaking changes na versão 5.

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 utilizar o IndexingParametersExtensions.DoNotFailOnUnsupportedContentType método, deve receber um aviso que diz "Este comportamento está agora ativado por padrão, pelo que chamar este método já não é necessário."

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

Quebrando mudanças na versão 5

Nova estrutura de pacotes

A mudança de rutura mais substancial na versão 5 é que a montagem e o Microsoft.Azure.Search seu conteúdo foram divididos em quatro conjuntos separados que agora são distribuídos como quatro pacotes NuGet separados:

  • Microsoft.Azure.Search: Este é um meta-pacote que inclui todos os outros pacotes de Pesquisa Azure como dependências. Se estiver a atualizar a partir de uma versão anterior do SDK, simplesmente atualizar este pacote e re-construir deve ser suficiente para começar a usar a nova versão.
  • Microsoft.Azure.Search.Data: Utilize este pacote se estiver a desenvolver uma aplicação .NET utilizando a Azure Search, e só precisa de consultar ou atualizar documentos nos seus índices. Se também precisar de criar ou atualizar índices, mapas de sinónimo ou outros recursos de nível de serviço, utilize o Microsoft.Azure.Search pacote em vez disso.
  • Microsoft.Azure.Search.Service: Utilize este pacote se estiver a desenvolver automatização em .NET para gerir índices de pesquisa de Azure, mapas de sinónimos, indexadores, fontes de dados ou outros recursos de nível de serviço. Se necessitar apenas de consultar ou atualizar documentos nos seus índices, utilize a Microsoft.Azure.Search.Data embalagem em vez disso. Se precisar de toda a funcionalidade da Azure Search, utilize a Microsoft.Azure.Search embalagem.
  • Microsoft.Azure.Search.Common: Tipos comuns necessários pelas bibliotecas Azure Search .NET. Não deverá utilizar este pacote diretamente na sua aplicação; Destina-se apenas a ser usada como dependência.

Esta mudança está tecnicamente a quebrar uma vez que muitos tipos foram movidos entre conjuntos. É por isso que a reconstrução da sua aplicação é necessária para atualizar para a versão 5 do SDK.

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

Alteração para Sugestivos

O Suggester construtor já não tem um enum parâmetro para SuggesterSearchMode. Este enum só tinha um valor, e foi, portanto, redundante. Se vir erros de construção como resultado disto, basta remover referências ao SuggesterSearchMode parâmetro.

Membros obsoletos removidos

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

  • Se estava a usar o IndexingParametersExtensions.IndexStorageMetadataOnly método, use SetBlobExtractionMode(BlobExtractionMode.StorageMetadata) em vez disso.
  • Se estava a usar o IndexingParametersExtensions.SkipContent método, use SetBlobExtractionMode(BlobExtractionMode.AllMetadata) em vez disso.

Funcionalidades de pré-visualização removidas

Se estiver a atualizar da versão 4.0 para a versão 5, esteja ciente de que o suporte de análise de matriz 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:

  • ParseJsonArrays
  • ParseDelimitedTextFiles

Se a sua aplicação tiver uma forte dependência destas funcionalidades, não poderá fazer upgrade para a versão 5 do Azure Search .NET SDK. Pode continuar a utilizar a versão 4.0 de 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!