Bagikan melalui

Tutorial: Mengembangkan aplikasi konsol .NET dengan Azure Cosmos DB untuk NoSQL

  • Artikel

BERLAKU UNTUK: NoSQL

Azure SDK untuk .NET memungkinkan Anda menambahkan data ke API untuk kontainer NoSQL baik operasi individu asinkron atau batch transaksional. Tutorial ini menjelaskan proses pembuatan aplikasi konsol .NET baru yang menambahkan beberapa item ke kontainer.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Membuat database menggunakan API untuk NoSQL
  • Buat aplikasi konsol .NET dan tambahkan Azure SDK untuk .NET
  • Menambahkan item individual ke dalam API untuk kontainer NoSQL
  • Mengambil item yang efisien dari API untuk kontainer NoSQL
  • Membuat transaksi dengan perubahan batch untuk API untuk kontainer NoSQL

Prasyarat

Membuat API untuk sumber daya NoSQL

Pertama, buat database kosong di API yang ada untuk akun NoSQL. Anda membuat kontainer menggunakan Azure SDK untuk .NET nanti.

  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 URI dan KUNCI PRIMER. Nilai-nilai ini digunakan di seluruh tutorial.

    Cuplikan layar halaman Kunci dengan bidang URI dan Kunci Primer 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 Database Baru di bilah perintah.

    Cuplikan layar opsi Database Baru di bilah perintah Data Explorer.

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

    Nilai
    Id database cosmicworks
    Jenis throughput database Manual
    Jumlah throughput database 400

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

  7. Pilih OK untuk membuat database.

Membuat aplikasi konsol .NET

Sekarang, Anda membuat aplikasi konsol .NET baru dan mengimpor Azure SDK untuk .NET dengan menggunakan Microsoft.Azure.Cosmos pustaka dari NuGet.

  1. Buka terminal di direktori kosong.

  2. Membuat aplikasi konsol baru menggunakan templat bawaan console

    dotnet new console --langVersion preview

  3. Tambahkan versi pratinjau 3.31.1 dari Microsoft.Azure.Cosmos paket dari NuGet.

    dotnet add package Microsoft.Azure.Cosmos --version 3.31.1-preview

  4. Selain itu, tambahkan versi System.CommandLine pra-rilis paket dari NuGet.

    dotnet add package System.CommandLine --prerelease

  5. Selain itu Humanizer , tambahkan paket dari NuGet.

    dotnet add package Humanizer

  6. Bangun proyek aplikasi konsol.

    dotnet build

  7. 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.

  8. Navigasi ke dan buka file Program.cs . Hapus semua kode yang ada dalam file.

  9. Tambahkan kode ini ke file untuk menggunakan pustaka System.CommandLine untuk mengurai baris perintah untuk dua string yang diteruskan melalui --first opsi dan --last .

    using System.CommandLine;

var command = new RootCommand();

var nameOption = new Option<string>("--name") { IsRequired = true };
var emailOption = new Option<string>("--email");
var stateOption = new Option<string>("--state") { IsRequired = true };
var countryOption = new Option<string>("--country") { IsRequired = true };

command.AddOption(nameOption);
command.AddOption(emailOption);
command.AddOption(stateOption);
command.AddOption(countryOption);

command.SetHandler(
    handle: CosmosHandler.ManageCustomerAsync, 
    nameOption, 
    emailOption,
    stateOption,
    countryOption
);

await command.InvokeAsync(args);

    Catatan

    Untuk tutorial ini, tidak sepenuhnya penting bagi Anda untuk memahami cara kerja pengurai baris perintah. Pengurai memiliki empat opsi yang dapat ditentukan saat aplikasi berjalan. Tiga opsi diperlukan karena akan digunakan untuk membuat bidang kunci ID dan partisi.

  10. Pada titik ini, proyek tidak akan dibangun karena Anda belum menentukan metode statis CosmosHandler.ManageCustomerAsync .

  11. Simpan file Program.cs.

Menambahkan item ke kontainer menggunakan SDK

Selanjutnya, Anda menggunakan operasi individual untuk menambahkan item ke dalam API untuk kontainer NoSQL. Di bagian ini, Anda menentukan CosmosHandler.ManageCustomerAsync metode .

  1. Buat file CosmosHandler.cs baru.

  2. Dalam file CosmosHandler.cs, tambahkan baru menggunakan direktif untuk Humanizer namespace layanan dan Microsoft.Azure.Cosmos .

    using Humanizer;
using Microsoft.Azure.Cosmos;

  3. Buat kelas statis baru bernama CosmosHandler.

    public static class CosmosHandler
{ }

  4. Hanya untuk memvalidasi aplikasi ini berfungsi, buat implementasi singkat metode statis ManageCustomerAsync untuk mencetak input baris perintah.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    await Console.Out.WriteLineAsync($"Hello {name} of {state}, {country}!");
}

  5. Simpan file CosmosHandler.cs.

  6. Kembali ke terminal, jalankan aplikasi.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  7. Output perintah harus menjadi salam yang menyenangkan.

    Hello Mica Pereira of Washington, United States!

  8. Kembali ke file CosmosHandler.cs .

  9. Dalam kelas CosmosHandler statis, tambahkan anggota baru private static readonly jenis CosmosClient bernama _client.

    private static readonly CosmosClient _client;

  10. Buat konstruktor statis baru untuk kelas .CosmosHandler

    static CosmosHandler()
{ }

  11. Dalam konstruktor, buat instans CosmosClient baru kelas yang melewati dua parameter string dengan nilai URI dan KUNCI PRIMER yang sebelumnya Anda rekam di lab. Simpan instans baru ini di _client anggota.

    static CosmosHandler()
{
    _client = new CosmosClient(
        accountEndpoint: "<uri>", 
        authKeyOrResourceToken: "<primary-key>"
    );
}

  12. Kembali ke dalam kelas CosmosHandler statis, buat metode asinkron baru bernama GetContainerAsync yang mengembalikan Container.

    private static async Task<Container> GetContainerAsync()
{ }

  13. Untuk langkah berikutnya, tambahkan kode ini dalam GetContainerAsync metode .

    1. cosmicworks Dapatkan database dan simpan dalam variabel bernama database.

      Database database = _client.GetDatabase("cosmicworks");

    2. Buat generik List<> string nilai baru dalam daftar jalur kunci partisi hierarkis dan simpan dalam variabel bernama keyPaths.

      List<string> keyPaths = new()
{
    "/address/country",
    "/address/state"
};

    3. Buat variabel baru ContainerProperties dengan nama kontainer (customers) dan daftar jalur kunci partisi.

      ContainerProperties properties = new(
    id: "customers",
    partitionKeyPaths: keyPaths
);

    4. CreateContainerIfNotExistsAsync Gunakan metode untuk menyediakan properti kontainer dan mengambil kontainer. Metode ini akan, sesuai nama, secara asinkron membuat kontainer jika belum ada dalam database. Mengembalikan hasil sebagai output metode GetContainerAsync .

      return await database.CreateContainerIfNotExistsAsync(
    containerProperties: properties
);

  14. Hapus semua kode dalam ManageCustomerAsync metode .

  15. Untuk langkah berikutnya, tambahkan kode ini dalam ManageCustomerAsync metode .

    1. Secara asinkron memanggil GetContainerAsync metode dan menyimpan hasilnya dalam variabel bernama container.

      Container container = await GetContainerAsync();

    2. Buat variabel baru bernama id yang menggunakan Kebaberize metode dari Humanizer untuk mengubah name parameter metode.

      string id = name.Kebaberize();

      Catatan

      Metode ini Kebaberize akan mengganti semua spasi dengan tanda hubung dan mengkonversi teks menjadi huruf kecil.

    3. Buat item berjenis anonim baru menggunakan nameparameter metode , state, dan country dan dan id variabel . Simpan item sebagai variabel bernama customer.

      var customer = new {
    id = id,
    name = name,
    address = new {
        state = state,
        country = country
    }
};

    4. Gunakan metode asinkron CreateItemAsync kontainer untuk membuat item baru dalam kontainer dan menetapkan metadata respons HTTP ke variabel bernama response.

      var response = await container.CreateItemAsync(customer);

    5. Tulis nilai response variabel StatusCode dan RequestCharge properti ke konsol. Tulis juga nilai id variabel.

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  16. Simpan file CosmosHandler.cs.

  17. Kembali ke terminal, jalankan aplikasi lagi.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  18. Output perintah harus menyertakan status dan biaya permintaan untuk operasi.

    [Created]       mica-pereira    7.05 RUs

    Catatan

    Biaya permintaan Anda dapat bervariasi.

  19. Jalankan aplikasi sekali lagi.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  20. Kali ini, program akan mengalami crash. Jika Anda menggulir pesan kesalahan, Anda akan melihat crash terjadi karena konflik dalam pengidentifikasi unik untuk item.

    Unhandled exception: Microsoft.Azure.Cosmos.CosmosException : Response status code does not indicate success: Conflict (409);Reason: (
    Errors : [
      "Resource with specified id or name already exists."
    ]
);

Mengambil item menggunakan SDK

Setelah membuat item pertama dalam kontainer, Anda dapat menggunakan SDK yang sama untuk mengambil item. Di sini, Anda akan mengkueri dan membaca item untuk membandingkan perbedaan konsumsi unit permintaan (RU).

  1. Kembali ke atau buka file CosmosHandler.cs .

  2. Hapus semua baris kode dari ManageCustomerAsync metode kecuali untuk dua baris pertama.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

  3. Untuk langkah berikutnya, tambahkan kode ini dalam ManageCustomerAsync metode .

    1. Gunakan metode asinkron CreateItemAsync kontainer untuk membuat item baru dalam kontainer dan menetapkan metadata respons HTTP ke variabel bernama response.

      var response = await container.CreateItemAsync(customer);

    2. Buat string baru bernama sql dengan kueri SQL untuk mengambil item tempat filter (@id) cocok.

      string sql = @"
SELECT
    *
FROM customers c
WHERE c.id = @id
";

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

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

    4. 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 var feed = container.GetItemQueryIterator<dynamic>(
    queryDefinition: query
);

    5. Secara asinkron memanggil ReadNextAsync metode feed variabel dan menyimpan hasilnya dalam variabel bernama response.

      var response = await feed.ReadNextAsync();

    6. Tulis nilai response variabel StatusCode dan RequestCharge properti ke konsol. Tulis juga nilai id variabel.

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  4. Simpan file CosmosHandler.cs.

  5. Kembali ke terminal, jalankan aplikasi untuk membaca item tunggal menggunakan kueri SQL.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  6. Output perintah harus menunjukkan bahwa kueri memerlukan beberapa unit permintaan (RU).

    [OK]    mica-pereira    2.82 RUs

  7. Kembali ke file CosmosHandler.cs , hapus semua baris kode dari ManageCustomerAsync metode lagi kecuali untuk dua baris pertama.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

  8. Untuk langkah berikutnya, tambahkan kode ini dalam ManageCustomerAsync metode .

    1. Buat instans PartitionKeyBuilder baru dengan menambahkan state parameter dan country sebagai nilai kunci multi-partisi.

      var partitionKey = new PartitionKeyBuilder()
    .Add(country)
    .Add(state)
    .Build();

    2. Gunakan metode kontainer ReadItemAsync<> untuk mengarahkan baca item dari kontainer menggunakan id variabel dan partitionKey . Simpan hasilnya dalam variabel bernama response.

      var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);

    3. Tulis nilai response variabel StatusCode dan RequestCharge properti ke konsol. Tulis juga nilai id variabel.

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RU");

  9. Simpan file CosmosHandler.cs lagi.

  10. Kembali ke terminal, jalankan aplikasi sekali lagi untuk mengarahkan baca item tunggal.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  11. Output perintah harus menunjukkan bahwa kueri memerlukan satu RU.

    [OK]    mica-pereira    1 RUs

Membuat transaksi menggunakan SDK

Terakhir, Anda mengambil item yang Anda buat, membaca item tersebut, dan membuat item terkait yang berbeda sebagai bagian dari satu transaksi menggunakan Azure SDK untuk .NET.

  1. Kembali ke atau buka file CosmosHandler.cs .

  2. Hapus baris kode ini dari ManageCustomerAsync metode .

    var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);

Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  3. Untuk langkah berikutnya, tambahkan kode baru ini dalam ManageCustomerAsync metode .

    1. Buat item berjenis anonim baru menggunakan nameparameter metode , state, dan country dan dan id variabel . Simpan item sebagai variabel bernama customerCart. Item ini mewakili kelir belanja real-time untuk pelanggan yang saat ini kosong.

      var customerCart = new {
    id = $"{Guid.NewGuid()}",
    customerId = id,
    items = new string[] {},
    address = new {
        state = state,
        country = country
    }
};

    2. Buat item berjenis anonim baru lainnya menggunakan nameparameter metode , state, dan country dan dan id variabel . Simpan item sebagai variabel bernama customerCart. Item ini mewakili pengiriman dan informasi kontak untuk pelanggan.

      var customerContactInfo = new {
    id = $"{id}-contact",
    customerId = id,
    email = email,
    location = $"{state}, {country}",
    address = new {
        state = state,
        country = country
    }
};

    3. Buat batch baru menggunakan metode kontainer CreateTransactionalBatch yang melewati partitionKey variabel. Simpan batch dalam variabel bernama batch. Gunakan metode fasih untuk melakukan tindakan berikut:

      Metode Parameter
      ReadItem id variabel string
      CreateItem customerCart variabel jenis anonim
      CreateItem customerContactInfo variabel jenis anonim 
      var batch = container.CreateTransactionalBatch(partitionKey)
    .ReadItem(id)
    .CreateItem(customerCart)
    .CreateItem(customerContactInfo);

    4. Gunakan metode batch ExecuteAsync untuk memulai transaksi. Simpan hasilnya dalam variabel bernama response.

      using var response = await batch.ExecuteAsync();

    5. Tulis nilai response variabel StatusCode dan RequestCharge properti ke konsol. Tulis juga nilai id variabel.

      Console.WriteLine($"[{response.StatusCode}]\t{response.RequestCharge} RUs");

  4. Simpan file CosmosHandler.cs lagi.

  5. Kembali ke terminal, jalankan aplikasi sekali lagi untuk mengarahkan baca item tunggal.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  6. Output perintah harus menunjukkan unit permintaan yang digunakan untuk seluruh transaksi.

    [OK]    16.05 RUs

    Catatan

    Biaya permintaan Anda dapat bervariasi.

Memvalidasi data akhir di Data Explorer

Untuk membungkus hal-hal, Anda menggunakan Data Explorer di portal Azure untuk melihat data, dan kontainer yang Anda buat dalam tutorial ini.

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

  2. Di menu sumber daya, pilih Data Explorer.

    Cuplikan layar opsi Data Explorer disorot di menu sumber daya.

  3. Pada halaman Data Explorer , perluas cosmicworks database, lalu pilih customers kontainer.

    Cuplikan layar simpul kontainer yang dipilih dalam simpul database.

  4. Di bilah perintah, pilih Kueri SQL baru.

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

  5. Di editor kueri, amati string kueri SQL ini.

    SELECT * FROM c

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

    Cuplikan layar opsi 'Jalankan Kueri' di bilah perintah Data Explorer.

  7. Hasilnya harus mencakup array JSON dengan tiga item yang dibuat dalam tutorial ini. Amati bahwa semua item memiliki nilai kunci partisi hierarkis yang sama, tetapi bidang ID unik. Contoh output yang disertakan dipotong untuk brevity.

    [
  {
    "id": "mica-pereira",
    "name": "Mica Pereira",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "33d03318-6302-4559-b5c0-f3cc643b2f38",
    "customerId": "mica-pereira",
    "items": [],
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "mica-pereira-contact",
    "customerId": "mica-pereira",
    "email": null,
    "location": "Washington, United States",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  }
]

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.