Upgrade uitvoeren naar Azure Search .NET SDK versie 1.1

Artikel
09/16/2021

Als u versie 1.0.2-preview of ouder van de Azure Search .NET SDK gebruikt, helpt dit artikel u bij het upgraden van uw toepassing om versie 1.1 te gebruiken.

Zie Azure Search gebruiken vanuit een .NET-toepassing voor een algemeen overzicht van de SDK, inclusief voorbeelden.

Notitie

Wanneer u een upgrade uitvoert naar versie 1.1 of als u al een versie tussen 1.1 en 2.0 preview gebruikt, moet u upgraden naar versie 3. Zie Upgraden naar azure Search .NET SDK versie 3 voor instructies.

Werk eerst uw NuGet-verwijzing bij voor Microsoft.Azure.Search het gebruik van de NuGet Pakketbeheer Console of door met de rechtermuisknop op uw projectverwijzingen te klikken en NuGet-pakketten beheren te selecteren... in Visual Studio.

Zodra NuGet de nieuwe pakketten en hun afhankelijkheden heeft gedownload, bouwt u uw project opnieuw.

Als u eerder versie 1.0.0-preview, 1.0.1-preview of 1.0.2-preview gebruikt, moet de build lukken en kunt u aan de slag.

Als u eerder versie 0.13.0 preview of ouder gebruikt, ziet u als volgt buildfouten:

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

De volgende stap is het oplossen van de buildfouten één voor één. Voor de meeste is het wijzigen van een aantal klasse- en methodenamen vereist die zijn gewijzigd in de SDK. Lijst met belangrijke wijzigingen in versie 1.1 bevat een lijst met deze naamwijzigingen.

Als u aangepaste klassen gebruikt om uw documenten te modelleren en deze klassen eigenschappen hebben van niet-nullable primitieve typen (bijvoorbeeld int of bool in C#), is er een foutoplossing in de versie 1.1 van de SDK waarvan u zich bewust moet zijn. Zie Oplossingen voor fouten in versie 1.1 voor meer informatie.

Ten slotte kunt u, zodra u buildfouten hebt opgelost, wijzigingen aanbrengen in uw toepassing om desgewenst te profiteren van nieuwe functionaliteit.

Lijst met belangrijke wijzigingen in versie 1.1

De volgende lijst wordt gerangschikt op basis van de kans dat de wijziging van invloed is op uw toepassingscode.

Wijzigingen in IndexBatch en IndexAction

IndexBatch.Create is gewijzigd in IndexBatch.New en heeft params geen argument meer. U kunt IndexBatch.New gebruiken voor batches die verschillende soorten acties combineren (samenvoegingen, verwijderingen, enzovoort). Daarnaast zijn er nieuwe statische methoden voor het maken van batches waarbij alle acties hetzelfde zijn: Delete, Merge, MergeOrUpload, en Upload.

IndexAction heeft geen openbare constructors meer en de eigenschappen zijn nu onveranderbaar. U moet de nieuwe statische methoden gebruiken voor het maken van acties voor verschillende doeleinden: Delete, Merge, MergeOrUpload, en Upload. IndexAction.Create Verwijderd. Als u de overbelasting hebt gebruikt die alleen een document nodig heeft, moet u in plaats daarvan het document gebruiken Upload .

Voorbeeld

Als uw code er als volgt uitziet:

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

U kunt dit wijzigen om eventuele buildfouten op te lossen:

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

Als u wilt, kunt u dit verder vereenvoudigen:

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

IndexBatchException-wijzigingen

De naam van de IndexBatchException.IndexResponse eigenschap is gewijzigd in IndexingResultsen het type is nu IList<IndexingResult>.

Voorbeeld

Als uw code er als volgt uitziet:

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

U kunt dit wijzigen om eventuele buildfouten op te lossen:

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

Wijzigingen in de bewerkingsmethode

Elke bewerking in de .NET SDK van Azure Search wordt weergegeven als een set overbelastingen van methoden voor synchrone en asynchrone bellers. De handtekeningen en factoring van deze methode overbelasten is gewijzigd in versie 1.1.

De bewerking Indexstatistieken ophalen in oudere versies van de SDK heeft bijvoorbeeld deze handtekeningen weergegeven:

In IIndexOperations:

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

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

De methodehandtekeningen voor dezelfde bewerking in versie 1.1 zien er als volgt uit:

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:

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

Vanaf versie 1.1 organiseert de Azure Search .NET SDK verschillende bewerkingsmethoden:

Optionele parameters worden nu gemodelleerd als standaardparameters in plaats van extra overbelasting van methoden. Dit vermindert het aantal overbelastingen van methoden, soms aanzienlijk.
De extensiemethoden verbergen nu veel van de overbodige details van HTTP van de aanroeper. Oudere versies van de SDK hebben bijvoorbeeld een antwoordobject geretourneerd met een HTTP-statuscode, die u vaak niet hoeft te controleren omdat bewerkingsmethoden worden gegenereerd CloudException voor een statuscode die een fout aangeeft. Met de nieuwe extensiemethoden worden alleen modelobjecten geretourneerd, waardoor u de moeite hebt om ze in uw code uit te pakken.
Omgekeerd bieden de kerninterfaces nu methoden die u meer controle geven op HTTP-niveau als u deze nodig hebt. U kunt nu aangepaste HTTP-headers doorgeven die moeten worden opgenomen in aanvragen en het nieuwe AzureOperationResponse<T> retourtype geeft u directe toegang tot de HttpRequestMessage en HttpResponseMessage voor de bewerking. AzureOperationResponse is gedefinieerd in de Microsoft.Rest.Azure naamruimte en vervangt Hyak.Common.OperationResponse.

Wijzigingen in ScoringParameters

Er is een nieuwe klasse met de naam ScoringParameter toegevoegd in de nieuwste SDK, zodat u gemakkelijker parameters kunt opgeven voor scoreprofielen in een zoekquery. Eerder werd de ScoringProfiles eigenschap van de SearchParameters klasse getypt als IList<string>; Nu is het getypt als IList<ScoringParameter>.

Voorbeeld

Als uw code er als volgt uitziet:

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

U kunt dit wijzigen om eventuele buildfouten op te lossen:

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

Modelklassewijzigingen

Vanwege de handtekeningwijzigingen die worden beschreven in bewerkingsmethodewijzigingen, zijn veel klassen in de Microsoft.Azure.Search.Models naamruimte gewijzigd of verwijderd. Bijvoorbeeld:

IndexDefinitionResponse is vervangen door AzureOperationResponse<Index>
De naam van DocumentSearchResponse is gewijzigd in DocumentSearchResult
De naam van IndexResult is gewijzigd in IndexingResult
Documents.Count() retourneert nu een long met het aantal documenten in plaats van een DocumentCountResponse
De naam van IndexGetStatisticsResponse is gewijzigd in IndexGetStatisticsResult
De naam van IndexListResponse is gewijzigd in IndexListResult

Om samen te vatten, OperationResponsezijn -afgeleide klassen die alleen bestonden om een modelobject te verpakken, verwijderd. De resterende klassen hebben hun achtervoegsel gewijzigd van Response .Result

Voorbeeld

Als uw code er als volgt uitziet:

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;

U kunt dit wijzigen om eventuele buildfouten op te lossen:

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;

Antwoordklassen en IEnumerable

Een extra wijziging die van invloed kan zijn op uw code is dat antwoordklassen die verzamelingen bevatten, niet meer worden geïmplementeerd IEnumerable<T>. In plaats daarvan hebt u rechtstreeks toegang tot de verzamelingseigenschap. Als uw code er bijvoorbeeld als volgt uitziet:

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

U kunt dit wijzigen om eventuele buildfouten op te lossen:

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

Speciaal geval voor webtoepassingen

Als u een webtoepassing hebt die rechtstreeks wordt geserialiseerd DocumentSearchResponse om zoekresultaten naar de browser te verzenden, moet u uw code wijzigen of worden de resultaten niet correct geserialiseerd. Als uw code er bijvoorbeeld als volgt uitziet:

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

U kunt dit wijzigen door de .Results eigenschap van het zoekantwoord op te halen om de weergave van zoekresultaten op te lossen:

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

U moet zelf zoeken naar dergelijke gevallen in uw code; De compiler waarschuwt u niet omdat JsonResult.Data het type objectis.

Wijzigingen in CloudException

De CloudException klasse is verplaatst van de Hyak.Common naamruimte naar de Microsoft.Rest.Azure naamruimte. Ook is de naam van de Error eigenschap gewijzigd in Body.

Wijzigingen in SearchServiceClient en SearchIndexClient

Het type eigenschap Credentials is gewijzigd van SearchCredentials de basisklasse, ServiceClientCredentials. Als u toegang nodig hebt tot een SearchCredentialsSearchIndexClient of SearchServiceClient, gebruikt u de nieuwe SearchCredentials eigenschap.

In oudere versies van de SDK SearchServiceClient en SearchIndexClient had constructors die een HttpClient parameter namen. Deze zijn vervangen door constructors die een HttpClientHandler en een matrix van DelegatingHandler objecten gebruiken. Hierdoor kunt u gemakkelijker aangepaste handlers installeren om HTTP-aanvragen vooraf te verwerken, indien nodig.

Ten slotte zijn de constructors die een Uri en SearchCredentials ander hebben genomen, gewijzigd. Als u bijvoorbeeld code hebt die er als volgt uitziet:

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

U kunt dit wijzigen om eventuele buildfouten op te lossen:

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

Houd er ook rekening mee dat het type van de parameter referenties is gewijzigd in ServiceClientCredentials. Dit is onwaarschijnlijk dat dit van invloed is op uw code omdat SearchCredentials deze is afgeleid van ServiceClientCredentials.

Een aanvraag-id doorgeven

In oudere versies van de SDK kunt u een aanvraag-id instellen op de SearchServiceClient of SearchIndexClient en deze wordt in elke aanvraag opgenomen in de REST API. Dit is handig voor het oplossen van problemen met uw zoekservice als u contact moet opnemen met ondersteuning. Het is echter handiger om een unieke aanvraag-id in te stellen voor elke bewerking in plaats van dezelfde id te gebruiken voor alle bewerkingen. Daarom zijn de SetClientRequestId methoden van SearchServiceClient en SearchIndexClient zijn verwijderd. In plaats daarvan kunt u een aanvraag-id doorgeven aan elke bewerkingsmethode via de optionele SearchRequestOptions parameter.

Notitie

In een toekomstige release van de SDK voegen we een nieuw mechanisme toe voor het wereldwijd instellen van een aanvraag-id op de clientobjecten die consistent zijn met de benadering die wordt gebruikt door andere Azure SDK's.

Voorbeeld

Als u code hebt die er als volgt uitziet:

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

U kunt dit wijzigen om eventuele buildfouten op te lossen:

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

Wijzigingen in interfacenaam

De interfacenamen van de bewerkingsgroep zijn allemaal gewijzigd zodat ze consistent zijn met de bijbehorende eigenschapsnamen:

De naam van ISearchServiceClient.Indexes het type is gewijzigd in IIndexOperationsIIndexesOperations.
De naam van ISearchServiceClient.Indexers het type is gewijzigd in IIndexerOperationsIIndexersOperations.
De naam van ISearchServiceClient.DataSources het type is gewijzigd in IDataSourceOperationsIDataSourcesOperations.
De naam van ISearchIndexClient.Documents het type is gewijzigd in IDocumentOperationsIDocumentsOperations.

Deze wijziging is waarschijnlijk niet van invloed op uw code, tenzij u voor testdoeleinden mocks van deze interfaces hebt gemaakt.

Opgeloste fouten in versie 1.1

Er is een fout opgeslagen in oudere versies van de Azure Search .NET SDK met betrekking tot serialisatie van aangepaste modelklassen. De fout kan optreden als u een aangepaste modelklasse hebt gemaakt met een eigenschap van een niet-nullable waardetype.

Stappen om te reproduceren

Maak een aangepaste modelklasse met een eigenschap van niet-nullable waardetype. Voeg bijvoorbeeld een openbare UnitCount eigenschap van het type int toe in plaats van int?.

Als u een document indexeert met de standaardwaarde van dat type (bijvoorbeeld 0 voor int), is het veld null in Azure Search. Als u vervolgens naar dat document zoekt, zal JsonSerializationException de Search oproep klagen dat het niet kan worden geconverteerd null naar int.

Filters werken mogelijk niet zoals verwacht, omdat null naar de index is geschreven in plaats van de beoogde waarde.

Details herstellen

Dit probleem is opgelost in versie 1.1 van de SDK. Als u nu een modelklasse als volgt hebt:

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

    public int IntValue { get; set; }
}

en u instelt IntValue op 0, die waarde wordt nu correct geserialiseerd als 0 op de kabel en opgeslagen als 0 in de index. Retourtrippen werkt ook zoals verwacht.

Er is een mogelijk probleem waar u rekening mee moet houden met deze methode: als u een modeltype met een niet-null-eigenschap gebruikt, moet u garanderen dat er geen documenten in uw index een null-waarde voor het bijbehorende veld bevatten. Met de SDK en de Azure Search REST API kunt u dit afdwingen.

Dit is niet alleen een hypothetische probleem: Stel een scenario voor waarin u een nieuw veld toevoegt aan een bestaande index van het type Edm.Int32. Na het bijwerken van de indexdefinitie hebben alle documenten een null-waarde voor het nieuwe veld (omdat alle typen null in Azure Search zijn). Als u vervolgens een modelklasse met een niet-nullbare int-eigenschap voor dat veld gebruikt, ontvangt u een JsonSerializationException zoals deze bij het ophalen van documenten:

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

Daarom raden we u nog steeds aan om null-typen in uw modelklassen te gebruiken als best practice.

Zie dit probleem op GitHub voor meer informatie over deze fout en de oplossing.

Delen via

Upgrade uitvoeren naar Azure Search .NET SDK versie 1.1

Lijst met belangrijke wijzigingen in versie 1.1

Wijzigingen in IndexBatch en IndexAction

Voorbeeld

IndexBatchException-wijzigingen

Voorbeeld

Wijzigingen in de bewerkingsmethode

Wijzigingen in ScoringParameters

Voorbeeld

Modelklassewijzigingen

Voorbeeld

Antwoordklassen en IEnumerable

Speciaal geval voor webtoepassingen

Wijzigingen in CloudException

Wijzigingen in SearchServiceClient en SearchIndexClient

Een aanvraag-id doorgeven

Voorbeeld

Wijzigingen in interfacenaam

Opgeloste fouten in versie 1.1

Stappen om te reproduceren

Details herstellen

Aanvullende resources