Delen via

Paginering met de Azure SDK voor .NET

In dit artikel leert u hoe u de Azure SDK voor .NET-pagineringsfunctionaliteit gebruikt om efficiënt en productief te werken met grote gegevenssets. Paginering is het verdelen van grote gegevenssets in pagina's, waardoor de consument gemakkelijker kleinere hoeveelheden gegevens kan doorlopen. Vanaf C# 8 kunt u streams asynchroon maken en gebruiken met behulp van Asynchrone (asynchrone) streams. Asynchrone streams zijn gebaseerd op de IAsyncEnumerable<T> interface. De Azure SDK voor .NET biedt een implementatie van IAsyncEnumerable<T> met zijn AsyncPageable<T> klasse.

Alle voorbeelden in dit artikel zijn afhankelijk van de volgende NuGet-pakketten:

Voor de nieuwste map van Azure SDK voor .NET-pakketten raadpleegt u de nieuwste versies van Azure SDK.

Pagina-gebaseerde retourtypen

Clients die zijn geïnstantieerd vanuit de Azure SDK voor .NET, kunnen de volgende paginabare typen retourneren.

Typologie Beschrijving
Pageable<T> Een verzameling waarden die uit pagina's zijn opgehaald.
AsyncPageable<T> Een verzameling waarden die asynchroon worden opgehaald op pagina's

De meeste voorbeelden in dit artikel zijn asynchroon, met behulp van variaties van het AsyncPageable<T> type. Het gebruik van asynchrone programmering voor I/O-gebonden bewerkingen is ideaal. Een perfecte use-case is het gebruik van de asynchrone API's van de Azure SDK voor .NET, omdat deze bewerkingen HTTP/S-netwerkoproepen vertegenwoordigen.

Itereer over AsyncPageable met await foreach

Om over een AsyncPageable<T> te itereren met behulp van de await foreach syntaxis, bekijk het volgende voorbeeld:

async Task IterateSecretsWithAwaitForeachAsync()
{
    AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

    await foreach (SecretProperties secret in allSecrets)
    {
        Console.WriteLine($"IterateSecretsWithAwaitForeachAsync: {secret.Name}");
    }
}

In de voorgaande C#-code:

  • De SecretClient.GetPropertiesOfSecretsAsync methode wordt aangeroepen en retourneert een AsyncPageable<SecretProperties> object.
  • In een await foreach lus wordt elk SecretProperties asynchroon opgeleverd.
  • Wanneer elke secret wordt gerealiseerd, wordt de Name naar de console geschreven.

Itereer over AsyncPageable met while

Om over een AsyncPageable<T> te itereren wanneer de await foreach syntaxis niet beschikbaar is, gebruikt u een while lus.

async Task IterateSecretsWithWhileLoopAsync()
{
    AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

    IAsyncEnumerator<SecretProperties> enumerator = allSecrets.GetAsyncEnumerator();
    try
    {
        while (await enumerator.MoveNextAsync())
        {
            SecretProperties secret = enumerator.Current;
            Console.WriteLine($"IterateSecretsWithWhileLoopAsync: {secret.Name}");
        }
    }
    finally
    {
        await enumerator.DisposeAsync();
    }
}

In de voorgaande C#-code:

Itereren over AsyncPageable pagina's

Als u controle wilt over het ontvangen van pagina's met waarden van de service, gebruikt u de AsyncPageable<T>.AsPages methode:

async Task IterateSecretsAsPagesAsync()
{
    AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

    await foreach (Page<SecretProperties> page in allSecrets.AsPages())
    {
        foreach (SecretProperties secret in page.Values)
        {
            Console.WriteLine($"IterateSecretsAsPagesAsync: {secret.Name}");
        }

        // The continuation token that can be used in AsPages call to resume enumeration
        Console.WriteLine(page.ContinuationToken);
    }
}

In de voorgaande C#-code:

  • De SecretClient.GetPropertiesOfSecretsAsync methode wordt aangeroepen en retourneert een AsyncPageable<SecretProperties> object.
  • De AsyncPageable<T>.AsPages methode wordt aangeroepen en retourneert een IAsyncEnumerable<Page<SecretProperties>>.
  • Elke pagina wordt asynchroon geïtereerd, met behulp van await foreach.
  • Elke pagina heeft een set Page<T>.Values, die een IReadOnlyList<T> vertegenwoordigt en die wordt geïtereerd met een synchrone foreach.
  • Elke pagina bevat ook een Page<T>.ContinuationToken, die kan worden gebruikt om de volgende pagina aan te vragen.

System.Linq.Async gebruiken met AsyncPageable

Het System.Linq.Async pakket biedt een set LINQ-methoden die op IAsyncEnumerable<T> type werken. Omdat AsyncPageable<T>IAsyncEnumerable<T> implementeert, kunt u System.Linq.Async gebruiken om de gegevens op te vragen en te transformeren.

Converteren naar een List<T>

Hiermee ToListAsync converteert u een AsyncPageable<T> naar een List<T>. Met deze methode kunnen verschillende serviceaanroepen worden uitgevoerd als de gegevens niet op één pagina terugkomen.

async Task ToListAsync()
{
    AsyncPageable<SecretProperties> allSecrets =
        client.GetPropertiesOfSecretsAsync();

    List<SecretProperties> secretList = await allSecrets.ToListAsync();

    secretList.ForEach(secret =>
        Console.WriteLine($"ToListAsync: {secret.Name}"));
}

In de voorgaande C#-code:

  • De SecretClient.GetPropertiesOfSecretsAsync methode wordt aangeroepen en retourneert een AsyncPageable<SecretProperties> object.
  • De ToListAsync methode wordt afgewacht, wat resulteert in een nieuwe List<SecretProperties> instantie.

Neem de eerste N-elementen

Take kan worden gebruikt om alleen de eerste N elementen van de AsyncPageable te krijgen. Met het gebruik Take worden de minste service-aanroepen uitgevoerd die nodig zijn om items op te halen N .

async Task TakeAsync(int count = 30)
{
    AsyncPageable<SecretProperties> allSecrets =
        client.GetPropertiesOfSecretsAsync();

    await foreach (SecretProperties secret in allSecrets.Take(count))
    {
        Console.WriteLine($"TakeAsync: {secret.Name}");
    }
}

Meer methoden

System.Linq.Async biedt andere methoden die functionaliteit bieden die equivalent is aan hun synchrone Enumerable tegenhangers. Voorbeelden van dergelijke methoden zijn Select, Where, en OrderByGroupBy.

Pas op voor evaluatie aan de clientzijde

Wanneer u het System.Linq.Async pakket gebruikt, moet u ervoor zorgen dat LINQ-bewerkingen op de client worden uitgevoerd. Met de volgende query worden alle items opgehaald om ze te tellen:

// ⚠️ DON'T DO THIS! 😲
int expensiveSecretCount =
    await client.GetPropertiesOfSecretsAsync()
        .CountAsync();

Waarschuwing

Dezelfde waarschuwing geldt voor operators zoals Where. Geef altijd de voorkeur aan filteren, aggregatie of projecties van gegevens op de server, indien beschikbaar.

Als een waarneembare reeks

Het System.Linq.Async pakket wordt voornamelijk gebruikt om waarnemerspatroonmogelijkheden te bieden via IAsyncEnumerable<T> reeksen. Asynchrone streams zijn pull-gebaseerd. Wanneer hun items worden geïtereerd, wordt het volgende beschikbare item opgehaald. Deze benadering bevindt zich in tegenstelling tot het observer pattern, dat op push gebaseerd is. Wanneer er items beschikbaar komen, worden ze gestuurd naar abonnees die als waarnemers fungeren. Het System.Linq.Async pakket biedt de ToObservable extensiemethode waarmee u een IAsyncEnumerable<T> bestand kunt converteren naar een IObservable<T>.

Stel je een IObserver<SecretProperties> implementatie voor

sealed file class SecretPropertyObserver : IObserver<SecretProperties>
{
    public void OnCompleted() =>
        Console.WriteLine("Done observing secrets");

    public void OnError(Exception error) =>
        Console.WriteLine($"Error observing secrets: {error}");

    public void OnNext(SecretProperties secret) =>
        Console.WriteLine($"Observable: {secret.Name}");
}

U kunt de ToObservable extensiemethode als volgt gebruiken:

IDisposable UseTheToObservableMethod()
{
    AsyncPageable<SecretProperties> allSecrets =
        client.GetPropertiesOfSecretsAsync();

    IObservable<SecretProperties> observable = allSecrets.ToObservable();

    return observable.Subscribe(
        new SecretPropertyObserver());
}

In de voorgaande C#-code:

  • De SecretClient.GetPropertiesOfSecretsAsync methode wordt aangeroepen en retourneert een AsyncPageable<SecretProperties> object.
  • De ToObservable() methode wordt aangeroepen op het AsyncPageable<SecretProperties> exemplaar en retourneert een IObservable<SecretProperties>.
  • Het observable abonnement wordt geabonneerd, doorgegeven in de implementatie van de waarnemer, die het abonnement retourneert naar de beller.
  • Het abonnement is een IDisposable. Wanneer het wordt verwijderd, eindigt het abonnement.

Paginabaar herhalen

Pageable<T> is een synchrone versie van AsyncPageable<T> die kan worden gebruikt met een normale foreach lus.

void IterateWithPageable()
{
    Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

    foreach (SecretProperties secret in allSecrets)
    {
        Console.WriteLine($"IterateWithPageable: {secret.Name}");
    }
}

Belangrijk

Hoewel deze synchrone API beschikbaar is, gebruikt u de asynchrone API-alternatieven voor een betere ervaring.

Zie ook