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 Appendice: Passaggi per l'aggiornamento alla versione 1.1 .See Appendix: Steps to upgrade to 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.

ConclusioneConclusion

Per altri dettagli sull'uso di Azure Search .NET SDK, vedere gli articoli aggiornati di recente contenenti le procedure.If you need more details on using the Azure Search .NET SDK, see our recently updated 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 "Search SDK: ".Make sure to prefix your issue title with "Search SDK: ".

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

Appendice: Passaggi per l'aggiornamento alla versione 1.1Appendix: Steps to upgrade to version 1.1

Nota

Questa sezione si applica solo agli utenti di Azure Search .NET SDK versione 1.0.2-preview e precedenti.This section applies only to users of the Azure Search .NET SDK version 1.0.2-preview and older.

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.

Se in precedenza si usava la versione 1.0.0 di anteprima, la versione 1.0.1 di anteprima o la versione 1.0.2 di anteprima, la compilazione dovrebbe avere esito positivo e tutto dovrebbe essere pronto per iniziare.If you were previously using version 1.0.0-preview, 1.0.1-preview, or 1.0.2-preview, the build should succeed and you're ready to go!

Se in precedenza si usava versione 0.13.0 di anteprima o una versione precedente, la compilazione dovrebbe generare errori simili ai seguenti:If you were previously using version 0.13.0-preview or older, you should see build errors like the following:

Program.cs(137,56,137,62): error CS0117: 'Microsoft.Azure.Search.Models.IndexBatch' does not contain a definition for 'Create'
Program.cs(137,99,137,105): error CS0117: 'Microsoft.Azure.Search.Models.IndexAction' does not contain a definition for 'Create'
Program.cs(146,41,146,54): error CS1061: 'Microsoft.Azure.Search.IndexBatchException' does not contain a definition for 'IndexResponse' and no extension method 'IndexResponse' accepting a first argument of type 'Microsoft.Azure.Search.IndexBatchException' could be found (are you missing a using directive or an assembly reference?)
Program.cs(163,13,163,42): error CS0246: The type or namespace name 'DocumentSearchResponse' could not be found (are you missing a using directive or an assembly reference?)

Il passaggio successivo consiste nel correggere gli errori di compilazione uno alla volta.The next step is to fix the build errors one by one. La maggior parte richiederà di modificare alcuni nomi di classe e di metodo rinominati nell'SDK.Most will require changing some class and method names that have been renamed in the SDK. Elenco di modifiche di rilievo nella versione 1.1 contiene l'elenco delle modifiche dei nomi.List of breaking changes in version 1.1 contains a list of these name changes.

Se si usano classi personalizzate per modellare i documenti e tali classi hanno proprietà di tipi primitivi non nullable, ad esempio, int o bool in C#, nella versione 1.1 dell'SDK è presente una correzione di bug che è opportuno conoscere.If you're using custom classes to model your documents, and those classes have properties of non-nullable primitive types (for example, int or bool in C#), there is a bug fix in the 1.1 version of the SDK of which you should be aware. Per altri dettagli, vedere Correzioni di bug nella versione 1.1 .See Bug fixes in version 1.1 for more details.

Infine, dopo avere corretto gli errori di compilazione, è possibile apportare modifiche all'applicazione per sfruttare la nuova funzionalità, se si vuole.Finally, once you've fixed any build errors, you can make changes to your application to take advantage of new functionality if you wish.

Elenco di modifiche di rilievo nella versione 1.1List of breaking changes in version 1.1

L'ordinamento dell'elenco seguente segue la probabilità che la modifica abbia effetto sul codice dell'applicazione.The following list is ordered by the likelihood that the change will affect your application code.

Modifiche a IndexBatch e IndexActionIndexBatch and IndexAction changes

IndexBatch.Create è stato rinominato IndexBatch.New e non include più un argomento params.IndexBatch.Create has been renamed to IndexBatch.New and no longer has a params argument. È possibile usare IndexBatch.New per i batch che combinano tipi diversi di azioni (unioni, eliminazioni e così via).You can use IndexBatch.New for batches that mix different types of actions (merges, deletes, etc.). Sono anche presenti nuovi metodi statici per creare batch in cui tutte le azioni sono le stesse: Delete, Merge, MergeOrUpload e Upload.In addition, there are new static methods for creating batches where all the actions are the same: Delete, Merge, MergeOrUpload, and Upload.

IndexAction non include più costruttori pubblici e le proprietà ora sono non modificabili.IndexAction no longer has public constructors and its properties are now immutable. È consigliabile usare i nuovi metodi statici per creare azioni con scopi diversi: Delete, Merge, MergeOrUpload e Upload.You should use the new static methods for creating actions for different purposes: Delete, Merge, MergeOrUpload, and Upload. IndexAction.Create è stato rimosso.IndexAction.Create has been removed. Se si è usato l'overload che accetta un solo documento, verificare di usare invece Upload .If you used the overload that takes only a document, make sure to use Upload instead.

EsempioExample

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

var batch = IndexBatch.Create(documents.Select(doc => IndexAction.Create(doc)));
indexClient.Documents.Index(batch);

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

var batch = IndexBatch.New(documents.Select(doc => IndexAction.Upload(doc)));
indexClient.Documents.Index(batch);

Se si vuole, è possibile semplificarlo ulteriormente in questo modo:If you want, you can further simplify it to this:

var batch = IndexBatch.Upload(documents);
indexClient.Documents.Index(batch);

Modifiche a IndexBatchExceptionIndexBatchException changes

La proprietà IndexBatchException.IndexResponse è stata rinominata IndexingResults e il tipo ora è IList<IndexingResult>.The IndexBatchException.IndexResponse property has been renamed to IndexingResults, and its type is now IList<IndexingResult>.

EsempioExample

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

catch (IndexBatchException e)
{
    Console.WriteLine(
        "Failed to index some of the documents: {0}",
        String.Join(", ", e.IndexResponse.Results.Where(r => !r.Succeeded).Select(r => r.Key)));
}

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

catch (IndexBatchException e)
{
    Console.WriteLine(
        "Failed to index some of the documents: {0}",
        String.Join(", ", e.IndexingResults.Where(r => !r.Succeeded).Select(r => r.Key)));
}

Modifiche ai metodi delle operazioniOperation method changes

Ogni operazione in Azure Search .NET SDK è esposta come set di overload di un metodo per i chiamanti sincroni e asincroni.Each operation in the Azure Search .NET SDK is exposed as a set of method overloads for synchronous and asynchronous callers. Le firme e il factoring di questi overload del metodo sono stati modificati nella versione 1.1.The signatures and factoring of these method overloads has changed in version 1.1.

Ad esempio, l'operazione "Get Index Statistics" nelle versioni precedenti dell'SDK espone queste firme:For example, the "Get Index Statistics" operation in older versions of the SDK exposed these signatures:

In IIndexOperations:In IIndexOperations:

// Asynchronous operation with all parameters
Task<IndexGetStatisticsResponse> GetStatisticsAsync(
    string indexName,
    CancellationToken cancellationToken);

In IndexOperationsExtensions:In IndexOperationsExtensions:

// Asynchronous operation with only required parameters
public static Task<IndexGetStatisticsResponse> GetStatisticsAsync(
    this IIndexOperations operations,
    string indexName);

// Synchronous operation with only required parameters
public static IndexGetStatisticsResponse GetStatistics(
    this IIndexOperations operations,
    string indexName);

Le firme dei metodi per la stessa operazione nella versione 1.1 sono simili a questa:The method signatures for the same operation in version 1.1 look like this:

In IIndexesOperations:In IIndexesOperations:

// Asynchronous operation with lower-level HTTP features exposed
Task<AzureOperationResponse<IndexGetStatisticsResult>> GetStatisticsWithHttpMessagesAsync(
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions),
    Dictionary<string, List<string>> customHeaders = null,
    CancellationToken cancellationToken = default(CancellationToken));

In IndexesOperationsExtensions:In IndexesOperationsExtensions:

// Simplified asynchronous operation
public static Task<IndexGetStatisticsResult> GetStatisticsAsync(
    this IIndexesOperations operations,
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions),
    CancellationToken cancellationToken = default(CancellationToken));

// Simplified synchronous operation
public static IndexGetStatisticsResult GetStatistics(
    this IIndexesOperations operations,
    string indexName,
    SearchRequestOptions searchRequestOptions = default(SearchRequestOptions));

A partire dalla versione 1.1, Azure Search .NET SDK organizza i metodi delle operazioni in modo diverso:Starting with version 1.1, the Azure Search .NET SDK organizes operation methods differently:

  • I parametri facoltativi ora vengono modellati come parametri predefiniti invece che come overload dei metodi aggiuntivi.Optional parameters are now modeled as default parameters rather than additional method overloads. Questo riduce, in alcuni casi anche considerevolmente, il numero di overload dei metodi.This reduces the number of method overloads, sometimes dramatically.
  • I metodi di estensione ora nascondono al chiamante numerosi dettagli estranei di HTTP.The extension methods now hide a lot of the extraneous details of HTTP from the caller. Ad esempio, le versioni precedenti dell'SDK restituiscono un oggetto risposta con un codice di stato HTTP, che spesso non è necessario controllare perché i metodi delle operazioni generano CloudException per tutti i codici di stato indicanti un errore.For example, older versions of the SDK returned a response object with an HTTP status code, which you often didn't need to check because operation methods throw CloudException for any status code that indicates an error. I nuovi metodi di estensione restituiscono solo oggetti modello, evitando il fastidio di doverne annullare il wrapping nel codice.The new extension methods just return model objects, saving you the trouble of having to unwrap them in your code.
  • Al contrario, le interfacce principali ora espongono metodi che offrono un maggiore controllo a livello HTTP, se necessario.Conversely, the core interfaces now expose methods that give you more control at the HTTP level if you need it. Ora è possibile passare le intestazioni HTTP personalizzate da includere nelle richieste e il nuovo tipo restituito AzureOperationResponse<T> consente l'accesso diretto a HttpRequestMessage e a HttpResponseMessage per l'operazione.You can now pass in custom HTTP headers to be included in requests, and the new AzureOperationResponse<T> return type gives you direct access to the HttpRequestMessage and HttpResponseMessage for the operation. AzureOperationResponse è definito nello spazio dei nomi Microsoft.Rest.Azure e sostituisce Hyak.Common.OperationResponse.AzureOperationResponse is defined in the Microsoft.Rest.Azure namespace and replaces Hyak.Common.OperationResponse.

Modifiche a ScoringParametersScoringParameters changes

Una nuova classe denominata ScoringParameter è stata aggiunta alla versione più recente dell'SDK per semplificare la specifica di parametri per i profili di punteggio in una query di ricerca.A new class named ScoringParameter has been added in the latest SDK to make it easier to provide parameters to scoring profiles in a search query. In precedenza la proprietà ScoringProfiles della classe SearchParameters veniva tipizzata come IList<string>. Ora viene tipizzata come IList<ScoringParameter>.Previously the ScoringProfiles property of the SearchParameters class was typed as IList<string>; Now it is typed as IList<ScoringParameter>.

EsempioExample

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

var sp = new SearchParameters();
sp.ScoringProfile = "jobsScoringFeatured";      // Use a scoring profile
sp.ScoringParameters = new[] { "featuredParam-featured", "mapCenterParam-" + lon + "," + lat };

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

var sp = new SearchParameters();
sp.ScoringProfile = "jobsScoringFeatured";      // Use a scoring profile
sp.ScoringParameters =
    new[]
    {
        new ScoringParameter("featuredParam", new[] { "featured" }),
        new ScoringParameter("mapCenterParam", GeographyPoint.Create(lat, lon))
    };

Modifiche alle classi di modelliModel class changes

In seguito alle modifiche apportate alle firme descritte in Modifiche ai metodi delle operazioni, molte classi nello spazio dei nomi Microsoft.Azure.Search.Models sono state rinominate o rimosse.Due to the signature changes described in Operation method changes, many classes in the Microsoft.Azure.Search.Models namespace have been renamed or removed. Ad esempio:For example:

  • IndexDefinitionResponse è stata sostituita da AzureOperationResponse<Index>IndexDefinitionResponse has been replaced by AzureOperationResponse<Index>
  • DocumentSearchResponse è stata rinominata DocumentSearchResultDocumentSearchResponse has been renamed to DocumentSearchResult
  • IndexResult è stata rinominata IndexingResultIndexResult has been renamed to IndexingResult
  • Documents.Count() ora restituisce long con il conteggio dei documenti invece di DocumentCountResponseDocuments.Count() now returns a long with the document count instead of a DocumentCountResponse
  • IndexGetStatisticsResponse è stata rinominata IndexGetStatisticsResultIndexGetStatisticsResponse has been renamed to IndexGetStatisticsResult
  • IndexListResponse è stata rinominata IndexListResultIndexListResponse has been renamed to IndexListResult

Per riepilogare, le classi derivate da OperationResponseche servivano solo a eseguire il wrapping di un oggetto modello sono state rimosse.To summarize, OperationResponse-derived classes that existed only to wrap a model object have been removed. I suffissi delle altre classi sono passati da Response a Result.The remaining classes have had their suffix changed from Response to Result.

EsempioExample

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

IndexerGetStatusResponse statusResponse = null;

try
{
    statusResponse = _searchClient.Indexers.GetStatus(indexer.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Error polling for indexer status: {0}", ex.Message);
    return;
}

IndexerExecutionResult lastResult = statusResponse.ExecutionInfo.LastResult;

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

IndexerExecutionInfo status = null;

try
{
    status = _searchClient.Indexers.GetStatus(indexer.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Error polling for indexer status: {0}", ex.Message);
    return;
}

IndexerExecutionResult lastResult = status.LastResult;
Classi di risposte e IEnumerableResponse classes and IEnumerable

Un'altra modifica che può avere effetto sul codice è che le classi di risposte contenenti raccolte non implementano più IEnumerable<T>.An additional change that may affect your code is that response classes that hold collections no longer implement IEnumerable<T>. Invece è possibile accedere direttamente alla proprietà della raccolta.Instead, you can access the collection property directly. Ad esempio, se il codice è simile a questo:For example, if your code looks like this:

DocumentSearchResponse<Hotel> response = indexClient.Documents.Search<Hotel>(searchText, sp);
foreach (SearchResult<Hotel> result in response)
{
    Console.WriteLine(result.Document);
}

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

DocumentSearchResult<Hotel> response = indexClient.Documents.Search<Hotel>(searchText, sp);
foreach (SearchResult<Hotel> result in response.Results)
{
    Console.WriteLine(result.Document);
}
Caso speciale per le applicazioni WebSpecial case for web applications

Se è presente un'applicazione Web che serializza direttamente DocumentSearchResponse per inviare i risultati della ricerca al browser, sarà necessario modificare il codice o i risultati non verranno serializzati correttamente.If you have a web application that serializes DocumentSearchResponse directly to send search results to the browser, you will need to change your code or the results will not serialize correctly. Ad esempio, se il codice è simile a questo:For example, if your code looks like this:

public ActionResult Search(string q = "")
{
    // If blank search, assume they want to search everything
    if (string.IsNullOrWhiteSpace(q))
        q = "*";

    return new JsonResult
    {
        JsonRequestBehavior = JsonRequestBehavior.AllowGet,
        Data = _featuresSearch.Search(q)
    };
}

È possibile modificarla ottenendo la proprietà .Results della risposta della ricerca per correggere il rendering dei risultati della ricerca:You can change it by getting the .Results property of the search response to fix search result rendering:

public ActionResult Search(string q = "")
{
    // If blank search, assume they want to search everything
    if (string.IsNullOrWhiteSpace(q))
        q = "*";

    return new JsonResult
    {
        JsonRequestBehavior = JsonRequestBehavior.AllowGet,
        Data = _featuresSearch.Search(q).Results
    };
}

Sarà necessario cercare manualmente tali casi nel codice. Il compilatore non genererà avvisi perché JsonResult.Data è di tipo object.You will have to look for such cases in your code yourself; The compiler will not warn you because JsonResult.Data is of type object.

Modifiche a CloudExceptionCloudException changes

La classe CloudException è stata spostata dallo spazio dei nomi Hyak.Common allo spazio dei nomi Microsoft.Rest.Azure.The CloudException class has moved from the Hyak.Common namespace to the Microsoft.Rest.Azure namespace. Inoltre la proprietà Error è stata rinominata Body.Also, its Error property has been renamed to Body.

Modifiche a SearchServiceClient e SearchIndexClientSearchServiceClient and SearchIndexClient changes

Il tipo della proprietà Credentials è passato da SearchCredentials alla relativa classe base, ServiceClientCredentials.The type of the Credentials property has changed from SearchCredentials to its base class, ServiceClientCredentials. Se è necessario accedere a SearchCredentials di un oggetto SearchIndexClient o SearchServiceClient, usare la nuova proprietà SearchCredentials.If you need to access the SearchCredentials of a SearchIndexClient or SearchServiceClient, please use the new SearchCredentials property.

Nelle versioni precedenti dell'SDK SearchServiceClient e SearchIndexClient hanno costruttori che accettano un parametro HttpClient.In older versions of the SDK, SearchServiceClient and SearchIndexClient had constructors that took an HttpClient parameter. Questi sono stati sostituiti con costruttori che accettano HttpClientHandler e una matrice di oggetti DelegatingHandler.These have been replaced with constructors that take an HttpClientHandler and an array of DelegatingHandler objects. In questo modo è più semplice installare gestori personalizzati per pre-elaborare le richieste HTTP, se necessario.This makes it easier to install custom handlers to pre-process HTTP requests if necessary.

Infine sono stati modificati i costruttori che accettano Uri e SearchCredentials.Finally, the constructors that took a Uri and SearchCredentials have changed. Ad esempio, se il codice è simile a questo:For example, if you have code that looks like this:

var client =
    new SearchServiceClient(
        new SearchCredentials("abc123"),
        new Uri("http://myservice.search.windows.net"));

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

var client =
    new SearchServiceClient(
        new Uri("http://myservice.search.windows.net"),
        new SearchCredentials("abc123"));

Si noti anche che il tipo del parametro delle credenziali è diventato ServiceClientCredentials.Also note that the type of the credentials parameter has changed to ServiceClientCredentials. È improbabile che ciò abbia effetto sul codice perché SearchCredentials deriva da ServiceClientCredentials.This is unlikely to affect your code since SearchCredentials is derived from ServiceClientCredentials.

Passaggio di un ID richiestaPassing a request ID

Nelle versioni precedenti dell'SDK è possibile impostare un ID richiesta su SearchServiceClient o su SearchIndexClient per includerlo in ogni richiesta per l'API REST.In older versions of the SDK, you could set a request ID on the SearchServiceClient or SearchIndexClient and it would be included in every request to the REST API. Ciò è utile per la risoluzione dei problemi relativi al servizio di ricerca se è necessario contattare il supporto.This is useful for troubleshooting issues with your search service if you need to contact support. È però più utile impostare un ID richiesta univoco per ogni operazione invece di usare lo stesso ID per tutte le operazioni.However, it is more useful to set a unique request ID for every operation rather than to use the same ID for all operations. Per questo motivo, i metodi SetClientRequestId di SearchServiceClient e SearchIndexClient sono stati rimossi.For this reason, the SetClientRequestId methods of SearchServiceClient and SearchIndexClient have been removed. È invece possibile passare un ID richiesta a ogni metodo di un'operazione tramite il parametro SearchRequestOptions facoltativo.Instead, you can pass a request ID to each operation method via the optional SearchRequestOptions parameter.

Nota

In una delle versioni future dell'SDK verrà aggiunto un nuovo meccanismo per impostare un ID richiesta a livello globale negli oggetti client, con un approccio coerente con quello usato da altri Azure SDK.In a future release of the SDK, we will add a new mechanism for setting a request ID globally on the client objects that is consistent with the approach used by other Azure SDKs.

EsempioExample

Se il codice è simile a questo:If you have code that looks like this:

client.SetClientRequestId(Guid.NewGuid());
...
long count = client.Documents.Count();

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

long count = client.Documents.Count(new SearchRequestOptions(requestId: Guid.NewGuid()));

Modifiche ai nomi delle interfacceInterface name changes

I nomi delle interfacce dei gruppi di operazioni sono stati tutti modificati in modo che fossero coerenti con i corrispondenti nomi di proprietà:The operation group interface names have all changed to be consistent with their corresponding property names:

  • Il tipo di ISearchServiceClient.Indexes è stato rinominato da IIndexOperations a IIndexesOperations.The type of ISearchServiceClient.Indexes has been renamed from IIndexOperations to IIndexesOperations.
  • Il tipo di ISearchServiceClient.Indexers è stato rinominato da IIndexerOperations a IIndexersOperations.The type of ISearchServiceClient.Indexers has been renamed from IIndexerOperations to IIndexersOperations.
  • Il tipo di ISearchServiceClient.DataSources è stato rinominato da IDataSourceOperations a IDataSourcesOperations.The type of ISearchServiceClient.DataSources has been renamed from IDataSourceOperations to IDataSourcesOperations.
  • Il tipo di ISearchIndexClient.Documents è stato rinominato da IDocumentOperations a IDocumentsOperations.The type of ISearchIndexClient.Documents has been renamed from IDocumentOperations to IDocumentsOperations.

Questa modifica potrebbe avere effetto sul codice solo se si creano interfacce fittizie a scopo di test.This change is unlikely to affect your code unless you created mocks of these interfaces for test purposes.

Correzioni di bug nella versione 1.1Bug fixes in version 1.1

Nelle versioni precedenti di Azure Search .NET SDK esiste un bug relativo alla serializzazione delle classi di modelli personalizzate.There was a bug in older versions of the Azure Search .NET SDK relating to serialization of custom model classes. Il bug può verificarsi se si crea una classe di modelli personalizzata con una proprietà di un tipo di valore non nullable.The bug could occur if you created a custom model class with a property of a non-nullable value type.

Passaggi per riprodurre il bugSteps to reproduce

Creare una classe di modelli personalizzata con una proprietà di tipo di valore non nullable.Create a custom model class with a property of non-nullable value type. Ad esempio, aggiungere una proprietà pubblica UnitCount di tipo int invece che int?.For example, add a public UnitCount property of type int instead of int?.

Se si indicizza un documento con il valore predefinito di tale tipo (ad esempio, 0 per int), il campo sarà null in Ricerca di Azure.If you index a document with the default value of that type (for example, 0 for int), the field will be null in Azure Search. Se in seguito si cerca tale documento, la chiamata a Search genererà JsonSerializationException perché non riesce a convertire null in int.If you subsequently search for that document, the Search call will throw JsonSerializationException complaining that it can't convert null to int.

Anche i filtri potrebbero non funzionare normalmente perché nell'indice è stato scritto null invece del valore previsto.Also, filters may not work as expected since null was written to the index instead of the intended value.

Dettagli della correzioneFix details

Questo problema è stato risolto nella versione 1.1 dell'SDK.We have fixed this issue in version 1.1 of the SDK. Se è presente una classe di modelli come questa:Now, if you have a model class like this:

public class Model
{
    public string Key { get; set; }

    public int IntValue { get; set; }
}

e si imposta IntValue su 0, tale valore ora viene serializzato correttamente come 0 durante il transito e archiviato come 0 nell'indice.and you set IntValue to 0, that value is now correctly serialized as 0 on the wire and stored as 0 in the index. Anche il round trip funziona come previsto.Round tripping also works as expected.

Questo approccio presenta un potenziale problema che è opportuno tenere presente: se si usa un tipo di modello con una proprietà che non ammette i valori null, è necessario garantire che nessun documento nell'indice contenga un valore null per il campo corrispondente.There is one potential issue to be aware of with this approach: If you use a model type with a non-nullable property, you have to guarantee that no documents in your index contain a null value for the corresponding field. Né l'SDK né l'API REST per Ricerca di Azure consentiranno di applicare questo valore.Neither the SDK nor the Azure Search REST API will help you to enforce this.

Non è solo un problema ipotetico: si pensi a uno scenario in cui si aggiunge un nuovo campo a un indice esistente di tipo Edm.Int32.This is not just a hypothetical concern: Imagine a scenario where you add a new field to an existing index that is of type Edm.Int32. Dopo l'aggiornamento della definizione dell'indice, tutti i documenti avranno un valore Null per il nuovo campo (perché tutti i tipi sono nullable in Ricerca di Azure).After updating the index definition, all documents will have a null value for that new field (since all types are nullable in Azure Search). Se quindi si usa una classe di modelli con una proprietà int che non ammette i valori Null per tale campo, verrà restituita un'eccezione JsonSerializationException, come questa, quando si cercherà di recuperare i documenti:If you then use a model class with a non-nullable int property for that field, you will get a JsonSerializationException like this when trying to retrieve documents:

Error converting value {null} to type 'System.Int32'. Path 'IntValue'.

Per questo motivo, è ancora consigliabile usare tipi nullable nelle classi di modelli.For this reason, we still recommend that you use nullable types in your model classes as a best practice.

Per altri dettagli sul bug e sulla correzione, vedere questo problema in GitHub.For more details on this bug and the fix, please see this issue on GitHub.