Sdílet prostřednictvím

Stránkování pomocí sady Azure SDK pro .NET

  • Článek

V tomto článku se dozvíte, jak používat funkci stránkování sady Azure SDK pro .NET k efektivní a produktivní práci s velkými datovými sadami. Stránkování je rozdělení velkých datových sad na stránky, což usnadňuje uživatelům iteraci menšími objemy dat. Počínaje jazykem C# 8 můžete vytvářet a využívat streamy asynchronně pomocí asynchronních (asynchronních) datových proudů. Asynchronní streamy jsou založené na IAsyncEnumerable<T> rozhraní. Sada Azure SDK pro .NET zveřejňuje implementaci IAsyncEnumerable<T> s její AsyncPageable<T> třídou.

Všechny ukázky v tomto článku se spoléhají na následující balíčky NuGet:

Nejnovější adresář sady Azure SDK pro balíčky .NET najdete v nejnovějších verzích sady Azure SDK.

Návratové typy s možností stránky

Klienti, kteří vytvořili instanci ze sady Azure SDK pro .NET, můžou vrátit následující stránkovatelné typy.

Typ Popis
Pageable<T> Kolekce hodnot načtených na stránkách
AsyncPageable<T> Kolekce hodnot asynchronně načtených na stránkách

Většina ukázek v tomto článku je asynchronní a používá varianty AsyncPageable<T> typu. Použití asynchronního programování pro vstupně-výstupní operace je ideální. Dokonalý případ použití používá asynchronní rozhraní API ze sady Azure SDK pro .NET, protože tyto operace představují síťová volání HTTP/S.

Iterace s využitím AsyncPageableawait foreach

Pokud chcete iterovat syntaxi AsyncPageable<T> pomocí await foreach , zvažte následující příklad:

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

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

V předchozím kódu jazyka C#:

  • Metoda SecretClient.GetPropertiesOfSecretsAsync je vyvolána a vrátí AsyncPageable<SecretProperties> objekt.
  • await foreach Ve smyčce je každý SecretProperties asynchronně výnosný.
  • Vzhledem k tomu, že každý secret je materializován, je Name zapsán do konzoly.

Iterace s využitím AsyncPageablewhile

Pokud chcete iterovat, AsyncPageable<T> když await foreach syntaxe není dostupná, použijte smyčku while .

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

V předchozím kódu jazyka C#:

Iterace přes AsyncPageable stránky

Pokud chcete mít kontrolu nad příjmem stránek hodnot ze služby, použijte metodu AsyncPageable<T>.AsPages :

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

V předchozím kódu jazyka C#:

Použití s System.Linq.AsyncAsyncPageable

Balíček System.Linq.Async poskytuje sadu metod LINQ , které pracují s typem IAsyncEnumerable<T> . Vzhledem k tomu AsyncPageable<T> , že implementuje IAsyncEnumerable<T>, můžete použít System.Linq.Async k dotazování a transformaci dat.

Převést na List<T>

Slouží ToListAsync k převodu na AsyncPageable<T> .List<T> Tato metoda může volat několik služeb, pokud se data nevrátí na jedné stránce.

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

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

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

V předchozím kódu jazyka C#:

  • Metoda SecretClient.GetPropertiesOfSecretsAsync je vyvolána a vrátí AsyncPageable<SecretProperties> objekt.
  • Očekává se ToListAsync metoda, která materializuje novou List<SecretProperties> instanci.

Vezměte první prvky N.

Take lze použít k získání pouze prvních N prvků AsyncPageable. Použití Take provede nejmenší volání služby potřebné k získání N položek.

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

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

Další metody

System.Linq.Async poskytuje další metody, které poskytují funkce ekvivalentní jejich synchronním Enumerable protějškům. Mezi příklady takových metod patří Select, Where, OrderBy, a GroupBy.

Vyhodnocení na straně klienta

Při použití System.Linq.Async balíčku si dávejte pozor, aby se na klientovi spouštěly operace LINQ. Následující dotaz načte všechny položky, které se mají spočítat:

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

Upozorňující

Stejné upozornění platí pro operátory, jako je Where. Vždy preferujte filtrování, agregaci nebo projekce dat na straně serveru, pokud jsou k dispozici.

Jako pozorovatelná posloupnost

Balíček System.Linq.Async se primárně používá k poskytování funkcí vzorů pozorovatele v sekvencích IAsyncEnumerable<T> . Asynchronní datové proudy jsou založené na vyžádání. S tím, jak jsou jejich položky iterated, další dostupná položka se načítá. Tento přístup je v juxtapozici se vzorem pozorovatele, který je založený na zápisu. Jakmile budou položky k dispozici, budou nasdílené odběratelům, kteří fungují jako pozorovatelé. Balíček System.Linq.Async poskytuje rozšiřující metoduToObservable, která umožňuje převést na IAsyncEnumerable<T> .IObservable<T>

Představte si implementaci 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}");
}

Metodu ToObservable rozšíření můžete využít následujícím způsobem:

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

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

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

V předchozím kódu jazyka C#:

  • Metoda SecretClient.GetPropertiesOfSecretsAsync je vyvolána a vrátí AsyncPageable<SecretProperties> objekt.
  • Metoda ToObservable() je volána v AsyncPageable<SecretProperties> instanci a vrací .IObservable<SecretProperties>
  • Odběr observable se přihlásí, předá implementaci pozorovatele a vrátí předplatné volajícímu.
  • Předplatné je .IDisposable Jakmile se odstraní, předplatné skončí.

Iterace přes stránkovatelné

Pageable<T> je synchronní verze AsyncPageable<T> , kterou lze použít s normální foreach smyčkou.

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

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

Důležité

I když je toto synchronní rozhraní API k dispozici, pro lepší prostředí využijte alternativy asynchronního rozhraní API.

Viz také