Eseguire l'aggiornamento a .NET SDK di Ricerca di Azure versione 9

  • Articolo

Se si usa la versione 7.0-preview o versione precedente di Azure Search .NET SDK, questo articolo consente di aggiornare l'applicazione per l'uso della versione 9.

Nota

Se si vuole usare la versione 8.0-preview per valutare le funzionalità non disponibili a livello generale, è anche possibile seguire le istruzioni riportate in questo articolo per eseguire l'aggiornamento a 8.0-preview dalle versioni precedenti.

Per una procedura dettagliata più generale relativa all'SDK, inclusi gli esempi, vedere Come usare Ricerca di Azure da un'applicazione .NET.

La versione 9 di Azure Search .NET SDK contiene molte modifiche rispetto alle versioni precedenti. Alcune di queste sono modifiche di rilievo, ma devono richiedere solo modifiche relativamente secondarie al codice. Per le istruzioni su come modificare il codice per usare la nuova versione dell'SDK, vedere Passaggi per eseguire l'aggiornamento .

Nota

Se si usa la versione 4.0-preview o versione precedente, è necessario eseguire l'aggiornamento alla versione 5 e quindi eseguire l'aggiornamento alla versione 9. Per istruzioni, vedere Aggiornamento a .NET SDK di Ricerca di Azure versione 5 .

L'istanza del servizio Ricerca di Azure supporta diverse versioni di API REST, inclusa quella più recente. È 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. Quando si usa l'API REST, è necessario specificare la versione dell'API in tutte le richieste tramite il parametro api-version. Quando si usa .NET SDK, la versione del componente SDK in uso determina la versione corrispondente dell'API REST. 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.

Novità della versione 9

La versione 9 di Azure Search .NET SDK è destinata alla versione 2019-05-06 dell'API REST di Ricerca di Azure, con le funzionalità seguenti:

  • L'arricchimento dell'intelligenza artificiale è la possibilità di estrarre testo da immagini, BLOB e altre origini dati non strutturate, arricchire il contenuto per renderlo più ricercabile in un indice di Ricerca di Azure.
  • Il supporto per tipi complessi consente di modellare quasi qualsiasi struttura JSON annidata in un indice di Ricerca di Azure.
  • Il completamento automatico offre un'alternativa all'API Suggerisci per implementare il comportamento di ricerca come tipo. Il completamento automatico "termina" la parola o la frase che un utente sta digitando.
  • Modalità di analisi jsonLines, parte dell'indicizzazione BLOB, crea un documento di ricerca per entità JSON separato da una nuova riga.

Nuove funzionalità di anteprima nella versione 8.0-preview

Versione 8.0-preview dell'API di azure Search .NET SDK versione 2017-11-11-Preview. Questa versione include tutte le stesse funzionalità della versione 9, più:

  • Le chiavi di crittografia gestite dal cliente per la crittografia sul lato servizio inattivi sono una nuova funzionalità di anteprima. Oltre alla crittografia predefinita gestita da Microsoft, è possibile applicare un livello aggiuntivo di crittografia in cui si è l'unico proprietario delle chiavi.

Passaggi per eseguire l'aggiornamento

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.

Una volta che NuGet ha scaricato i nuovi pacchetti e le relative dipendenze, ricompilare il progetto. A seconda della struttura del codice, la ricompilazione potrebbe essere eseguita correttamente. In questo caso è possibile procedere.

Se la compilazione ha esito negativo, sarà necessario correggere ogni errore di compilazione. Per informazioni dettagliate su come risolvere ogni potenziale errore di compilazione, vedere Modifiche di rilievo nella versione 9 .

È possibile che vengano visualizzati avvisi di compilazione aggiuntivi correlati a proprietà o metodi obsoleti. Gli avvisi indicheranno istruzioni sulle operazioni da eseguire al posto della funzionalità deprecata. Ad esempio, se l'applicazione usa la DataSourceType.DocumentDb proprietà, dovrebbe essere visualizzato un avviso che indica "Questo membro è deprecato. Usare Invece CosmosDb".

Dopo avere corretto eventuali errori o avvisi di compilazione, è possibile apportare modifiche all'applicazione per sfruttare la nuova funzionalità, se si vuole. Le nuove funzionalità nell'SDK sono dettagliate in Novità della versione 9.

Modifiche di rilievo nella versione 9

Esistono diverse modifiche di rilievo nella versione 9 che possono richiedere modifiche al codice oltre alla ricompilazione dell'applicazione.

Nota

L'elenco delle modifiche riportate di seguito non è esaustivo. Alcune modifiche potrebbero non causare errori di compilazione, ma sono tecnicamente di rilievo perché interrompono la compatibilità binaria con assembly che dipendono dalle versioni precedenti degli assembly .NET SDK di Ricerca di Azure. Tali modifiche non sono elencate di seguito. Ricompilare l'applicazione durante l'aggiornamento alla versione 9 per evitare eventuali problemi di compatibilità binaria.

Proprietà non modificabili

Le proprietà pubbliche di diverse classi di modello sono ora non modificabili. Se è necessario creare istanze personalizzate di queste classi per il test, è possibile usare i nuovi costruttori con parametri:

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

Modifiche al campo

La Field classe è stata modificata ora che può rappresentare anche campi complessi.

Le proprietà seguenti bool sono ora nullable:

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

Ciò è dovuto al fatto che queste proprietà devono ora essere null nel caso di campi complessi. Se si dispone di codice che legge queste proprietà, deve essere preparato per gestire null. Si noti che tutte le altre proprietà di Field sono sempre state e continuano a essere nullable e alcune di queste saranno null anche nel caso di campi complessi , in particolare quanto segue:

  • Analyzer
  • SearchAnalyzer
  • IndexAnalyzer
  • SynonymMaps

Il costruttore senza parametri di Field è stato reso internal. Da ora in poi, ogni Field tipo di dati e nome esplicito al momento della costruzione.

Tipi di batch e risultati semplificati

Nella versione 7.0-preview e versioni precedenti, le varie classi che incapsulano gruppi di documenti sono state strutturate in gerarchie di classi parallele:

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

I tipi derivati senza un parametro di tipo generico erano destinati a essere usati negli scenari "tipizzato dinamicamente" e presupponevano l'utilizzo del Document tipo.

A partire dalla versione 8.0-preview, sono state rimosse tutte le classi di base e le classi derivate non generiche. Per scenari tipizzato in modo dinamico, è possibile usare IndexBatch<Document>, DocumentSearchResult<Document>e così via.

Removed ExtensibleEnum

La classe di base ExtensibleEnum è stata rimossa. Tutte le classi derivate da esso sono ora struct, ad esempio AnalyzerName, DataTypee DataSourceType ad esempio. I loro Create metodi sono stati rimossi anche. È sufficiente rimuovere le chiamate a Create poiché questi tipi sono implicitamente convertibili da stringhe. In caso di errori del compilatore, è possibile richiamare in modo esplicito l'operatore di conversione tramite cast per tipi disambiguati. Ad esempio, è possibile modificare il codice simile al seguente:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", AnalyzerName.Create("my_email_analyzer")) { IsSearchable = true }
    },
    ...
}

con questo:

var index = new Index()
{
    Fields = new[]
    {
        new Field("id", DataType.String) { IsKey = true },
        new Field("message", (AnalyzerName)"my_email_analyzer") { IsSearchable = true }
    },
    ...
}

Le proprietà che contengono valori facoltativi di questi tipi sono ora tipizzati in modo esplicito come nullable in modo da continuare a essere facoltativi.

Rimosso FacetResults e HitHighlights

Le FacetResults classi e HitHighlights sono state rimosse. I risultati del facet sono ora digitati come IDictionary<string, IList<FacetResult>> e evidenziazioni di hit come IDictionary<string, IList<string>>. Un modo rapido per risolvere gli errori di compilazione introdotti da questa modifica consiste nell'aggiungere using alias nella parte superiore di ogni file che usa i tipi rimossi. Ad esempio:

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

Passare a SynonymMap

Il costruttore SynonymMap non ha più un parametro enum per SynonymMapFormat. Tale enum aveva un solo valore ed era quindi ridondante. Se in conseguenza di ciò vengono visualizzati errori di compilazione, è sufficiente rimuovere i riferimenti al parametro SynonymMapFormat.

Modifiche alla classe di modello varie

La AutocompleteMode proprietà di AutocompleteParameters non è più nullable. Se si dispone di codice che assegna questa proprietà a null, è sufficiente rimuoverla e la proprietà verrà inizializzata automaticamente al valore predefinito.

L'ordine dei parametri del IndexAction costruttore è stato modificato ora che questo costruttore viene generato automaticamente. Anziché usare il costruttore, è consigliabile usare i metodi IndexAction.Uploaddi factory , IndexAction.Mergee così via.

Funzionalità di anteprima rimosse

Se si esegue l'aggiornamento dalla versione 8.0-preview alla versione 9, tenere presente che la crittografia con chiavi gestite dal cliente è stata rimossa poiché questa funzionalità è ancora in anteprima. In particolare, le EncryptionKey proprietà di Index e SynonymMap sono state rimosse.

Se l'applicazione ha una dipendenza difficile da questa funzionalità, non sarà possibile eseguire l'aggiornamento alla versione 9 di Azure Search .NET SDK. È possibile continuare a usare la versione 8.0-preview. Tenere presente, tuttavia, che non è consigliabile usare SDK in anteprima nelle applicazioni di produzione. Le funzionalità di anteprima sono destinate esclusivamente alla valutazione e sono soggette a modifiche.

Nota

Se sono stati creati indici crittografati o mappe sinonimi usando la versione 8.0-preview dell'SDK, sarà comunque possibile usarli e modificarli usando la versione 9 dell'SDK senza influire negativamente sullo stato di crittografia. La versione 9 dell'SDK non invierà la encryptionKey proprietà all'API REST e, di conseguenza, l'API REST non cambierà lo stato di crittografia della risorsa.

Modifica del comportamento nel recupero dei dati

Se si usano le API "tipizzate dinamicamente" Search, o Get che restituiscono istanze di tipo Document, Suggesttenere presente che ora deserializzare le matrici JSON vuote invece object[] di string[].

Conclusioni

Per altri dettagli sull'uso di .NET SDK Ricerca di Azure, vedere le Procedure .NET.

I commenti degli utenti sull'SDK saranno molto apprezzati. Se si verificano problemi, chiedere assistenza su Stack Overflow. Se si trova un bug, è possibile registrare il problema nel repository di GitHub su Azure .NET SDK. Verificare di avere anteposto al titolo del problema il prefisso "[Ricerca di Azure]".

Grazie per avere usato Ricerca di Azure.