Tutorial: Mengembangkan aplikasi web ASP.NET dengan Azure Cosmos DB for NoSQL

  • Artikel

BERLAKU UNTUK: NoSQL

Azure SDK untuk .NET memungkinkan Anda mengkueri data dalam API untuk kontainer NoSQL menggunakan LINQ di C# atau string kueri SQL. Tutorial ini akan menelusuri proses pembaruan aplikasi web ASP.NET yang ada yang menggunakan data tempat penampung untuk mengkueri dari API.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Membuat dan mengisi database dan kontainer menggunakan API untuk NoSQL
  • Membuat aplikasi web ASP.NET dari templat
  • Mengkueri data dari API untuk kontainer NoSQL menggunakan Azure SDK untuk .NET

Prasyarat

Membuat API untuk sumber daya NoSQL

Pertama, Anda akan membuat database dan kontainer di API yang ada untuk akun NoSQL. Anda kemudian akan mengisi akun ini dengan data menggunakan cosmicworks alat dotnet.

  1. Buka API yang ada untuk akun NoSQL di portal Azure.

  2. Di menu sumber daya, pilih Kunci.

    Cuplikan layar halaman akun API untuk NoSQL. Opsi Kunci disorot di menu sumber daya.

  3. Pada halaman Kunci , amati dan rekam nilai bidang STRING KONEKSI UTAMA*. Nilai ini akan digunakan sepanjang tutorial.

    Cuplikan layar halaman Kunci dengan bidang URI, Kunci Primer, dan String Koneksi ion Utama disorot.

  4. Di menu sumber daya, pilih Data Explorer.

    Cuplikan layar opsi Data Explorer disorot di menu sumber daya.

  5. Pada halaman Data Explorer , pilih opsi Kontainer Baru di bilah perintah.

    Cuplikan layar opsi Kontainer Baru di bilah perintah Data Explorer.

  6. Dalam dialog Kontainer Baru, buat kontainer baru dengan pengaturan berikut:

    Pengaturan Nilai
    Id database cosmicworks
    Jenis throughput database Manual
    Jumlah throughput database 1000
    Id Kontainer products
    Kunci partisi /category/name

    Cuplikan layar dialog Kontainer Baru di Data Explorer dengan berbagai nilai di setiap bidang.

    Penting

    Dalam tutorial ini, pertama-tama kita akan menskalakan database hingga 1.000 RU/dtk dalam throughput bersama untuk memaksimalkan performa migrasi data. Setelah migrasi data selesai, kami akan menurunkan skala hingga 400 RU/dtk throughput yang disediakan.

  7. Pilih OK untuk membuat database dan kontainer.

  8. Buka terminal untuk menjalankan perintah untuk mengisi kontainer dengan data.

    Tip

    Anda dapat secara opsional menggunakan Azure Cloud Shell di sini.

  9. Instal v2cosmicworks alat dotnet dari NuGet.

    dotnet tool install --global cosmicworks  --version 2.*

  10. cosmicworks Gunakan alat untuk mengisi API Anda untuk akun NoSQL dengan data produk sampel menggunakan nilai URI dan KUNCI PRIMER yang Anda rekam sebelumnya di lab ini. Nilai yang direkam tersebut endpoint akan digunakan untuk parameter dan key masing-masing.

    cosmicworks \
    --number-of-products 1759 \
    --number-of-employees 0 \
    --disable-hierarchical-partition-keys \
    --connection-string <nosql-connection-string>

  11. Amati output dari alat baris perintah. Ini harus menambahkan 1759 item ke kontainer. Contoh output yang disertakan dipotong untuk brevity.

    ── Parsing connection string ────────────────────────────────────────────────────────────────
╭─Connection string──────────────────────────────────────────────────────────────────────────╮
│ AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;  │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
── Populating data ──────────────────────────────────────────────────────────────────────────
╭─Products configuration─────────────────────────────────────────────────────────────────────╮
│ Database   cosmicworks                                                                     │
│ Container  products                                                                        │
│ Count      1,759                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
...
[SEED]  00000000-0000-0000-0000-000000005951 | Road-650 Black, 60 - Bikes
[SEED]  00000000-0000-0000-0000-000000005950 | Mountain-100 Silver, 42 - Bikes
[SEED]  00000000-0000-0000-0000-000000005949 | Men's Bib-Shorts, L - Clothing
[SEED]  00000000-0000-0000-0000-000000005948 | ML Mountain Front Wheel - Components
[SEED]  00000000-0000-0000-0000-000000005947 | Mountain-500 Silver, 42 - Bikes

  12. Kembali ke halaman Data Explorer untuk akun Anda.

  13. Di bagian Data , perluas simpul cosmicworks database lalu pilih Skalakan.

    Cuplikan layar opsi Skala dalam simpul database.

  14. Kurangi throughput dari 1.000 ke bawah menjadi 400.

    Cuplikan layar pengaturan throughput untuk database berkurang menjadi 400 RU/dtk.

  15. Di bilah perintah, pilih Simpan.

    Cuplikan layar opsi Simpan di bilah perintah Data Explorer.

  16. Di bagian Data , perluas dan pilih simpul kontainer produk .

    Cuplikan layar simpul kontainer yang diperluas dalam simpul database.

  17. Di bilah perintah, pilih Kueri SQL baru.

    Cuplikan layar opsi Kueri SQL Baru di bilah perintah Data Explorer.

  18. Di editor kueri, tambahkan string kueri SQL ini.

    SELECT
  p.sku,
  p.price
FROM products p
WHERE p.price < 2000
ORDER BY p.price DESC

  19. Pilih Jalankan Kueri untuk menjalankan kueri dan mengamati hasilnya.

    Cuplikan layar opsi Jalankan Kueri di bilah perintah Data Explorer.

  20. Hasilnya harus berupa array paginated dari semua item dalam kontainer dengan price nilai kurang dari 2.000 diurutkan dari harga tertinggi ke terendah. Untuk brevity, subset output disertakan di sini.

    [
  {
    "sku": "BK-R79Y-48",
    "price": 1700.99
  },
  ...
  {
    "sku": "FR-M94B-46",
    "price": 1349.6
  },
...

  21. Ganti konten editor kueri dengan kueri ini lalu pilih Jalankan Kueri lagi untuk mengamati hasilnya.

    SELECT
    p.name,
    p.category.name AS category,
    p.category.subCategory.name AS subcategory,
    p.tags
FROM products p
JOIN tag IN p.tags
WHERE STRINGEQUALS(tag, "yellow", true)

  22. Hasilnya harus berupa array item yang lebih kecil yang difilter untuk hanya berisi item yang menyertakan setidaknya satu tag dengan nilai Tag-32nama . Sekali lagi, subset output disertakan di sini untuk brevity.

    [
  ...
  {
    "name": "HL Touring Frame - Yellow, 60",
    "category": "Components",
    "subcategory": "Touring Frames",
    "tags": [
      "Components",
      "Touring Frames",
      "Yellow",
      "60"
    ]
  },
  ...
]

Membuat aplikasi web ASP.NET

Sekarang, Anda akan membuat aplikasi web ASP.NET baru menggunakan templat proyek sampel. Anda kemudian akan menjelajahi kode sumber dan menjalankan sampel untuk berkenalan dengan aplikasi sebelum menambahkan konektivitas Azure Cosmos DB menggunakan Azure SDK untuk .NET.

Penting

Tutorial ini secara transparan menarik paket dari NuGet. Anda dapat menggunakan dotnet nuget list source untuk memverifikasi sumber paket Anda. Jika Anda tidak memiliki NuGet sebagai sumber paket, gunakan dotnet nuget add source untuk menginstal situs sebagai sumber.

  1. Buka terminal di direktori kosong.

  2. cosmicworks.template.web Instal paket templat proyek dari NuGet.

    dotnet new install cosmicworks.template.web

  3. Buat proyek aplikasi web baru menggunakan templat yang baru diinstal dotnet new cosmosdbnosql-webapp .

    dotnet new cosmosdbnosql-webapp

  4. Bangun dan jalankan proyek aplikasi web.

    dotnet run

  5. Amati output perintah jalankan. Output harus mencakup daftar port dan URL tempat aplikasi berjalan.

    ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
...

  6. Buka browser baru dan navigasikan ke aplikasi web yang sedang berjalan. Amati ketiga halaman aplikasi yang sedang berjalan.

    Cuplikan layar sampel aplikasi web yang berjalan dengan data tempat penampung.

  7. Hentikan aplikasi yang sedang berjalan dengan mengakhiri proses yang sedang berjalan.

    Tip

    Gunakan perintah Ctrl+C untuk menghentikan proses yang sedang berjalan. Atau, Anda dapat menutup dan membuka kembali terminal.

  8. Buka Visual Studio Code menggunakan folder proyek saat ini sebagai ruang kerja.

    Tip

    Anda dapat menjalankan code . di terminal untuk membuka Visual Studio Code dan secara otomatis membuka direktori kerja sebagai ruang kerja saat ini.

  9. Navigasi ke dan buka file Services/ICosmosService.cs . Amati RetrieveActiveProductsAsync implementasi metode default dan RetrieveAllProductsAsync . Metode ini membuat daftar statis produk yang akan digunakan saat menjalankan proyek untuk pertama kalinya. Contoh terpotong dari salah satu metode disediakan di sini.

    public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{
    await Task.Delay(1);

    return new List<Product>()
    {
        new Product(id: "baaa4d2d-5ebe-45fb-9a5c-d06876f408e0", category: new Category(name: "Components, Road Frames"), sku: "FR-R72R-60", name: """ML Road Frame - Red, 60""", description: """The product called "ML Road Frame - Red, 60".""", price: 594.83000000000004m),
        new Product(id: "bd43543e-024c-4cda-a852-e29202310214", category: new Category(name: "Components, Forks"), sku: "FK-5136", name: """ML Fork""", description: """The product called "ML Fork".""", price: 175.49000000000001m),
        ...
    };
}

  10. Buka dan buka file Services/CosmosService.cs . Amati implementasi kelas CosmosService saat ini. Kelas ini mengimplementasikan antarmuka ICosmosService tetapi tidak mengambil alih metode apa pun. Dalam konteks ini, kelas akan menggunakan implementasi antarmuka default hingga penimpaan implementasi disediakan di antarmuka.

    public class CosmosService : ICosmosService
{ }

  11. Terakhir, navigasikan ke dan buka file Model/Product.cs dan Model/Category.cs . Amati jenis rekaman yang ditentukan dalam setiap file. Jenis ini akan digunakan dalam kueri di seluruh tutorial ini.

    public record Product(
    string id,
    Category category,
    string sku,
    string name,
    string description,
    decimal price
);

    public record Category(
    string name
);

Mengkueri data menggunakan .NET SDK

Selanjutnya, Anda akan menambahkan Azure SDK untuk .NET ke proyek sampel ini dan menggunakan pustaka untuk mengkueri data dari API untuk kontainer NoSQL.

  1. Kembali ke terminal, tambahkan Microsoft.Azure.Cosmos paket dari NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  2. Bangun proyek.

    dotnet build

  3. Kembali ke Visual Studio Code, navigasikan lagi ke file Services/CosmosService.cs .

  4. Tambahkan baru menggunakan direktif untuk Microsoft.Azure.Cosmos namespace layanan dan Microsoft.Azure.Cosmos.Linq .

    using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;

  5. Dalam kelas CosmosService, tambahkan anggota baru private readonly jenis CosmosClient bernama _client.

    private readonly CosmosClient _client;

  6. Buat konstruktor kosong baru untuk kelas .CosmosService

    public CosmosService()
{ }

  7. Dalam konstruktor, buat instans CosmosClient baru kelas yang melewati parameter string dengan nilai STRING KONEKSI UTAMA yang sebelumnya Anda rekam di lab. Simpan instans baru ini di _client anggota.

    public CosmosService()
{ 
    _client = new CosmosClient(
        connectionString: "<primary-connection-string>"
    );
}

  8. Kembali ke dalam kelas CosmosService , buat properti baru private jenis Container bernama container. Atur dapatkan aksesor untuk mengembalikan cosmicworks database dan products kontainer.

    private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}

  9. Buat metode asinkron baru bernama RetrieveAllProductsAsync yang mengembalikan IEnumerable<Product>.

    public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }

  10. Untuk langkah berikutnya, tambahkan kode ini dalam RetrieveAllProductsAsync metode .

    1. GetItemLinqQueryable<> Gunakan metode generik untuk mendapatkan objek jenis IQueryable<> yang bisa Anda gunakan untuk membuat kueri terintegrasi bahasa (LINQ). Simpan objek tersebut dalam variabel bernama queryable.

      var queryable = container.GetItemLinqQueryable<Product>();

    2. Buat kueri LINQ menggunakan Where metode ekstensi dan OrderByDescending . ToFeedIterator Gunakan metode ekstensi untuk membuat iterator untuk mendapatkan data dari Azure Cosmos DB dan menyimpan iterator dalam variabel bernama feed. Bungkus seluruh ekspresi ini dalam pernyataan penggunaan untuk membuang iterator nanti.

      using FeedIterator<Product> feed = queryable
    .Where(p => p.price < 2000m)
    .OrderByDescending(p => p.price)
    .ToFeedIterator();

    3. Buat variabel baru bernama results menggunakan jenis generik List<> .

      List<Product> results = new();

    4. Buat perulangan sementara yang akan melakukan iterasi hingga HasMoreResults properti feed variabel mengembalikan false. Perulangan ini akan memastikan bahwa Anda mengulangi semua halaman hasil sisi server.

      while (feed.HasMoreResults)
{ }

    5. Dalam perulangan sementara, secara asinkron memanggil ReadNextAsync metode feed variabel dan menyimpan hasilnya dalam variabel bernama response.

      while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}

    6. Masih dalam perulangan sementara , gunakan perulangan foreach untuk menelusuri setiap item dalam respons dan menambahkannya ke results daftar.

      while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}

    7. results Mengembalikan daftar sebagai output metode RetrieveAllProductsAsync .

      return results;

  11. Buat metode asinkron baru bernama RetrieveActiveProductsAsync yang mengembalikan IEnumerable<Product>.

    public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }

  12. Untuk langkah berikutnya, tambahkan kode ini dalam RetrieveActiveProductsAsync metode .

    1. Buat string baru bernama sql dengan kueri SQL untuk mengambil beberapa bidang di mana filter (@tagFilter) diterapkan ke array tag dari setiap item.

      string sql = """
SELECT
    p.id,
    p.name,
    p.category,
    p.sku,
    p.description,
    p.price
FROM products p
JOIN tag IN p.tags
WHERE STRINGEQUALS(tag, @tagFilter, true)
""";

    2. Buat variabel baru QueryDefinition bernama query passing dalam sql string sebagai satu-satunya parameter kueri. Selain itu WithParameter , gunakan metode cairan untuk menerapkan nilai red ke @tagFilter parameter .

      var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "red");

    3. GetItemQueryIterator<> Gunakan metode generik dan query variabel untuk membuat iterator yang mendapatkan data dari Azure Cosmos DB. Simpan iterator dalam variabel bernama feed. Bungkus seluruh ekspresi ini dalam pernyataan penggunaan untuk membuang iterator nanti.

      using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

    4. Gunakan perulangan sementara untuk melakukan iterasi melalui beberapa halaman hasil dan menyimpan nilai dalam hasil bernama generikList<>. Mengembalikan hasil sebagai output metode RetrieveActiveProductsAsync .

      List<Product> results = new();

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}

return results;

  13. Simpan file Services/CosmosClient.cs.

    Tip

    Jika Anda tidak yakin bahwa kode Anda benar, Anda dapat memeriksa kode sumber Terhadap kode sampel di GitHub.

Memvalidasi aplikasi akhir

Terakhir, Anda akan menjalankan aplikasi dengan hot reload diaktifkan . Menjalankan aplikasi akan memvalidasi bahwa kode Anda dapat mengakses data dari API untuk NoSQL.

  1. Kembali ke terminal, jalankan aplikasi.

    dotnet run

  2. Output perintah jalankan harus menyertakan daftar port dan URL tempat aplikasi berjalan. Buka browser baru dan navigasikan ke aplikasi web yang sedang berjalan. Amati ketiga halaman aplikasi yang sedang berjalan. Setiap halaman sekarang harus menyertakan data langsung dari Azure Cosmos DB.

Membersihkan sumber daya

Jika tidak lagi diperlukan, hapus database yang digunakan dalam tutorial ini. Untuk melakukannya, navigasikan ke halaman akun, pilih Data Explorer, pilih cosmicworks database, lalu pilih Hapus.

Langkah berikutnya

Sekarang setelah Anda membuat aplikasi web .NET pertama Anda menggunakan Azure Cosmos DB, Anda sekarang dapat mendalami lebih dalam SDK untuk mengimpor lebih banyak data, melakukan kueri kompleks, dan mengelola sumber daya Azure Cosmos DB for NoSQL Anda.

Mulai menggunakan Azure Cosmos DB untuk NoSQL dan .NET