Compartir a través de

Actualización a la versión 3 del SDK de .NET para Azure Search

  • Artículo

Si usa la versión preliminar 2.0 o posterior del SDK de .NET para Azure Search, este artículo le ayudará a actualizar la aplicación para que use la versión 3.

Para obtener un tutorial más general del SDK que incluya ejemplos, vea Cómo usar Azure Search desde una aplicación .NET.

La versión 3 del SDK de .NET para Azure Search contiene algunos cambios de versiones anteriores. La mayoría son de menor importancia, por lo que cambiar el código solo precisará del mínimo esfuerzo. Vea Pasos para actualizar , a fin de obtener instrucciones sobre cómo cambiar el código para usar la nueva versión del SDK.

Nota

Si usa la versión 1.0.2-preview o anterior, debe actualizar primero a la versión 1.1 y luego a la versión 3. Consulte Actualización a la versión 1.1 del SDK de .NET para Azure Search para instrucciones.

La instancia del servicio Azure Search es compatible con varias versiones de API de REST, incluida la más reciente. Puede seguir usando una versión aunque no sea la más reciente, pero es recomendable que migre el código para usar la versión más actualizada. Cuando se usa la API de REST, debe especificar la versión de API en cada solicitud realizada a través del parámetro api-version. Al usar el SDK de .NET, la versión del SDK que usa determina la versión correspondiente de la API de REST. Si usa un SDK anterior, puede seguir ejecutando ese código sin realizar ningún cambio, incluso si el servicio se ha actualizado para admitir una versión más reciente de la API.

Novedades de la versión 3

La versión 3 del SDK de .NET para Azure Search tiene como destino la versión más reciente con disponibilidad general de la API de REST de Azure Search, en concreto la del 01-09-2016. Esto hace posible el uso de muchas características de Azure Search desde una aplicación. NET, incluidas las siguientes:

  • Analizadores personalizados
  • Compatibilidad del indexador de Azure Blob Storage y Azure Table Storage
  • Personalización de indizador mediante asignaciones de campos
  • Compatibilidad con ETags para permitir actualizaciones seguras simultáneas de definiciones de índice, indizadores y orígenes de datos
  • Compatibilidad con la generación de definiciones de campos de índice de forma declarativa mediante la decoración de la clase model y el uso de la nueva clase FieldBuilder.
  • Compatibilidad con .NET Core y .NET Portable Profile 111

Pasos para actualizar

En primer lugar, actualice la referencia de NuGet para Microsoft.Azure.Search mediante la Consola del Administrador de paquetes NuGet, o bien haga clic con el botón derecho en las referencias del proyecto y seleccione "Administrar paquetes NuGet" en Visual Studio.

Una vez que NuGet ha descargado los nuevos paquetes y sus dependencias, recompile el proyecto. Dependiendo de cómo se estructura el código, se podrá volver a compilar correctamente. Si lo consigue, ya estará listo para empezar.

Si se produce un error en la compilación, verá un mensaje similar al siguiente:

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?)

El paso siguiente consiste en corregir los errores de compilación. Consulte Cambios importantes en la versión 3 para más información sobre las causas del error y cómo corregirlo.

Puede ver las advertencias de compilación adicionales relacionadas con propiedades o métodos obsoletos. Las advertencias incluyen instrucciones sobre qué utilizar en lugar de la característica en desuso. Por ejemplo, si la aplicación utiliza la propiedad IndexingParameters.Base64EncodeKeys, recibirá una advertencia que indica lo siguiente: "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead."

Una vez que haya solucionado los errores de compilación, puede realizar cambios a la aplicación para aprovechar las ventajas de la nueva funcionalidad, si lo desea. Las nuevas características en el SDK se detallan en Novedades de la versión 3.

Cambios importantes en la versión 3

Hay solo algunos cambios importantes en la versión 3 que pueden requerir cambios de código además de la recompilación de la aplicación.

Tipo de valor devuelto de Indexes.GetClient

El método Indexes.GetClient tiene un nuevo tipo de valor devuelto. Anteriormente devolvía SearchIndexClient, pero se ha cambiado a ISearchIndexClient en la versión 2.0-preview, y ese cambio se traslada a la versión 3. Sirve para admitir clientes que deseen simular el método GetClient para las pruebas unitarias devolviendo una implementación ficticia de ISearchIndexClient.

Ejemplo

Si el código tiene el siguiente aspecto:

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

Puede cambiarlo por este para corregir cualquier error de compilación:

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

AnalyzerName, DataType y otros ya no se pueden convertir de manera implícita en cadenas

Hay muchos tipos en el SDK de .NET para Azure Search que derivan de ExtensibleEnum. Anteriormente, todos estos tipos eran convertibles de manera implícita en el tipo string. Sin embargo, se detectó un error en la implementación de Object.Equals para estas clases y para corregir el error fue necesario deshabilitar esta conversión implícita. La conversión explícita a string todavía se permite.

Ejemplo

Si el código tiene el siguiente aspecto:

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

Puede cambiarlo por este para corregir cualquier error de compilación:

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

Miembros obsoletos quitados

Es posible que vea errores de compilación relacionados con métodos o propiedades que se marcaron como obsoletos en la versión 2.0-preview y que posteriormente se eliminaron en la versión 3. Si se encuentra con tales errores, aquí le decimos cómo resolverlos:

  • Si usaba este constructor: ScoringParameter(string name, string value), utilice en su lugar este: ScoringParameter(string name, IEnumerable<string> values)
  • Si usaba la propiedad ScoringParameter.Value, utilice en su lugar la propiedad ScoringParameter.Values o el método ToString.
  • Si usaba la propiedad SearchRequestOptions.RequestId, utilice en su lugar la propiedad ClientRequestId.

Características quitadas de la versión preliminar

Si va a actualizar de la versión 2.0-preview a la versión 3, debe saber que se ha eliminado la compatibilidad con el análisis de JSON y CSV en los indexadores de blobs dado que estás características se encuentran aún en versión preliminar. En concreto, se han quitado los siguientes métodos de la clase IndexingParametersExtensions:

  • ParseJson
  • ParseJsonArrays
  • ParseDelimitedTextFiles

Si la aplicación tiene una dependencia fuerte de estas características, no podrá actualizar a la versión 3 del SDK de Azure Search para .NET. Podrá seguir usando la versión 2.0-preview. Sin embargo, tenga en cuenta que no se recomienda usar SDK de versión preliminar en aplicaciones de producción. Las características de versión preliminar son solo para evaluación y pueden cambiar.

Conclusión

Si necesita más detalles sobre el uso del SDK de .NET para Azure Search, consulte la guía de .NET.

Agradecemos sus comentarios sobre el SDK. Si tiene algún problema, no dude en pedirnos ayuda en Stack Overflow. Si encuentra un error, puede enviarlo al repositorio de GitHub del SDK de .NET para Azure. Asegúrese de agregar "[Azure Search]" como prefijo en el título del problema.

Gracias por usar Azure Search.