Bagikan melalui

Penomoran halaman dengan Azure SDK untuk .NET

  • Artikel

Dalam artikel ini, Anda akan mempelajari cara menggunakan fungsionalitas paginasi Azure SDK for .NET untuk bekerja secara efisien dan produktif dengan himpunan data besar. Penomoran halaman adalah tindakan membalik himpunan data besar ke dalam halaman, sehingga memudahkan konsumen untuk melakukan iterasi melalui jumlah data yang lebih kecil. Dimulai dengan C# 8, Anda dapat membuat dan mengonsumsi aliran secara asinkron menggunakan aliran Asinkron (asinkron). Aliran asinkron didasarkan pada IAsyncEnumerable<T> antarmuka. Azure SDK untuk .NET mengekspos implementasi IAsyncEnumerable<T> dengan kelasnya AsyncPageable<T> .

Semua sampel dalam artikel ini mengandalkan paket NuGet berikut:

Untuk direktori terbaru Azure SDK untuk paket .NET, lihat Rilis terbaru Azure SDK.

Jenis pengembalian yang dapat di-pageable

Klien yang dibuat dari Azure SDK untuk .NET dapat mengembalikan jenis yang dapat di-pageable berikut.

Tipe Deskripsi
Pageable<T> Kumpulan nilai yang diambil dalam halaman
AsyncPageable<T> Kumpulan nilai yang diambil secara asinkron di halaman

Sebagian besar sampel dalam artikel ini bersifat asinkron, menggunakan variasi jenisnya AsyncPageable<T> . Menggunakan pemrograman asinkron untuk operasi terikat I/O sangat ideal. Kasus penggunaan yang sempurna menggunakan API asinkron dari Azure SDK untuk .NET karena operasi ini mewakili panggilan jaringan HTTP/S.

Iterasi dengan AsyncPageableawait foreach

Untuk melakukan iterasi melalui AsyncPageable<T> menggunakan await foreach sintaks, pertimbangkan contoh berikut:

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

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

Dalam kode C# sebelumnya:

  • Metode SecretClient.GetPropertiesOfSecretsAsync ini dipanggil dan mengembalikan AsyncPageable<SecretProperties> objek.
  • Dalam perulangan await foreach , masing-masing SecretProperties secara asinkron dihasilkan.
  • Saat masing-masing terwujud, Name masing-masing secret ditulis ke konsol.

Iterasi dengan AsyncPageablewhile

Untuk mengulangi AsyncPageable<T> saat await foreach sintaks tidak tersedia, gunakan perulangan 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();
    }
}

Dalam kode C# sebelumnya:

Iterasi di atas AsyncPageable halaman

Jika Anda ingin mengontrol penerimaan halaman nilai dari layanan, gunakan AsyncPageable<T>.AsPages metode :

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

Dalam kode C# sebelumnya:

  • Metode SecretClient.GetPropertiesOfSecretsAsync ini dipanggil dan mengembalikan AsyncPageable<SecretProperties> objek.
  • Metode AsyncPageable<T>.AsPages ini dipanggil dan mengembalikan IAsyncEnumerable<Page<SecretProperties>>.
  • Setiap halaman diulang secara asinkron, menggunakan await foreach.
  • Setiap halaman memiliki satu set Page<T>.Values, yang mewakili IReadOnlyList<T> yang diulang dengan sinkron foreach.
  • Setiap halaman juga berisi Page<T>.ContinuationToken, yang dapat digunakan untuk meminta halaman berikutnya.

Gunakan System.Linq.Async dengan AsyncPageable

Paket ini System.Linq.Async menyediakan serangkaian metode LINQ yang beroperasi pada IAsyncEnumerable<T> jenis. Karena AsyncPageable<T> mengimplementasikan IAsyncEnumerable<T>, Anda dapat menggunakan System.Linq.Async untuk mengkueri dan mengubah data.

Mengonversi ke List<T>

Gunakan ToListAsync untuk mengonversi AsyncPageable<T> ke List<T>. Metode ini mungkin melakukan beberapa panggilan layanan jika data tidak dikembalikan dalam satu halaman.

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

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

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

Dalam kode C# sebelumnya:

  • Metode SecretClient.GetPropertiesOfSecretsAsync ini dipanggil dan mengembalikan AsyncPageable<SecretProperties> objek.
  • Metode ToListAsync ini ditunggu, yang mewujudkan instans baru List<SecretProperties> .

Ambil elemen N pertama

Take hanya dapat digunakan untuk mendapatkan elemen pertama N dari AsyncPageable. Menggunakan Take akan melakukan panggilan layanan terkecil yang diperlukan untuk mendapatkan N item.

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

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

Metode lainnya

System.Linq.Asyncmenyediakan metode lain yang menyediakan fungsionalitas yang setara dengan rekan-rekan sinkron Enumerable mereka. Contoh metode tersebut termasuk Select, , Where, OrderBydan GroupBy.

Waspadalah terhadap evaluasi sisi klien

Saat menggunakan System.Linq.Async paket, waspadalah bahwa operasi LINQ dijalankan pada klien. Kueri berikut akan mengambil semua item hanya untuk menghitungnya:

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

Peringatan

Peringatan yang sama berlaku untuk operator seperti Where. Selalu pilih pemfilteran, agregasi, atau proyeksi data sisi server jika tersedia.

Sebagai urutan yang dapat diamati

Paket System.Linq.Async ini terutama digunakan untuk memberikan kemampuan pola pengamat atas IAsyncEnumerable<T> urutan. Aliran asinkron berbasis pull. Saat item mereka diulang, item berikutnya yang tersedia akan ditarik. Pendekatan ini berada dalam juxtaposition dengan pola pengamat, yang berbasis dorong. Saat item tersedia, item akan didorong ke pelanggan yang bertindak sebagai pengamat. Paket ini System.Linq.Async menyediakan ToObservable metode ekstensi yang memungkinkan Anda mengonversi IAsyncEnumerable<T> ke IObservable<T>.

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

Anda dapat menggunakan ToObservable metode ekstensi sebagai berikut:

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

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

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

Dalam kode C# sebelumnya:

  • Metode SecretClient.GetPropertiesOfSecretsAsync ini dipanggil dan mengembalikan AsyncPageable<SecretProperties> objek.
  • Metode ToObservable() ini dipanggil pada AsyncPageable<SecretProperties> instans, mengembalikan IObservable<SecretProperties>.
  • observable berlangganan, meneruskan implementasi pengamat, mengembalikan langganan ke pemanggil.
  • Langganan adalah IDisposable. Saat dibuang, langganan berakhir.

Iterasi melalui pageable

Pageable<T> adalah versi sinkron yang AsyncPageable<T> dapat digunakan dengan perulangan normal foreach .

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

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

Penting

Meskipun API sinkron ini tersedia, gunakan alternatif API asinkron untuk pengalaman yang lebih baik.

Lihat juga