Tutorial: Mengembangkan aplikasi web ASP.NET dengan Azure Cosmos DB for NoSQL
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
- Akun Azure Cosmos DB for NoSQL yang sudah ada.
- Jika Anda memiliki langganan Azure yang sudah ada, buat akun baru.
- Tidak ada langganan Azure? Anda dapat mencoba Azure Cosmos DB gratis tanpa kartu kredit yang diperlukan.
- Visual Studio Code
- .NET 6 (LTS) atau yang lebih baru
- Pengalaman menulis aplikasi C#.
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.
Buka API yang ada untuk akun NoSQL di portal Azure.
Di menu sumber daya, pilih Kunci.
Pada halaman Kunci , amati dan rekam nilai bidang STRING KONEKSI UTAMA*. Nilai ini akan digunakan sepanjang tutorial.
Di menu sumber daya, pilih Data Explorer.
Pada halaman Data Explorer , pilih opsi Kontainer Baru di bilah perintah.
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
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.
Pilih OK untuk membuat database dan kontainer.
Buka terminal untuk menjalankan perintah untuk mengisi kontainer dengan data.
Tip
Anda dapat secara opsional menggunakan Azure Cloud Shell di sini.
Instal v2
cosmicworks
alat dotnet dari NuGet.dotnet tool install --global cosmicworks --version 2.*
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 tersebutendpoint
akan digunakan untuk parameter dankey
masing-masing.cosmicworks \ --number-of-products 1759 \ --number-of-employees 0 \ --disable-hierarchical-partition-keys \ --connection-string <nosql-connection-string>
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
Kembali ke halaman Data Explorer untuk akun Anda.
Di bagian Data , perluas simpul
cosmicworks
database lalu pilih Skalakan.Kurangi throughput dari 1.000 ke bawah menjadi 400.
Di bilah perintah, pilih Simpan.
Di bagian Data , perluas dan pilih simpul kontainer produk .
Di bilah perintah, pilih Kueri SQL baru.
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
Pilih Jalankan Kueri untuk menjalankan kueri dan mengamati hasilnya.
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 }, ...
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)
Hasilnya harus berupa array item yang lebih kecil yang difilter untuk hanya berisi item yang menyertakan setidaknya satu tag dengan nilai
Tag-32
nama . 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.
Buka terminal di direktori kosong.
cosmicworks.template.web
Instal paket templat proyek dari NuGet.dotnet new install cosmicworks.template.web
Buat proyek aplikasi web baru menggunakan templat yang baru diinstal
dotnet new cosmosdbnosql-webapp
.dotnet new cosmosdbnosql-webapp
Bangun dan jalankan proyek aplikasi web.
dotnet run
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 ...
Buka browser baru dan navigasikan ke aplikasi web yang sedang berjalan. Amati ketiga halaman aplikasi yang sedang berjalan.
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.
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.Navigasi ke dan buka file Services/ICosmosService.cs . Amati
RetrieveActiveProductsAsync
implementasi metode default danRetrieveAllProductsAsync
. 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), ... }; }
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 { }
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.
Kembali ke terminal, tambahkan
Microsoft.Azure.Cosmos
paket dari NuGet.dotnet add package Microsoft.Azure.Cosmos
Bangun proyek.
dotnet build
Kembali ke Visual Studio Code, navigasikan lagi ke file Services/CosmosService.cs .
Tambahkan baru menggunakan direktif untuk
Microsoft.Azure.Cosmos
namespace layanan danMicrosoft.Azure.Cosmos.Linq
.using Microsoft.Azure.Cosmos; using Microsoft.Azure.Cosmos.Linq;
Dalam kelas CosmosService, tambahkan anggota baru
private readonly
jenisCosmosClient
bernama_client
.private readonly CosmosClient _client;
Buat konstruktor kosong baru untuk kelas .
CosmosService
public CosmosService() { }
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>" ); }
Kembali ke dalam kelas CosmosService , buat properti baru
private
jenisContainer
bernamacontainer
. Atur dapatkan aksesor untuk mengembalikancosmicworks
database danproducts
kontainer.private Container container { get => _client.GetDatabase("cosmicworks").GetContainer("products"); }
Buat metode asinkron baru bernama
RetrieveAllProductsAsync
yang mengembalikanIEnumerable<Product>
.public async Task<IEnumerable<Product>> RetrieveAllProductsAsync() { }
Untuk langkah berikutnya, tambahkan kode ini dalam
RetrieveAllProductsAsync
metode .GetItemLinqQueryable<>
Gunakan metode generik untuk mendapatkan objek jenisIQueryable<>
yang bisa Anda gunakan untuk membuat kueri terintegrasi bahasa (LINQ). Simpan objek tersebut dalam variabel bernamaqueryable
.var queryable = container.GetItemLinqQueryable<Product>();
Buat kueri LINQ menggunakan
Where
metode ekstensi danOrderByDescending
.ToFeedIterator
Gunakan metode ekstensi untuk membuat iterator untuk mendapatkan data dari Azure Cosmos DB dan menyimpan iterator dalam variabel bernamafeed
. 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();
Buat variabel baru bernama
results
menggunakan jenis generikList<>
.List<Product> results = new();
Buat perulangan sementara yang akan melakukan iterasi hingga
HasMoreResults
propertifeed
variabel mengembalikan false. Perulangan ini akan memastikan bahwa Anda mengulangi semua halaman hasil sisi server.while (feed.HasMoreResults) { }
Dalam perulangan sementara, secara asinkron memanggil
ReadNextAsync
metodefeed
variabel dan menyimpan hasilnya dalam variabel bernamaresponse
.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); }
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); } }
results
Mengembalikan daftar sebagai output metodeRetrieveAllProductsAsync
.return results;
Buat metode asinkron baru bernama
RetrieveActiveProductsAsync
yang mengembalikanIEnumerable<Product>
.public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync() { }
Untuk langkah berikutnya, tambahkan kode ini dalam
RetrieveActiveProductsAsync
metode .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) """;
Buat variabel baru
QueryDefinition
bernamaquery
passing dalamsql
string sebagai satu-satunya parameter kueri. Selain ituWithParameter
, gunakan metode cairan untuk menerapkan nilaired
ke@tagFilter
parameter .var query = new QueryDefinition( query: sql ) .WithParameter("@tagFilter", "red");
GetItemQueryIterator<>
Gunakan metode generik danquery
variabel untuk membuat iterator yang mendapatkan data dari Azure Cosmos DB. Simpan iterator dalam variabel bernamafeed
. Bungkus seluruh ekspresi ini dalam pernyataan penggunaan untuk membuang iterator nanti.using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>( queryDefinition: query );
Gunakan perulangan sementara untuk melakukan iterasi melalui beberapa halaman hasil dan menyimpan nilai dalam hasil bernama generik
List<>
. Mengembalikan hasil sebagai output metodeRetrieveActiveProductsAsync
.List<Product> results = new(); while (feed.HasMoreResults) { FeedResponse<Product> response = await feed.ReadNextAsync(); foreach (Product item in response) { results.Add(item); } } return results;
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.
Kembali ke terminal, jalankan aplikasi.
dotnet run
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.