Sidnumrering med Azure SDK för .NET

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:

• Azure.Security.KeyVault.Secrets
• Microsoft.Extensions.Azure
• Microsoft.Extensions.Hosting
• System.Linq.Async

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

Växlingsbara returtyper

Objekt som instansieras från Azure SDK för .NET kan returnera följande pagineringstyper.

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 avkastas varje SecretProperties asynkront.
• När var och en secret materialiseras, skrivs 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:

• Metoden SecretClient.GetPropertiesOfSecretsAsync anropas och returnerar ett AsyncPageable<SecretProperties> objekt.
• Metoden AsyncPageable<T>.GetAsyncEnumerator anropas och returnerar en IAsyncEnumerator<SecretProperties>.
• Metoden MoveNextAsync() anropas upprepade gånger tills det inte finns några objekt att returnera.

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:

• Metoden SecretClient.GetPropertiesOfSecretsAsync anropas och returnerar ett AsyncPageable<SecretProperties> objekt.
• Metoden AsyncPageable<T>.AsPages anropas och returnerar en IAsyncEnumerable<Page<SecretProperties>>.
• Varje sida itereras asynkront med hjälp av await foreach.
• Varje sida har en uppsättning Page<T>.Values, som representerar en IReadOnlyList<T> och itereras över med ett synkront foreach.
• Varje sida innehåller också en Page<T>.ContinuationToken, som kan användas för att begära nästa sida.

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 av Take görs det minsta antal 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();

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 står i kontrast till observatörsmö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> implementation:

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>.
• Prenumerationen på observable genomförs genom att skicka in observatörsimplementeringen och returnera prenumerationen till anroparen.
• Prenumerationen är en IDisposable. När den tas bort upphör prenumerationen.

Iterera över paginerbar

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

Se även

• Beroendeinmatning med Azure SDK för .NET
• Trådsäkerhet och klientlivslängdshantering för Azure SDK-objekt
• System.Linq.Async
• Aktivitetsbaserat asynkront mönster