Dela via

Sidnumrering med Azure SDK för .NET

  • Artikel

I den här artikeln får du lära dig hur du använder Azure SDK för .NET-sidnumreringsfunktioner för att arbeta effektivt och produktivt med stora datamängder. Sidnumrering handlar om att dela upp stora datamängder i sidor, vilket gör det enklare för konsumenten att iterera genom mindre mängder data. Från och med C# 8 kan du skapa och använda strömmar asynkront med Asynkrona (asynkrona) strömmar. Asynkrona strömmar baseras på IAsyncEnumerable<T> gränssnittet. Azure SDK för .NET exponerar en implementering av IAsyncEnumerable<T> med sin AsyncPageable<T> klass.

Alla exempel i den här artikeln förlitar sig på följande NuGet-paket:

Den senaste katalogen med Azure SDK för .NET-paket finns i De senaste versionerna av Azure SDK.

Växlingsbara returtyper

Klienter som instansieras från Azure SDK för .NET kan returnera följande växlingsbara typer.

Typ Beskrivning
Pageable<T> En samling värden som hämtats på sidor
AsyncPageable<T> En samling värden som hämtas asynkront på sidor

De flesta av exemplen i den här artikeln är asynkrona och använder varianter av typen AsyncPageable<T> . Det är idealiskt att använda asynkron programmering för I/O-bundna åtgärder. Ett perfekt användningsfall är att använda asynkrona API:er från Azure SDK för .NET eftersom dessa åtgärder representerar HTTP/S-nätverksanrop.

Iterera över AsyncPageable med await foreach

Om du vill iterera över en AsyncPageable<T> med hjälp av syntaxen await foreach bör du överväga följande exempel:

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

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

I föregående C#-kod:

  • Metoden SecretClient.GetPropertiesOfSecretsAsync anropas och returnerar ett AsyncPageable<SecretProperties> objekt.
  • I en await foreach loop returneras var och SecretProperties en asynkront.
  • När var och en secret materialiseras skrivs den Name till konsolen.

Iterera över AsyncPageable med while

Om du vill iterera över en AsyncPageable<T> när syntaxen await foreach inte är tillgänglig använder du en while loop.

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

I föregående C#-kod:

Iterera över AsyncPageable sidor

Om du vill ha kontroll över att ta emot sidor med värden från tjänsten använder du AsyncPageable<T>.AsPages metoden:

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

I föregående C#-kod:

Använd System.Linq.Async med AsyncPageable

Paketet System.Linq.Async innehåller en uppsättning LINQ-metoder som fungerar på IAsyncEnumerable<T> typ. Eftersom AsyncPageable<T> implementerar IAsyncEnumerable<T>kan du använda System.Linq.Async för att fråga och transformera data.

Konvertera till en List<T>

Använd ToListAsync för att konvertera en AsyncPageable<T> till en List<T>. Den här metoden kan göra flera tjänstanrop om data inte returneras på en enda sida.

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

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

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

I föregående C#-kod:

  • Metoden SecretClient.GetPropertiesOfSecretsAsync anropas och returnerar ett AsyncPageable<SecretProperties> objekt.
  • Metoden ToListAsync väntar, vilket materialiserar en ny List<SecretProperties> instans.

Ta de första N-elementen

Take kan endast användas för att hämta de första N elementen i AsyncPageable. Med hjälp Take av görs de minsta tjänstanrop som krävs för att hämta N objekt.

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

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

Fler metoder

System.Linq.Async tillhandahåller andra metoder som ger funktioner som motsvarar deras synkrona Enumerable motsvarigheter. Exempel på sådana metoder är Select, Where, OrderByoch GroupBy.

Akta dig för utvärdering på klientsidan

När du använder System.Linq.Async paketet bör du se upp för att LINQ-åtgärder körs på klienten. Följande fråga hämtar alla objekt bara för att räkna dem:

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

Varning

Samma varning gäller för operatorer som Where. Föredra alltid filtrering, aggregering eller projektioner av data på serversidan om det är tillgängligt.

Som en observerbar sekvens

Paketet System.Linq.Async används främst för att tillhandahålla övervakningsmönsterfunktioner över IAsyncEnumerable<T> sekvenser. Asynkrona strömmar är pull-baserade. När deras objekt itereras över hämtas nästa tillgängliga objekt. Den här metoden är i kombination med övervakningsmönstret, som är push-baserat. När objekt blir tillgängliga skickas de till prenumeranter som fungerar som observatörer. Paketet System.Linq.Async innehåller tilläggsmetoden ToObservable som gör att du kan konvertera en IAsyncEnumerable<T> till en IObservable<T>.

Föreställ dig en IObserver<SecretProperties> implementering:

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

Du kan använda ToObservable tilläggsmetoden på följande sätt:

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

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

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

I föregående C#-kod:

  • Metoden SecretClient.GetPropertiesOfSecretsAsync anropas och returnerar ett AsyncPageable<SecretProperties> objekt.
  • Metoden ToObservable() anropas på instansen AsyncPageable<SecretProperties> och returnerar en IObservable<SecretProperties>.
  • observable prenumererar på, skickar in observatörsimplementeringen och returnerar prenumerationen till anroparen.
  • Prenumerationen är en IDisposable. När den tas bort upphör prenumerationen.

Iterera över växlingsbar

Pageable<T> är en synkron version av AsyncPageable<T> som kan användas med en normal foreach loop.

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

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

Viktigt!

Även om det här synkrona API:et är tillgängligt använder du de asynkrona API-alternativen för en bättre upplevelse.

Se även