Aggiornamento ad Azure Search .NET SDK versione 3Upgrading to the Azure Search .NET SDK version 3

Se si usa la versione 2.0 di anteprima o precedente di Azure Search .NET SDK, questo articolo include informazioni utili per aggiornare l'applicazione per l'uso della versione 3.If you're using version 2.0-preview or older of the Azure Search .NET SDK, this article will help you upgrade your application to use version 3.

Per una procedura dettagliata più generale relativa all'SDK, inclusi gli esempi, vedere Come usare Ricerca di Azure da un'applicazione .NET.For a more general walkthrough of the SDK including examples, see How to use Azure Search from a .NET Application.

La versione 3 di Azure Search .NET SDK contiene alcune modifiche rispetto alle versioni precedenti.Version 3 of the Azure Search .NET SDK contains some changes from earlier versions. ma per lo più secondarie, quindi il codice potrà essere modificato facilmente.These are mostly minor, so changing your code should require only minimal effort. Per le istruzioni su come modificare il codice per usare la nuova versione dell'SDK, vedere Passaggi per eseguire l'aggiornamento .See Steps to upgrade for instructions on how to change your code to use the new SDK version.

Nota

Se si usa la versione 1.0.2-preview o precedente, è consigliabile eseguire prima l'aggiornamento alla versione 1.1 e quindi l'aggiornamento alla versione 3.If you're using version 1.0.2-preview or older, you should upgrade to version 1.1 first, and then upgrade to version 3. Per informazioni, vedere Aggiornamento a .NET SDK Ricerca di Azure versione 1.1.See Upgrading to the Azure Search .NET SDK version 1.1 for instructions.

L'istanza del servizio Ricerca di Azure supporta diverse versioni di API REST, inclusa quella più recente.Your Azure Search service instance supports several REST API versions, including the latest one. È possibile continuare a usare una versione anche se non è la più recente, ma si consiglia di migrare il codice per usare la versione più recente.You can continue to use a version when it is no longer the latest one, but we recommend that you migrate your code to use the newest version. Quando si usa l'API REST, è necessario specificare la versione dell'API in tutte le richieste tramite il parametro api-version.When using the REST API, you must specify the API version in every request via the api-version parameter. Quando si usa .NET SDK, la versione del componente SDK in uso determina la versione corrispondente dell'API REST.When using the .NET SDK, the version of the SDK you're using determines the corresponding version of the REST API. Se si usa una versione del componente SDK precedente, è possibile continuare a eseguire il codice senza apportare modifiche, anche se il servizio viene aggiornato per supportare una versione API più recente.If you are using an older SDK, you can continue to run that code with no changes even if the service is upgraded to support a newer API version.

Novità della versione 3What's new in version 3

La versione 3 di Azure Search .NET SDK ha come destinazione la versione più recente disponibile a livello generale dell'API REST di Ricerca di Azure, in particolare la versione 2016-09-01.Version 3 of the Azure Search .NET SDK targets the latest generally available version of the Azure Search REST API, specifically 2016-09-01. Questo rende possibile usare molte nuove funzionalità di Ricerca di Azure da un'applicazione .NET, incluse le seguenti:This makes it possible to use many new features of Azure Search from a .NET application, including the following:

  • Analizzatori personalizzatiCustom analyzers
  • Supporto per gli indicizzatori di Archiviazione BLOB di Azure e Archiviazione tabelle di AzureAzure Blob Storage and Azure Table Storage indexer support
  • Personalizzazione dell'indicizzatore tramite mapping dei campiIndexer customization via field mappings
  • Supporto di eTag per consentire l'aggiornamento simultaneo sicuro di definizioni di indice, indicizzatori e origini datiETags support to enable safe concurrent updating of index definitions, indexers, and data sources
  • Supporto per la creazione di definizioni dei campi di indice in modo dichiarativo, decorando la classe modello e usando la nuova classe FieldBuilder.Support for building index field definitions declaratively by decorating your model class and using the new FieldBuilder class.
  • Supporto per .NET Core e .NET Portable Profile 111Support for .NET Core and .NET Portable Profile 111

Passaggi per eseguire l'aggiornamentoSteps to upgrade

Per prima cosa aggiornare il riferimento a NuGet per Microsoft.Azure.Search usando NuGet Package Manager Console o facendo clic con il pulsante destro del mouse sui riferimenti di progetto e scegliendo "Gestisci pacchetti NuGet" in Visual Studio.First, update your NuGet reference for Microsoft.Azure.Search using either the NuGet Package Manager Console or by right-clicking on your project references and selecting "Manage NuGet Packages..." in Visual Studio.

Una volta che NuGet ha scaricato i nuovi pacchetti e le relative dipendenze, ricompilare il progetto.Once NuGet has downloaded the new packages and their dependencies, rebuild your project. A seconda della struttura del codice, la ricompilazione potrebbe essere eseguita correttamente.Depending on how your code is structured, it may rebuild successfully. In questo caso è possibile procedere.If so, you're ready to go!

Se la compilazione non riesce, viene visualizzato un errore di compilazione simile al seguente:If your build fails, you should see a build error like the following:

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

Il passaggio successivo consiste nel correggere l'errore di compilazione.The next step is to fix this build error. Vedere Modifiche di rilievo della versione 3 per informazioni dettagliate sulle cause dell'errore e sulla risoluzione.See Breaking changes in version 3 for details on what causes the error and how to fix it.

È possibile che vengano visualizzati avvisi di compilazione aggiuntivi correlati a proprietà o metodi obsoleti.You may see additional build warnings related to obsolete methods or properties. Gli avvisi indicheranno istruzioni sulle operazioni da eseguire al posto della funzionalità deprecata.The warnings will include instructions on what to use instead of the deprecated feature. Ad esempio, se l'applicazione usa la proprietà IndexingParameters.Base64EncodeKeys, dovrebbe essere visualizzato l'avviso "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead."For example, if your application uses the IndexingParameters.Base64EncodeKeys property, you should get a warning that says "This property is obsolete. Please create a field mapping using 'FieldMapping.Base64Encode' instead."

Dopo avere corretto gli errori di compilazione, è possibile apportare modifiche all'applicazione per sfruttare la nuova funzionalità, se si vuole.Once you've fixed any build errors, you can make changes to your application to take advantage of new functionality if you wish. Le nuove funzionalità nell'SDK sono descritte in dettaglio in Novità della versione 3.New features in the SDK are detailed in What's new in version 3.

Modifiche di rilievo nella versione 3Breaking changes in version 3

La versione 3 include poche modifiche di rilievo che potrebbero richiedere modifiche al codice oltre alla ricompilazione dell'applicazione.There a small number of breaking changes in version 3 that may require code changes in addition to rebuilding your application.

Tipo restituito Indexes.GetClientIndexes.GetClient return type

Il metodo Indexes.GetClient dispone di un nuovo tipo restituito.The Indexes.GetClient method has a new return type. In precedenza, veniva restituito SearchIndexClient, ma questo valore è stato modificato in ISearchIndexClient nella versione 2.0-preview e questa modifica è ancora presente nella versione 3.Previously, it returned SearchIndexClient, but this was changed to ISearchIndexClient in version 2.0-preview, and that change carries over to version 3. Serve a supportare i clienti che vogliono simulare il metodo GetClient per i test di unità tramite la restituzione di un'implementazione fittizia di ISearchIndexClient.This is to support customers that wish to mock the GetClient method for unit tests by returning a mock implementation of ISearchIndexClient.

EsempioExample

Se il codice è simile a questo:If your code looks like this:

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

È possibile sostituirlo con questo per correggere gli errori di compilazione:You can change it to this to fix any build errors:

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

AnalyzerName, DataType e altri tipi non possono più essere convertiti in modo implicito in stringheAnalyzerName, DataType, and others are no longer implicitly convertible to strings

Esistono molti tipi in Azure Search .NET SDK che derivano da ExtensibleEnum.There are many types in the Azure Search .NET SDK that derive from ExtensibleEnum. In precedenza, questi tipi erano tutti convertibili in modo implicito nel tipo string.Previously these types were all implicitly convertible to type string. Tuttavia, è stato rilevato un bug nell'implementazione di Object.Equals per queste classi e per correggere il bug è stato necessario disabilitare la conversione implicita.However, a bug was discovered in the Object.Equals implementation for these classes, and fixing the bug required disabling this implicit conversion. La conversione esplicita in string è ancora consentita.Explicit conversion to string is still allowed.

EsempioExample

Se il codice è simile a questo:If your code looks like this:

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

È possibile sostituirlo con questo per correggere gli errori di compilazione:You can change it to this to fix any build errors:

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

Rimuovere i membri obsoletiRemoved obsolete members

È possibile che vengano visualizzati errori di compilazione correlati a metodi o proprietà contrassegnati come obsoleti nella versione 2.0-preview e successivamente rimossi nella versione 3.You may see build errors related to methods or properties that were marked as obsolete in version 2.0-preview and subsequently removed in version 3. Se si verificano tali errori, ecco come risolverli:If you encounter such errors, here is how to resolve them:

  • Se l'errore riguarda il costruttore ScoringParameter(string name, string value), sostituirlo con ScoringParameter(string name, IEnumerable<string> values)If you were using this constructor: ScoringParameter(string name, string value), use this one instead: ScoringParameter(string name, IEnumerable<string> values)
  • Se l'errore riguarda la proprietà ScoringParameter.Value, sostituirla con la proprietà ScoringParameter.Values o il metodo ToString.If you were using the ScoringParameter.Value property, use the ScoringParameter.Values property or the ToString method instead.
  • Se l'errore riguarda la proprietà SearchRequestOptions.RequestId, sostituirla con la proprietà ClientRequestId.If you were using the SearchRequestOptions.RequestId property, use the ClientRequestId property instead.

Funzionalità di anteprima rimosseRemoved preview features

Se esegue l'aggiornamento dalla versione 2.0-preview alla versione 3, tenere presente che è stato rimosso il supporto dell'analisi JSON e CSV per gli indicizzatori BLOB, perché queste funzionalità sono ancora in anteprima.If you are upgrading from version 2.0-preview to version 3, be aware that JSON and CSV parsing support for Blob Indexers has been removed since these features are still in preview. In particolare, sono stati rimossi i metodi seguenti della classe IndexingParametersExtensions:Specifically, the following methods of the IndexingParametersExtensions class have been removed:

  • ParseJson
  • ParseJsonArrays
  • ParseDelimitedTextFiles

Se l'applicazione dipende in modo sostanziale da queste funzionalità, non sarà possibile completare l'aggiornamento alla versione 3 di Azure Search .NET SDK.If your application has a hard dependency on these features, you will not be able to upgrade to version 3 of the Azure Search .NET SDK. È possibile continuare a usare la versione 2.0-preview.You can continue to use version 2.0-preview. Tenere presente, tuttavia, che non è consigliabile usare SDK in anteprima nelle applicazioni di produzione.However, please keep in mind that we do not recommend using preview SDKs in production applications. Le funzionalità di anteprima sono destinate esclusivamente alla valutazione e sono soggette a modifiche.Preview features are for evaluation only and may change.

ConclusioniConclusion

Per altri dettagli sull'uso di .NET SDK Ricerca di Azure, vedere le Procedure .NET.If you need more details on using the Azure Search .NET SDK, see the .NET How-to.

I commenti degli utenti sull'SDK saranno molto apprezzati.We welcome your feedback on the SDK. In caso di problemi, è possibile richiedere assistenza nel forum MSDN su Ricerca di Azure.If you encounter problems, feel free to ask us for help on the Azure Search MSDN forum. Se si trova un bug, è possibile registrare il problema nel repository di GitHub su Azure .NET SDK.If you find a bug, you can file an issue in the Azure .NET SDK GitHub repository. Verificare di avere anteposto al titolo del problema il prefisso "[Ricerca di Azure]".Make sure to prefix your issue title with "[Azure Search]".

Grazie per avere usato Ricerca di Azure.Thank you for using Azure Search!