Bagikan melalui

Menggunakan Database Dokumen Azure Cosmos DB di Xamarin.Forms

  • Artikel

Database dokumen Azure Cosmos DB adalah database NoSQL yang menyediakan akses latensi rendah ke dokumen JSON, menawarkan layanan database yang cepat, sangat tersedia, dan dapat diskalakan untuk aplikasi yang memerlukan skala mulus dan replikasi global. Artikel ini menjelaskan cara menggunakan pustaka klien Azure Cosmos DB .NET Standard untuk mengintegrasikan database dokumen Azure Cosmos DB ke dalam aplikasi Xamarin.Forms .

Video Microsoft Azure Cosmos DB

Akun database dokumen Azure Cosmos DB dapat disediakan menggunakan langganan Azure. Setiap akun database dapat memiliki nol atau lebih database. Database dokumen di Azure Cosmos DB adalah kontainer logis untuk koleksi dan pengguna dokumen.

Database dokumen Azure Cosmos DB mungkin berisi nol atau lebih koleksi dokumen. Setiap koleksi dokumen dapat memiliki tingkat performa yang berbeda, memungkinkan lebih banyak throughput ditentukan untuk koleksi yang sering diakses, dan lebih sedikit throughput untuk koleksi yang jarang diakses.

Setiap koleksi dokumen terdiri dari nol atau lebih dokumen JSON. Dokumen dalam koleksi bebas skema, jadi tidak perlu berbagi struktur atau bidang yang sama. Saat dokumen ditambahkan ke koleksi dokumen, Azure Cosmos DB secara otomatis mengindeksnya dan tersedia untuk dikueri.

Untuk tujuan pengembangan, database dokumen juga dapat digunakan melalui emulator. Dengan menggunakan emulator, aplikasi dapat dikembangkan dan diuji secara lokal, tanpa membuat langganan Azure atau menimbulkan biaya apa pun. Untuk informasi selengkapnya tentang emulator, lihat Mengembangkan secara lokal dengan Emulator Azure Cosmos DB.

Artikel ini, dan aplikasi sampel yang menyertainya, menunjukkan aplikasi daftar Todo tempat tugas disimpan dalam database dokumen Azure Cosmos DB. Untuk informasi selengkapnya tentang aplikasi sampel, lihat Memahami sampel.

Untuk informasi selengkapnya tentang Azure Cosmos DB, lihat Dokumentasi Azure Cosmos DB.

Catatan

Jika Anda tidak memiliki langganan Azure, buatlah akun gratis sebelum Anda memulai.

Siapkan

Proses untuk mengintegrasikan database dokumen Azure Cosmos DB ke dalam aplikasi Xamarin.Forms adalah sebagai berikut:

  1. Membuat akun Azure Cosmos DB. Untuk informasi selengkapnya, lihat Membuat akun Azure Cosmos DB.
  2. Tambahkan paket NuGet pustaka klien Azure Cosmos DB .NET Standard ke proyek platform dalam Xamarin.Forms solusi.
  3. Tambahkan using direktif untuk Microsoft.Azure.Documentsnamespace layanan , Microsoft.Azure.Documents.Client, dan Microsoft.Azure.Documents.Linq ke kelas yang akan mengakses akun Azure Cosmos DB.

Setelah melakukan langkah-langkah ini, pustaka klien Azure Cosmos DB .NET Standard dapat digunakan untuk mengonfigurasi dan menjalankan permintaan terhadap database dokumen.

Catatan

Pustaka klien Azure Cosmos DB .NET Standard hanya dapat diinstal ke dalam proyek platform, dan bukan ke dalam proyek Pustaka Kelas Portabel (PCL). Oleh karena itu, aplikasi sampel adalah Proyek Akses Bersama (SAP) untuk menghindari duplikasi kode. Namun, DependencyService kelas dapat digunakan dalam proyek PCL untuk memanggil kode pustaka klien Azure Cosmos DB .NET Standard yang terkandung dalam proyek khusus platform.

Menggunakan akun Azure Cosmos DB

Jenis ini DocumentClient merangkum titik akhir, kredensial, dan kebijakan koneksi yang digunakan untuk mengakses akun Azure Cosmos DB, dan digunakan untuk mengonfigurasi dan menjalankan permintaan terhadap akun. Contoh kode berikut menunjukkan cara membuat instans kelas ini:

DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);

Azure Cosmos DB Uri dan kunci utama harus diberikan kepada DocumentClient konstruktor. Ini dapat diperoleh dari Portal Microsoft Azure. Untuk informasi selengkapnya, lihat Koneksi ke akun Azure Cosmos DB.

Membuat Database

Database dokumen adalah kontainer logis untuk koleksi dokumen dan pengguna, dan dapat dibuat di Portal Microsoft Azure, atau secara terprogram menggunakan DocumentClient.CreateDatabaseIfNotExistsAsync metode :

public async Task CreateDatabase(string databaseName)
{
  ...
  await client.CreateDatabaseIfNotExistsAsync(new Database
  {
    Id = databaseName
  });
  ...
}

Metode CreateDatabaseIfNotExistsAsync menentukan Database objek sebagai argumen, dengan Database objek yang menentukan nama database sebagai propertinya Id . Metode CreateDatabaseIfNotExistsAsync membuat database jika tidak ada, atau mengembalikan database jika sudah ada. Namun, aplikasi sampel mengabaikan data apa pun yang CreateDatabaseIfNotExistsAsync dikembalikan oleh metode .

Catatan

Metode CreateDatabaseIfNotExistsAsync mengembalikan Task<ResourceResponse<Database>> objek, dan kode status respons dapat diperiksa untuk menentukan apakah database dibuat, atau database yang sudah ada dikembalikan.

Membuat Koleksi Dokumen

Koleksi dokumen adalah kontainer untuk dokumen JSON, dan dapat dibuat di Portal Microsoft Azure, atau secara terprogram menggunakan DocumentClient.CreateDocumentCollectionIfNotExistsAsync metode :

public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
  ...
  // Create collection with 400 RU/s
  await client.CreateDocumentCollectionIfNotExistsAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    new DocumentCollection
    {
      Id = collectionName
    },
    new RequestOptions
    {
      OfferThroughput = 400
    });
  ...
}

Metode ini CreateDocumentCollectionIfNotExistsAsync memerlukan dua argumen wajib – nama database yang ditentukan sebagai Uri, dan DocumentCollection objek. Objek DocumentCollection mewakili kumpulan dokumen yang namanya ditentukan dengan Id properti . Metode CreateDocumentCollectionIfNotExistsAsync membuat kumpulan dokumen jika tidak ada, atau mengembalikan kumpulan dokumen jika sudah ada. Namun, aplikasi sampel mengabaikan data apa pun yang CreateDocumentCollectionIfNotExistsAsync dikembalikan oleh metode .

Catatan

Metode CreateDocumentCollectionIfNotExistsAsync mengembalikan Task<ResourceResponse<DocumentCollection>> objek, dan kode status respons dapat diperiksa untuk menentukan apakah kumpulan dokumen dibuat, atau kumpulan dokumen yang ada dikembalikan.

Secara opsional, metode ini CreateDocumentCollectionIfNotExistsAsync juga dapat menentukan RequestOptions objek, yang merangkum opsi yang dapat ditentukan untuk permintaan yang dikeluarkan ke akun Azure Cosmos DB. Properti RequestOptions.OfferThroughput digunakan untuk menentukan tingkat performa koleksi dokumen, dan dalam aplikasi sampel, diatur ke 400 unit permintaan per detik. Nilai ini harus ditingkatkan atau dikurangi tergantung pada apakah koleksi akan sering atau jarang diakses.

Penting

Perhatikan bahwa metode ini CreateDocumentCollectionIfNotExistsAsync akan membuat koleksi baru dengan throughput yang dipesan, yang memiliki implikasi harga.

Mengambil Dokumen Kumpulan Dokumen

Konten kumpulan dokumen dapat diambil dengan membuat dan menjalankan kueri dokumen. Kueri dokumen dibuat dengan DocumentClient.CreateDocumentQuery metode :

public async Task<List<TodoItem>> GetTodoItemsAsync()
{
  ...
  var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
            .AsDocumentQuery();
  while (query.HasMoreResults)
  {
    Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
  }
  ...
}

Kueri ini secara asinkron mengambil semua dokumen dari koleksi yang ditentukan, dan menempatkan dokumen dalam List<TodoItem> koleksi untuk ditampilkan.

Metode CreateDocumentQuery<T> menentukan Uri argumen yang mewakili koleksi yang harus dikueri untuk dokumen. Dalam contoh ini, collectionLink variabel adalah bidang tingkat kelas yang menentukan Uri yang mewakili kumpulan dokumen untuk mengambil dokumen dari:

Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);

Metode CreateDocumentQuery<T> ini membuat kueri yang dijalankan secara sinkron, dan mengembalikan IQueryable<T> objek. Namun, metode mengonversi AsDocumentQueryIQueryable<T> objek menjadi IDocumentQuery<T> objek yang dapat dieksekusi secara asinkron. Kueri asinkron dijalankan dengan IDocumentQuery<T>.ExecuteNextAsync metode , yang mengambil halaman hasil berikutnya dari database dokumen, dengan IDocumentQuery<T>.HasMoreResults properti yang menunjukkan apakah ada hasil tambahan yang akan dikembalikan dari kueri.

Dokumen dapat difilter di sisi server dengan menyertakan Where klausul dalam kueri, yang menerapkan predikat pemfilteran ke kueri terhadap kumpulan dokumen:

var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
          .Where(f => f.Done != true)
          .AsDocumentQuery();

Kueri ini mengambil semua dokumen dari koleksi yang propertinya Done sama dengan false.

Menyisipkan Dokumen ke dalam Kumpulan Dokumen

Dokumen adalah konten JSON yang ditentukan pengguna, dan dapat disisipkan ke dalam kumpulan dokumen dengan DocumentClient.CreateDocumentAsync metode :

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.CreateDocumentAsync(collectionLink, item);
  ...
}

Metode CreateDocumentAsync menentukan Uri argumen yang mewakili kumpulan dokumen harus disisipkan, dan object argumen yang mewakili dokumen yang akan disisipkan.

Mengganti Dokumen dalam Kumpulan Dokumen

Dokumen dapat diganti dalam kumpulan dokumen dengan DocumentClient.ReplaceDocumentAsync metode :

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
  ...
}

Metode ReplaceDocumentAsync menentukan Uri argumen yang mewakili dokumen dalam koleksi yang harus diganti, dan object argumen yang mewakili data dokumen yang diperbarui.

Menghapus Dokumen dari Kumpulan Dokumen

Dokumen dapat dihapus dari kumpulan dokumen dengan DocumentClient.DeleteDocumentAsync metode :

public async Task DeleteTodoItemAsync(string id)
{
  ...
  await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
  ...
}

Metode DeleteDocumentAsync menentukan Uri argumen yang mewakili dokumen dalam koleksi yang harus dihapus.

Menghapus Kumpulan Dokumen

Kumpulan dokumen dapat dihapus dari database dengan DocumentClient.DeleteDocumentCollectionAsync metode :

await client.DeleteDocumentCollectionAsync(collectionLink);

Metode DeleteDocumentCollectionAsync menentukan Uri argumen yang mewakili kumpulan dokumen yang akan dihapus. Perhatikan bahwa memanggil metode ini juga akan menghapus dokumen yang disimpan dalam koleksi.

Menghapus Database

Database dapat dihapus dari akun database Azure Cosmos DB dengan metode :DocumentClient.DeleteDatabaesAsync

await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));

Metode DeleteDatabaseAsync menentukan Uri argumen yang mewakili database yang akan dihapus. Perhatikan bahwa memanggil metode ini juga akan menghapus koleksi dokumen yang disimpan dalam database, dan dokumen yang disimpan dalam koleksi dokumen.

Ringkasan

Artikel ini menjelaskan cara menggunakan pustaka klien Azure Cosmos DB .NET Standard untuk mengintegrasikan database dokumen Azure Cosmos DB ke dalam aplikasi Xamarin.Forms . Database dokumen Azure Cosmos DB adalah database NoSQL yang menyediakan akses latensi rendah ke dokumen JSON, menawarkan layanan database yang cepat, sangat tersedia, dan dapat diskalakan untuk aplikasi yang memerlukan skala mulus dan replikasi global.