Partilhar via

Upgrade para Azure Search .NET SDK versão 9

  • Artigo

Se estiver a utilizar a versão 7.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 9.

Nota

Se pretender utilizar a versão 8.0-pré-visualização para avaliar funcionalidades que não estão geralmente disponíveis ainda, também pode seguir as instruções deste artigo para atualizar para 8.0-pré-visualização de versões anteriores.

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 9 do Azure Search .NET SDK contém muitas alterações em versões anteriores. Algumas destas alterações estão a quebrar alterações, mas só devem requerer alterações relativamente pequenas no seu código. 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 4.0 pré-visualização ou mais antiga, deve atualizar para a versão 5 primeiro e, em seguida, atualizar para a versão 9. Consulte a atualização para a versão 5 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 9

A versão 9 do Azure Search .NET SDK tem como alvo a versão 2019-05-06 da Azure Search REST API, com as seguintes funcionalidades:

  • O enriquecimento de IA é a capacidade de extrair texto de imagens, bolhas e outras fontes de dados não estruturadas - enriquecendo o conteúdo para torná-lo mais pes pescável num índice de Pesquisa de Azure.
  • O suporte para tipos complexos permite-lhe modelo quase qualquer estrutura JSON aninhada num índice de Pesquisa de Azure.
  • O autocomplete fornece uma alternativa à API sugestiva para implementar comportamentos de pesquisa à sua maneira. "Finisha" automaticamente a palavra ou frase que um utilizador está atualmente a escrever.
  • O modo de análise JsonLines, parte da indexação de blob, cria um documento de pesquisa por entidade JSON que é separado por uma nova linha.

Novas funcionalidades de pré-visualização na versão 8.0-pré-visualização

Versão 8.0-pré-visualização do Azure Search .NET SDK visa a versão API 2017-11-11-Preview. Esta versão inclui todas as mesmas funcionalidades da versão 9, mais:

  • As chaves de encriptação geridas pelo cliente para encriptação do lado do serviço em repouso é uma nova funcionalidade de pré-visualização. Além da encriptação incorporada em repouso gerida pela Microsoft, pode aplicar uma camada adicional de encriptação onde é o único proprietário das chaves.

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, terá de corrigir cada erro de construção. Consulte alterações de Breaking na versão 9 para obter mais detalhes sobre como resolver cada potencial erro de construção.

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 o DataSourceType.DocumentDb imóvel, deve receber um aviso que diz "Este membro está precotado. Use o CosmosDb em vez disso".

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 9.

Quebrando mudanças na versão 9

Existem várias alterações na versão 9 que podem exigir alterações de código para além da reconstrução da sua aplicação.

Nota

A lista de alterações abaixo não é exaustiva. Algumas alterações provavelmente não resultarão em erros de construção, mas estão tecnicamente a quebrar uma vez que quebram a compatibilidade binária com conjuntos que dependem de versões anteriores dos conjuntos Azure Search .NET SDK. Tais alterações não constam da lista abaixo. Por favor, reconstrua a sua aplicação ao atualizar para a versão 9 para evitar quaisquer problemas de compatibilidade binária.

Propriedades imutáveis

As propriedades públicas de várias classes modelo são agora imutáveis. Se precisar de criar instâncias personalizadas destas classes para testes, pode utilizar os novos construtores parametrizados:

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

Alterações no Campo

A Field classe mudou agora que também pode representar campos complexos.

As seguintes bool propriedades são agora anuladas:

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

Isto porque estas propriedades devem agora ser null no caso de campos complexos. Se tiver um código que leia estas propriedades, tem de estar preparado para manusear null. Note que todas as outras propriedades Field sempre foram e continuam a ser anulados, e algumas delas também serão null no caso de campos complexos - especificamente o seguinte:

  • Analyzer
  • SearchAnalyzer
  • IndexAnalyzer
  • SynonymMaps

O construtor sem parâmetros Field foi feito internal. A partir de agora, cada Field um requer um nome explícito e um tipo de dados no momento da construção.

Tipos de lote e resultados simplificados

Na versão 7.0-pré-visualização e anterior, as várias classes que encapsulam grupos de documentos foram estruturadas em hierarquias de classe paralelas:

  • DocumentSearchResult e DocumentSearchResult<T> herdado de DocumentSearchResultBase
  • DocumentSuggestResult e DocumentSuggestResult<T> herdado de DocumentSuggestResultBase
  • IndexAction e IndexAction<T> herdado de IndexActionBase
  • IndexBatch e IndexBatch<T> herdado de IndexBatchBase
  • SearchResult e SearchResult<T> herdado de SearchResultBase
  • SuggestResult e SuggestResult<T> herdado de SuggestResultBase

Os tipos derivados sem um parâmetro de tipo genérico destinavam-se a ser utilizados em cenários "de tipo dinâmico" e assumiam a utilização do Document tipo.

Começando pela versão 8.0-pré-visualização, as classes base e as classes derivadas não genéricas foram todas removidas. Para cenários de tipo dinâmico, pode usar IndexBatch<Document>, DocumentSearchResult<Document>e assim por diante.

ExtensibleEnum removido

A ExtensibleEnum classe base foi removida. Todas as classes que dele derivaram são agora structs, como AnalyzerName, DataTypee DataSourceType por exemplo. Os seus Create métodos também foram removidos. Basta remover chamadas para uma Create vez que estes tipos são implicitamente descapotáveis das cordas. Se isso resultar em erros de compilador, pode invocar explicitamente o operador de conversão através da fundição para tipos de desambiguados. Por exemplo, pode alterar códigos 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 este:

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 detinham valores opcionais deste tipo são agora explicitamente digitadas como nulas, pelo que continuam a ser opcionais.

FacetResults removidos e hitHighlights

As FacetResults aulas foram HitHighlights removidas. Os resultados facetas são agora dactilografados como IDictionary<string, IList<FacetResult>> e atingem os destaques como IDictionary<string, IList<string>>. Uma forma rápida de resolver erros de construção introduzidos por esta alteração é adicionar using pseudónimos no topo de cada ficheiro que utiliza 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>>;

Alteração para SynonymMap

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

Mudanças de classe modelo diversas

A AutocompleteMode propriedade de AutocompleteParameters não é mais anulado. Se tiver um código que atribui a nulleste imóvel, pode simplesmente removê-lo e a propriedade será automaticamente inicializada ao valor predefinido.

A ordem dos parâmetros para o IndexAction construtor mudou agora que este construtor é gerado automaticamente. Em vez de utilizar o construtor, recomendamos a utilização dos métodos IndexAction.Uploadde fábrica, IndexAction.Mergee assim por diante.

Funcionalidades de pré-visualização removidas

Se estiver a atualizar a partir da versão 8.0 pré-visualização para a versão 9, esteja ciente de que a encriptação com as teclas geridas pelo cliente foi removida uma vez que esta funcionalidade ainda se encontra em pré-visualização. Especificamente, as EncryptionKey propriedades de Index e SynonymMap foram removidas.

Se a sua aplicação tiver uma forte dependência desta funcionalidade, não poderá fazer upgrade para a versão 9 do Azure Search .NET SDK. Pode continuar a utilizar a versão 8.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.

Nota

Se criou índices encriptados ou mapas de sinónimo utilizando a versão 8.0-pré-visualização do SDK, ainda poderá utilizá-los e modificar as suas definições utilizando a versão 9 do SDK sem afetar negativamente o seu estado de encriptação. A versão 9 do SDK não enviará a encryptionKey propriedade para a API REST e, consequentemente, a API REST não alterará o estado de encriptação do recurso.

Mudança comportamental na recuperação de dados

Se estiver a utilizar as "dinâmicas dactilografam", SearchSuggestou Get APIs que devolvem instâncias do tipoDocument, saiba que agora deserializam matrizes JSON vazias para object[] em vez de string[].

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!