Delen via

Paginering met de Azure SDK voor .NET

  • Artikel

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. Met de Azure SDK voor .NET wordt een implementatie van IAsyncEnumerable<T> deze AsyncPageable<T> klasse weergegeven.

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.

Paginabare retourtypen

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

Type Description
Pageable<T> Een verzameling waarden die zijn opgehaald in pagina's
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.

AsyncPageable Herhalen metawait foreach

Als u de AsyncPageable<T>await foreach syntaxis wilt herhalen, bekijkt u 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 geretourneerd.
  • Zoals elk secret is gerealiseerd, Name wordt het naar de console geschreven.

AsyncPageable Herhalen metwhile

Als u de syntaxis wilt herhalen AsyncPageable<T> 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:

Pagina's herhalen AsyncPageable

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 curseerd, met behulp van await foreach.
  • Elke pagina heeft een set Page<T>.Values, die een IReadOnlyList<T> is die wordt ge curseerd met een synchrone foreach.
  • Elke pagina bevat ook een Page<T>.ContinuationToken, die kan worden gebruikt om de volgende pagina aan te vragen.

Gebruiken System.Linq.Async met AsyncPageable

Het System.Linq.Async pakket biedt een set LINQ-methoden die op IAsyncEnumerable<T> type werken. Omdat AsyncPageable<T> dit wordt geïmplementeerd IAsyncEnumerable<T>, kunt u de System.Linq.Async gegevens opvragen en transformeren.

Converteren naar een List<T>

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

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 in afwachting van een nieuwe List<SecretProperties> instantie.

Neem de eerste N-elementen

Take kan worden gebruikt om alleen de eerste N elementen van de AsyncPageable. 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 curseerd, wordt het volgende beschikbare item opgehaald. Deze benadering bevindt zich in juxtapositie met het waarnemerspatroon, dat op push gebaseerde is. Wanneer er items beschikbaar komen, worden ze gepusht 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 u een implementatie voor IObserver<SecretProperties> :

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 abonnement wordt verwijderd, wordt het abonnement beëindigd.

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