içinde Azure Cosmos DB Belge Veritabanı kullanma Xamarin.Forms

Makale
07/13/2023

Azure Cosmos DB belge veritabanı, sorunsuz ölçeklendirme ve genel çoğaltma gerektiren uygulamalar için hızlı, yüksek oranda kullanılabilir, ölçeklenebilir bir veritabanı hizmeti sunan, JSON belgelerine düşük gecikme süreli erişim sağlayan bir NoSQL veritabanıdır. Bu makalede, Azure Cosmos DB belge veritabanını Xamarin.Forms bir uygulamayla tümleştirmek için Azure Cosmos DB .NET Standard istemci kitaplığının nasıl kullanılacağı açıklanmaktadır.

Microsoft Azure Cosmos DB videosu

Azure Cosmos DB belge veritabanı hesabı, Azure aboneliği kullanılarak sağlanabilir. Her veritabanı hesabının sıfır veya daha fazla veritabanı olabilir. Azure Cosmos DB'deki belge veritabanı, belge koleksiyonları ve kullanıcıları için mantıksal bir kapsayıcıdır.

Azure Cosmos DB belge veritabanı sıfır veya daha fazla belge koleksiyonu içerebilir. Her belge koleksiyonu farklı bir performans düzeyine sahip olabilir ve bu sayede sık erişilen koleksiyonlar için daha fazla aktarım hızı ve seyrek erişilen koleksiyonlar için daha az aktarım hızı belirtilebilir.

Her belge koleksiyonu sıfır veya daha fazla JSON belgeden oluşur. Koleksiyondaki belgeler şemasızdır ve bu nedenle aynı yapıyı veya alanları paylaşmanız gerekmez. Belgeler bir belge koleksiyonuna eklendikçe, Azure Cosmos DB bunları otomatik olarak dizine alır ve sorgulanabilir hale gelir.

Geliştirme amacıyla, bir belge veritabanı öykünücü aracılığıyla da kullanılabilir. Öykünücü kullanılarak uygulamalar, Azure aboneliği oluşturmadan veya herhangi bir maliyet olmadan yerel olarak geliştirilebilir ve test edilebilir. Öykünücü hakkında daha fazla bilgi için bkz . Azure Cosmos DB Öykünücüsü ile yerel olarak geliştirme.

Bu makalede ve örnek uygulamayla birlikte, görevlerin Azure Cosmos DB belge veritabanında depolandığı bir Yapılacaklar listesi uygulaması gösterilmektedir. Örnek uygulama hakkında daha fazla bilgi için bkz . Örneği anlama.

Azure Cosmos DB hakkında daha fazla bilgi için bkz . Azure Cosmos DB Belgeleri.

Not

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Ayarlama

Azure Cosmos DB belge veritabanını bir Xamarin.Forms uygulamayla tümleştirme işlemi aşağıdaki gibidir:

Bir Azure Cosmos DB hesabı oluşturun. Daha fazla bilgi için bkz . Azure Cosmos DB hesabı oluşturma.
Çözümdeki platform projelerine Xamarin.Forms Azure Cosmos DB .NET Standard istemci kitaplığı NuGet paketini ekleyin.
Azure Cosmos DB hesabına erişecek sınıflara , ve Microsoft.Azure.Documents.Linq ad alanları için Microsoft.Azure.Documentsyönergeler ekleyinusing. Microsoft.Azure.Documents.Client

Bu adımlar gerçekleştirildikten sonra Azure Cosmos DB .NET Standart istemci kitaplığı, istekleri belge veritabanında yapılandırmak ve yürütmek için kullanılabilir.

Not

Azure Cosmos DB .NET Standart istemci kitaplığı yalnızca platform projelerine yüklenebilir, Taşınabilir Sınıf Kitaplığı (PCL) projesine yüklenemez. Bu nedenle örnek uygulama, kod yinelemesini önlemek için paylaşılan erişim projesidir (SAP). Ancak sınıfı, platforma DependencyService özgü projelerde yer alan Azure Cosmos DB .NET Standart istemci kitaplığı kodunu çağırmak için bir PCL projesinde kullanılabilir.

Azure Cosmos DB hesabını kullanma

Türü DocumentClient , Azure Cosmos DB hesabına erişmek için kullanılan uç nokta, kimlik bilgileri ve bağlantı ilkesini kapsüller ve hesaba yönelik istekleri yapılandırmak ve yürütmek için kullanılır. Aşağıdaki kod örneği, bu sınıfın bir örneğinin nasıl oluşturulacağını gösterir:

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

Oluşturucuya Azure Cosmos DB Uri'si ve birincil anahtar sağlanmalıdır DocumentClient . Bunlar Azure Portal'dan alınabilir. Daha fazla bilgi için bkz. Azure Cosmos DB hesabına Bağlan.

Veritabanı Oluşturma

Belge veritabanı, belge koleksiyonları ve kullanıcılar için mantıksal bir kapsayıcıdır ve Azure Portal'da veya programlama yoluyla şu yöntem kullanılarak DocumentClient.CreateDatabaseIfNotExistsAsync oluşturulabilir:

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

CreateDatabaseIfNotExistsAsync yöntemi bir Database nesneyi bağımsız değişken olarak belirtir ve Database nesnesi veritabanı adını özelliği olarak Id belirtir. CreateDatabaseIfNotExistsAsync yöntemi, yoksa veritabanını oluşturur veya zaten varsa veritabanını döndürür. Ancak, örnek uygulama yöntemi tarafından CreateDatabaseIfNotExistsAsync döndürülen tüm verileri yoksayar.

Not

CreateDatabaseIfNotExistsAsync yöntemi bir Task<ResourceResponse<Database>> nesne döndürür ve yanıtın durum kodu, veritabanının oluşturulup oluşturulmadığını veya var olan bir veritabanının döndürüleceğini belirlemek için denetlenebilir.

Belge Koleksiyonu Oluşturma

Belge koleksiyonu, JSON belgeleri için bir kapsayıcıdır ve Azure Portal'da veya program aracılığıyla şu yöntem kullanılarak DocumentClient.CreateDocumentCollectionIfNotExistsAsync oluşturulabilir:

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

CreateDocumentCollectionIfNotExistsAsync yöntemi iki zorunlu bağımsız değişken gerektirir: veritabanı adı olarak belirtilen bir Uriveritabanı adı ve bir DocumentCollection nesne. DocumentCollection nesnesi, adı özelliğiyle Id belirtilen bir belge koleksiyonunu temsil eder. CreateDocumentCollectionIfNotExistsAsync yöntemi, yoksa belge koleksiyonunu oluşturur veya zaten varsa belge koleksiyonunu döndürür. Ancak, örnek uygulama yöntemi tarafından CreateDocumentCollectionIfNotExistsAsync döndürülen tüm verileri yoksayar.

Not

CreateDocumentCollectionIfNotExistsAsync yöntemi bir Task<ResourceResponse<DocumentCollection>> nesne döndürür ve yanıtın durum kodu, belge koleksiyonunun oluşturulup oluşturulmadığını veya var olan bir belge koleksiyonunun döndürüleceğini belirlemek için denetlenebilir.

İsteğe bağlı olarak yöntemi CreateDocumentCollectionIfNotExistsAsync , Azure Cosmos DB hesabına gönderilen istekler için belirtilebilen seçenekleri kapsülleyen bir RequestOptions nesnesi de belirtebilir. RequestOptions.OfferThroughput özelliği, belge koleksiyonunun performans düzeyini tanımlamak için kullanılır ve örnek uygulamada saniyede 400 istek birimine ayarlanır. Bu değer, koleksiyona sık veya seyrek erişilip erişilmeyeceğine bağlı olarak artırılmalıdır veya azaltılmalıdır.

Önemli

yönteminin CreateDocumentCollectionIfNotExistsAsync ayrılmış aktarım hızına sahip yeni bir koleksiyon oluşturacağını ve bunun fiyatlandırma açısından etkileri olduğunu unutmayın.

Belge Koleksiyonu Belgelerini Alma

Belge sorgusu oluşturulup yürütülerek bir belge koleksiyonunun içeriği alınabilir. Yöntemiyle DocumentClient.CreateDocumentQuery bir belge sorgusu oluşturulur:

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

Bu sorgu, belirtilen koleksiyondaki tüm belgeleri zaman uyumsuz olarak alır ve görüntülemek üzere bir List<TodoItem> koleksiyona yerleştirir.

yöntemi, CreateDocumentQuery<T> belgeler için sorgulanması gereken koleksiyonu temsil eden bir Uri bağımsız değişken belirtir. Bu örnekte değişken, collectionLink aşağıdakilerden belge alınacak belge koleksiyonunu temsil eden öğesini belirten Uri sınıf düzeyinde bir alandır:

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

CreateDocumentQuery<T> yöntemi, zaman uyumlu olarak yürütülen bir sorgu oluşturur ve bir IQueryable<T> nesne döndürür. Ancak yöntemi, AsDocumentQuery nesnesini zaman uyumsuz olarak yürütülebilen bir IDocumentQuery<T> nesneye dönüştürürIQueryable<T>. Zaman uyumsuz sorgu, belge veritabanından bir sonraki sonuç sayfasını alan yöntemiyle IDocumentQuery<T>.ExecuteNextAsyncIDocumentQuery<T>.HasMoreResults yürütülür ve özelliği sorgudan döndürülecek ek sonuçlar olup olmadığını gösterir.

Belgeler, sorguya bir Where yan tümcesi eklenerek sunucu tarafından filtrelenebilir ve bu da sorguya belge koleksiyonuna yönelik bir filtreleme koşulu uygular:

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

Bu sorgu, özelliği değerine eşit falseolan Done koleksiyondaki tüm belgeleri alır.

Belge Koleksiyonuna Belge Ekleme

Belgeler kullanıcı tanımlı JSON içeriğidir ve şu yöntemle bir belge koleksiyonuna DocumentClient.CreateDocumentAsync eklenebilir:

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

yöntemi, CreateDocumentAsync belgenin eklenmesi gereken koleksiyonu temsil eden bir Uri bağımsız değişken ve eklenecek belgeyi temsil eden bir object bağımsız değişken belirtir.

Belge Koleksiyonundaki Bir Belgeyi Değiştirme

Belge koleksiyonundaki belgeler şu yöntemle DocumentClient.ReplaceDocumentAsync değiştirilebilir:

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

ReplaceDocumentAsync yöntemi, değiştirilmesi gereken koleksiyondaki belgeyi temsil eden bir Uri bağımsız değişken ve güncelleştirilmiş belge verilerini temsil eden bir object bağımsız değişken belirtir.

Belge Koleksiyonundan Belge Silme

Bir belge, şu yöntemle DocumentClient.DeleteDocumentAsync belge koleksiyonundan silinebilir:

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

yöntemi, DeleteDocumentAsync silinmesi gereken koleksiyondaki belgeyi temsil eden bir Uri bağımsız değişken belirtir.

Belge Koleksiyonunu Silme

Bir belge koleksiyonu veritabanından DocumentClient.DeleteDocumentCollectionAsync şu yöntemle silinebilir:

await client.DeleteDocumentCollectionAsync(collectionLink);

yöntemi, DeleteDocumentCollectionAsync silinecek belge koleksiyonunu temsil eden bir Uri bağımsız değişken belirtir. Bu yöntemi çağırmanın koleksiyonda depolanan belgeleri de sileceğini unutmayın.

Veritabanı Silme

Bir veritabanı Azure Cosmos DB veritabanı hesabından DocumentClient.DeleteDatabaesAsync şu yöntemle silinebilir:

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

yöntemi, DeleteDatabaseAsync silinecek veritabanını temsil eden bir Uri bağımsız değişken belirtir. Bu yöntemi çağırmanın veritabanında depolanan belge koleksiyonlarını ve belge koleksiyonlarında depolanan belgeleri de sileceğini unutmayın.

Özet

Bu makalede, Azure Cosmos DB belge veritabanını Xamarin.Forms bir uygulamayla tümleştirmek için Azure Cosmos DB .NET Standard istemci kitaplığının nasıl kullanılacağı açıklanmıştır. Azure Cosmos DB belge veritabanı, sorunsuz ölçeklendirme ve genel çoğaltma gerektiren uygulamalar için hızlı, yüksek oranda kullanılabilir, ölçeklenebilir bir veritabanı hizmeti sunan, JSON belgelerine düşük gecikme süreli erişim sağlayan bir NoSQL veritabanıdır.