Udostępnij za pośrednictwem

Stronicowanie przy użyciu zestawu Azure SDK dla platformy .NET

  • Artykuł

W tym artykule dowiesz się, jak wydajnie i wydajnie pracować z dużymi zestawami danych za pomocą zestawu Azure SDK dla platformy .NET na potrzeby stronicowania. Stronicowanie to proces dzielenia dużych zestawów danych na strony, co ułatwia konsumentowi iterowanie po mniejszych ilościach danych. Począwszy od języka C# 8, można tworzyć strumienie asynchronicznie i korzystać z nich przy użyciu strumieni asynchronicznych (asynchronicznych). Strumienie asynchroniczne są oparte na interfejsie IAsyncEnumerable<T> . Zestaw Azure SDK dla platformy .NET uwidacznia implementację klasy IAsyncEnumerable<T>AsyncPageable<T> .

Wszystkie przykłady w tym artykule bazują na następujących pakietach NuGet:

Najnowsze wersje zestawu Azure SDK dla platformy .NET można znaleźć w artykule Azure SDK latest releases (Najnowsze wersje zestawu Azure SDK).

Stronicowalne typy zwracane

Klienci utworzone z zestawu Azure SDK dla platformy .NET mogą zwracać następujące typy stronicowalne.

Type Opis
Pageable<T> Kolekcja wartości pobranych na stronach
AsyncPageable<T> Kolekcja wartości asynchronicznie pobierana na stronach

Większość przykładów w tym artykule jest asynchroniczna, używając odmian AsyncPageable<T> typu. Korzystanie z programowania asynchronicznego dla operacji związanych z operacjami we/wy jest idealne. Idealny przypadek użycia używa asynchronicznych interfejsów API z zestawu Azure SDK dla platformy .NET, ponieważ te operacje reprezentują wywołania sieciowe HTTP/S.

Iterowanie za AsyncPageable pomocą polecenia await foreach

Aby iterować AsyncPageable<T> przy użyciu await foreach składni, rozważmy następujący przykład:

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

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

W poprzednim kodzie języka C#:

  • Metoda jest wywoływana SecretClient.GetPropertiesOfSecretsAsync i zwraca AsyncPageable<SecretProperties> obiekt.
  • W pętli każda await foreachSecretProperties z nich jest asynchronicznie zwracana.
  • W miarę materializacji Name każdy secret z nich jest zapisywany w konsoli programu .

Iterowanie za AsyncPageable pomocą polecenia while

Aby iterować AsyncPageable<T> w przypadku await foreach niedostępnej składni, użyj while pętli .

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

W poprzednim kodzie języka C#:

Iterowanie na AsyncPageable stronach

Jeśli chcesz kontrolować odbieranie stron wartości z usługi, użyj AsyncPageable<T>.AsPages metody :

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

W poprzednim kodzie języka C#:

  • Metoda jest wywoływana SecretClient.GetPropertiesOfSecretsAsync i zwraca AsyncPageable<SecretProperties> obiekt.
  • Metoda AsyncPageable<T>.AsPages jest wywoływana i zwraca wartość IAsyncEnumerable<Page<SecretProperties>>.
  • Każda strona jest iteracja asynchronicznie przy użyciu metody await foreach.
  • Każda strona ma zestaw Page<T>.Values, który reprezentuje IReadOnlyList<T> iterytę z synchronicznym foreachelementem .
  • Każda strona zawiera również element Page<T>.ContinuationToken, który może służyć do żądania następnej strony.

Używanie z usługą System.Linq.AsyncAsyncPageable

Pakiet System.Linq.Async zawiera zestaw metod LINQ , które działają na IAsyncEnumerable<T> typie. Ponieważ AsyncPageable<T> implementuje IAsyncEnumerable<T>element , można użyć System.Linq.Async metody do wykonywania zapytań i przekształcania danych.

Konwertowanie na List<T>

Użyj ToListAsync polecenia , aby przekonwertować element AsyncPageable<T> na .List<T> Ta metoda może wykonać kilka wywołań usługi, jeśli dane nie są zwracane na jednej stronie.

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

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

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

W poprzednim kodzie języka C#:

  • Metoda jest wywoływana SecretClient.GetPropertiesOfSecretsAsync i zwraca AsyncPageable<SecretProperties> obiekt.
  • Oczekiwana ToListAsync jest metoda, która zmaterializuje nowe List<SecretProperties> wystąpienie.

Weź pierwsze N elementów

Take może służyć do pobierania tylko pierwszych N elementów obiektu AsyncPageable. Użycie Take spowoduje, że najmniejsze wywołania usługi będą wymagane do pobrania N elementów.

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

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

Więcej metod

System.Linq.Async udostępnia inne metody, które zapewniają funkcjonalność równoważną ich synchronicznym Enumerable odpowiednikom. Przykłady takich metod to Select, , WhereOrderByi GroupBy.

Uważaj na ocenę po stronie klienta

W przypadku korzystania z System.Linq.Async pakietu należy pamiętać, że operacje LINQ są wykonywane na kliencie. Następujące zapytanie pobierze wszystkie elementy, aby je policzyć:

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

Ostrzeżenie

To samo ostrzeżenie dotyczy operatorów, takich jak Where. Zawsze preferuj filtrowanie, agregację lub projekcje danych po stronie serwera, jeśli są dostępne.

Jako zauważalna sekwencja

Pakiet System.Linq.Async jest używany głównie do zapewniania możliwości wzorca obserwatora w IAsyncEnumerable<T> sekwencjach. Strumienie asynchroniczne są oparte na ściąganiu. Gdy ich elementy są iterowane, następny dostępny element jest ściągany. Takie podejście jest w połączeniu ze wzorcem obserwatora, który jest oparty na wypychaniach. Gdy elementy staną się dostępne, są one wypychane do subskrybentów, którzy pełnią rolę obserwatorów. Pakiet System.Linq.Async udostępnia metodę ToObservable rozszerzenia, która umożliwia konwertowanie IAsyncEnumerable<T> elementu na element IObservable<T>.

Wyobraź sobie implementację 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}");
}

Możesz użyć ToObservable metody rozszerzenia w następujący sposób:

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

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

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

W poprzednim kodzie języka C#:

  • Metoda jest wywoływana SecretClient.GetPropertiesOfSecretsAsync i zwraca AsyncPageable<SecretProperties> obiekt.
  • Metoda ToObservable() jest wywoływana w wystąpieniu AsyncPageable<SecretProperties> , zwracając element IObservable<SecretProperties>.
  • Element observable jest subskrybowany, przekazując implementację obserwatora, zwracając subskrypcję do elementu wywołującego.
  • Subskrypcja IDisposableto . Po usunięciu subskrypcja kończy się.

Iterowanie po stronie

Pageable<T> to synchroniczna wersja AsyncPageable<T> , która może być używana z normalną foreach pętlą.

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

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

Ważne

Chociaż ten synchroniczny interfejs API jest dostępny, użyj asynchronicznych alternatyw interfejsu API, aby uzyskać lepsze środowisko.

Zobacz też