Öğretici: NoSQL için Azure Cosmos DB ile .NET konsol uygulaması geliştirme

Makale
06/01/2023

UYGULANANLAR: NoSQL

.NET

.NET için Azure SDK, NoSQL kapsayıcısı için bir API'ye zaman uyumsuz tek tek işlemler veya işlem toplu işlemi eklemenizi sağlar. Bu öğreticide, kapsayıcıya birden çok öğe ekleyen yeni bir .NET konsol uygulaması oluşturma işlemi izlenecektir.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

NoSQL için API kullanarak veritabanı oluşturma
.NET konsol uygulaması oluşturma ve .NET için Azure SDK'sını ekleme
NoSQL kapsayıcısı için BIR API'ye tek tek öğeler ekleme
NoSQL kapsayıcısı için API'den verimli öğeler alma
NoSQL kapsayıcısı için API'ye yönelik toplu değişikliklerle işlem oluşturma

Önkoşullar

Mevcut bir NoSQL için Azure Cosmos DB hesabı.
- Mevcut bir Azure aboneliğiniz varsa yeni bir hesap oluşturun.
- Azure aboneliği yok mu? Kredi kartı gerektirmeden Azure Cosmos DB'i ücretsiz deneyebilirsiniz.
Visual Studio Code
.NET 6 (LTS) veya üzeri
C# uygulamaları yazma deneyimi.

NoSQL kaynakları için API oluşturma

İlk olarak, NoSQL hesabı için mevcut API'de boş bir veritabanı oluşturun. Daha sonra .NET için Azure SDK'sını kullanarak bir kapsayıcı oluşturacaksınız.

Azure portalında mevcut NoSQL hesabı API'nize gidin.
Kaynak menüsünde Anahtarlar'ı seçin.
Anahtarlar sayfasında URI ve BİRİnCİl ANAHTAR alanlarının değerini gözlemleyin ve kaydedin. Bu değerler öğretici boyunca kullanılacaktır.
Kaynak menüsünde Veri Gezgini'ı seçin.
Veri Gezgini sayfasında, komut çubuğundaKi Yeni Veritabanı seçeneğini belirleyin.
Yeni Veritabanı iletişim kutusunda aşağıdaki ayarlarla yeni bir kapsayıcı oluşturun:

Değer

Veritabanı kimliği cosmicworks

Veritabanı aktarım hızı türü El ile

Veritabanı aktarım hızı miktarı 400
Veritabanını oluşturmak için Tamam'ı seçin.

	Değer
Veritabanı kimliği	`cosmicworks`
Veritabanı aktarım hızı türü	El ile
Veritabanı aktarım hızı miktarı	`400`

.NET konsol uygulaması oluşturma

Şimdi yeni bir .NET konsol uygulaması oluşturacak ve NuGet kitaplığını kullanarak .NET için Azure SDK'sını Microsoft.Azure.Cosmos içeri aktaracaksınız.

Boş bir dizinde bir terminal açın.
Yerleşik şablonu kullanarak console yeni bir konsol uygulaması oluşturma
```
dotnet new console --langVersion preview
```
NuGet'ten paketin 3.31.1-preview sürümünü Microsoft.Azure.Cosmos ekleyin.
```
dotnet add package Microsoft.Azure.Cosmos --version 3.31.1-preview
```
Ayrıca, NuGet'ten paketin System.CommandLine yayın öncesi sürümünü ekleyin.
```
dotnet add package System.CommandLine --prerelease
```
Ayrıca NuGet'ten Humanizer paketi ekleyin.
```
dotnet add package Humanizer
```
Konsol uygulaması projesini oluşturun.
```
dotnet build
```
Çalışma alanı olarak geçerli proje klasörünü kullanarak Visual Studio Code'yu açın.

Bahşiş

Terminalde çalıştırarak code . Visual Studio Code'u açabilir ve çalışma dizinini otomatik olarak geçerli çalışma alanı olarak açabilirsiniz.
Program.cs dosyasına gidin ve dosyasını açın. Dosyadaki mevcut kodun tümünü silin.

Ve --last seçenekleri aracılığıyla geçirilen iki dize için komut satırını ayrıştırmak üzere System.CommandLine kitaplığını kullanmak üzere bu kodu dosyaya --first ekleyin.

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

Dekont

Bu öğreticide, komut satırı ayrıştırıcısının nasıl çalıştığını anlamanız tamamen önemli değildir. Ayrıştırıcı, uygulama çalışırken belirtilebilen dört seçeneğe sahiptir. Kimlik ve bölüm anahtarı alanlarını oluşturmak için kullanılacakları için seçeneklerden üçü gereklidir.

Bu noktada, statik CosmosHandler.ManageCustomerAsync yöntemi henüz tanımlamadığınız için proje derlenmez.
Program.cs dosyasını kaydedin.

SDK kullanarak kapsayıcıya öğe ekleme

Ardından, NoSQL kapsayıcısı için API'ye öğe eklemek için tek tek işlemleri kullanacaksınız. Bu bölümde yöntemini tanımlayacaksınız CosmosHandler.ManageCustomerAsync .

Yeni bir CosmosHandler.cs dosyası oluşturun.
CosmosHandler.cs dosyasında ve Microsoft.Azure.Cosmos ad alanları için Humanizer yeni bir using yönergesi ekleyin.
```
using Humanizer;
using Microsoft.Azure.Cosmos;
```
adlı CosmosHandleryeni bir statik sınıf oluşturun.
```
public static class CosmosHandler
{ }
```

Bu uygulamanın işe yarayacağını doğrulamak için, komut satırı girişini yazdırmak için statik ManageCustomerAsync yöntemin kısa bir uygulamasını oluşturun.

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

CosmosHandler.cs dosyasını kaydedin.

Terminale geri dönüp uygulamayı çalıştırın.

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

Komutun çıkışı eğlenceli bir karşılama olmalıdır.
```
Hello Mica Pereira of Washington, United States!
```
CosmosHandler.cs dosyasına dönün.
Statik CosmosHandler sınıfı içinde adlı _clienttüründe CosmosClient yeni private static readonly bir üye ekleyin.
```
private static readonly CosmosClient _client;
```
sınıfı için CosmosHandler yeni bir statik oluşturucu oluşturun.
```
static CosmosHandler()
{ }
```
Oluşturucu içinde, daha önce laboratuvarda CosmosClient kaydettiğiniz URI ve BİRİnCİl ANAHTAR değerleriyle iki dize parametresini geçirerek sınıfın yeni bir örneğini oluşturun. Bu yeni örneği üyede depolayın _client .
```
static CosmosHandler()
{
    _client = new CosmosClient(
        accountEndpoint: "<uri>", 
        authKeyOrResourceToken: "<primary-key>"
    );
}
```
Statik CosmosHandler sınıfına geri dönüp adlı yeni bir zaman uyumsuz yöntem GetContainerAsync oluşturun.Container
```
private static async Task<Container> GetContainer()
{ }
```
Sonraki adımlar için bu kodu yöntemine GetContainerAsync ekleyin.
1. cosmicworks Veritabanını alın ve adlı databasebir değişkende depolayın.
```
Database database = _client.GetDatabase("cosmicworks");
```
2. Hiyerarşik bölüm anahtarı yolları listesinde yeni bir değer geneli List<>string oluşturun ve adlı keyPathsbir değişkende depolayın.
```
List<string> keyPaths = new()
{
    "/address/country",
    "/address/state"
};
```
3. Kapsayıcı adı (customers) ve bölüm anahtarı yolları listesiyle yeni ContainerProperties bir değişken oluşturun.
```
ContainerProperties properties = new(
    id: "customers",
    partitionKeyPaths: keyPaths
);
```
4. CreateContainerIfNotExistsAsync Kapsayıcı özelliklerini sağlamak ve kapsayıcıyı almak için yöntemini kullanın. Bu yöntem, veritabanında zaten yoksa, ad başına kapsayıcıyı zaman uyumsuz olarak oluşturur. Sonucu yöntemin çıktısı GetContainerAsync olarak döndürür.
```
return await database.CreateContainerIfNotExistsAsync(
    containerProperties: properties
);
```
yöntemindeki tüm kodu ManageCustomerAsync silin.
Sonraki adımlar için bu kodu yöntemine ManageCustomerAsync ekleyin.
1. yöntemini zaman uyumsuz olarak çağırın GetContainerAsync ve sonucu adlı containerbir değişkende depolayın.
```
Container container = await GetContainerAsync();
```
2. Yöntem parametresini Kebaberize dönüştürmek name için Humanizer yöntemini kullanan adlı id yeni bir değişken oluşturun.
```
string id = name.Kebaberize();
```
  Dekont
  
  Kebaberize yöntemi, tüm boşlukları kısa çizgilerle değiştirir ve metni küçük harfle yakınsar.
3. , , stateve yöntem parametrelerini ve country değişkenini nameid kullanarak yeni bir anonim türlenmiş öğe oluşturun. Öğeyi adlı customerbir değişken olarak depolayın.
```
var customer = new {
    id = id,
    name = name,
    address = new {
        state = state,
        country = country
    }
};
```
4. Kapsayıcıda yeni bir öğe oluşturmak ve HTTP yanıt meta verilerini adlı responsebir değişkene atamak için kapsayıcının zaman uyumsuz CreateItemAsync yöntemini kullanın.
```
var response = await container.CreateItemAsync(customer);
```
5. Değişkenin responseStatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
```
CosmosHandler.cs dosyasını kaydedin.

Terminale geri dönüp uygulamayı yeniden çalıştırın.

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

Komutun çıktısı işlem için bir durum ve istek ücreti içermelidir.
```
[Created]       mica-pereira    7.05 RUs
```
Dekont

İstek ücretiniz farklılık gösterebilir.

Uygulamayı bir kez daha çalıştırın.

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

Bu kez program kilitlenmelidir. Hata iletisini kaydırdığınızda, kilitlenmenin öğelerin benzersiz tanımlayıcısında bir çakışma nedeniyle oluştuğunı görürsünüz.

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."
    ]
);

SDK kullanarak öğe alma

Kapsayıcıda ilk öğenizi oluşturduğunuza göre, öğeyi almak için aynı SDK'yı kullanabilirsiniz. Burada, istek birimi (RU) tüketimindeki farkı karşılaştırmak için öğeyi sorgulayıp nokta okuması yapacaksınız.

CosmosHandler.cs dosyasına dönün veya dosyayı açın.

yöntemden ManageCustomerAsync ilk iki satır dışındaki tüm kod satırlarını silin.

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

    string id = name.Kebaberize();
}

Sonraki adımlar için bu kodu yöntemine ManageCustomerAsync ekleyin.
1. Kapsayıcıda yeni bir öğe oluşturmak ve HTTP yanıt meta verilerini adlı responsebir değişkene atamak için kapsayıcının zaman uyumsuz CreateItemAsync yöntemini kullanın.
```
var response = await container.CreateItemAsync(customer);
```
2. Bir filtrenin (@id) eşleştiği öğeleri almak için SQL sorgusuyla adlı sql yeni bir dize oluşturun.
```
string sql = """
SELECT
    *
FROM customers c
WHERE c.id = @id
""";
```
3. Dizeyi sql tek sorgu parametresi olarak geçirme adlı query yeni QueryDefinition bir değişken oluşturun. Ayrıca değişken değerini id@id parametreye uygulamak için akışkan yöntemini kullanınWithParameter.
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@id", id);
```
4. Azure Cosmos DB'den GetItemQueryIterator<> veri alan bir yineleyici oluşturmak için genel yöntemi ve query değişkenini kullanın. Yineleyiciyi adlı feedbir değişkende depolayın. Yineleyiciyi daha sonra atmak için bu ifadenin tamamını bir using deyimine sarmalayın.
```
using var feed = container.GetItemQueryIterator<dynamic>(
    queryDefinition: query
);
```
5. Zaman uyumsuz olarak değişkeninin ReadNextAsync yöntemini çağırın feed ve sonucu adlı responsebir değişkende depolayın.
```
var response = await feed.ReadNextAsync();
```
6. Değişkenin responseStatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
```
CosmosHandler.cs dosyasını kaydedin.
Terminale döndüğünüzde, sql sorgusu kullanarak tek öğeyi okumak için uygulamayı çalıştırın.
```
dotnet run -- --name 'Mica Pereira'
```
Komutun çıkışı, sorgunun birden çok RU gerektirdiğini göstermelidir.
```
[OK]    mica-pereira    2.82 RUs
```

CosmosHandler.cs dosyasına geri döndüğünüzde, ilk iki satır dışındaki tüm kod satırlarını yöntemden ManageCustomerAsync yeniden silin.

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

    string id = name.Kebaberize();
}

Sonraki adımlar için bu kodu yöntemine ManageCustomerAsync ekleyin.
1. ve country parametrelerini çok parçalı bölüm anahtarı değeri olarak ekleyerek state yeni bir örneği PartitionKeyBuilder oluşturun.
```
var partitionKey = new PartitionKeyBuilder()
    .Add(country)
    .Add(state)
    .Build();
```
2. ve partitionKey değişkenlerini kullanarak kapsayıcıdan ReadItemAsync<> öğeyi okumak için kapsayıcının id yöntemini kullanın. Sonucu adlı responsebir değişkene kaydedin.
```
var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);
```
3. Değişkenin responseStatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RU");
```
CosmosHandler.cs dosyasını yeniden kaydedin.
Terminale geri dönüp uygulamayı bir kez daha çalıştırarak tek öğeyi okumasını sağlayın.
```
dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
```
Komutun çıkışı, sorgunun tek bir RU gerektirdiğini göstermelidir.
```
[OK]    mica-pereira    1 RUs
```

SDK kullanarak işlem oluşturma

Son olarak oluşturduğunuz öğeyi alacak, bu öğeyi okuyacak ve .NET için Azure SDK'sını kullanarak tek bir işlemin parçası olarak farklı bir ilgili öğe oluşturacaksınız.

CosmosHandler.cs dosyasına dönün veya dosyayı açın.

Yönteminden bu kod satırlarını ManageCustomerAsync silin.

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

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

Sonraki adımlar için bu yeni kodu yöntemine ManageCustomerAsync ekleyin.
1. , , stateve yöntem parametrelerini ve country değişkenini nameid kullanarak yeni bir anonim türlenmiş öğe oluşturun. Öğeyi adlı customerCartbir değişken olarak depolayın. Bu öğe, şu anda boş olan müşteri için gerçek zamanlı bir alışveriş sepetini temsil eder.
```
var customerCart = new {
    id = $"{Guid.NewGuid()}",
    customerId = id,
    items = new string[] {},
    address = new {
        state = state,
        country = country
    }
};
```
2. , , stateve yöntem parametrelerini ve country değişkenini nameid kullanarak anonim olarak yazılan başka bir öğe oluşturun. Öğeyi adlı customerCartbir değişken olarak depolayın. Bu öğe, müşterinin sevkiyat ve iletişim bilgilerini temsil eder.
```
var customerContactInfo = new {
    id = $"{id}-contact",
    customerId = id,
    email = email,
    location = $"{state}, {country}",
    address = new {
        state = state,
        country = country
    }
};
```
3. Değişkenini geçirerek partitionKey kapsayıcının CreateTransactionalBatch yöntemini kullanarak yeni bir toplu iş oluşturun. Toplu işlemi adlı batchbir değişkende depolayın. Aşağıdaki eylemleri gerçekleştirmek için akıcı yöntemleri kullanın:
  
  Metot Parametre
  
  ReadItem id dize değişkeni
  
  CreateItem customerCart anonim tür değişkeni
  
  CreateItem customerContactInfo anonim tür değişkeni
```
var batch = container.CreateTransactionalBatch(partitionKey)
    .ReadItem(id)
    .CreateItem(customerCart)
    .CreateItem(customerContactInfo);
```
4. İşlemi başlatmak için toplu işlemin ExecuteAsync yöntemini kullanın. Sonucu adlı responsebir değişkene kaydedin.
```
using var response = await batch.ExecuteAsync();
```
5. Değişkenin responseStatusCode ve RequestCharge özelliklerinin değerlerini konsola yazın. Değişkenin değerini id de yazın.
```
Console.WriteLine($"[{response.StatusCode}]\t{response.RequestCharge} RUs");
```
CosmosHandler.cs dosyasını yeniden kaydedin.
Terminale geri dönüp uygulamayı bir kez daha çalıştırarak tek öğeyi okumasını sağlayın.
```
dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
```
Komutun çıktısı, işlemin tamamı için kullanılan istek birimlerini göstermelidir.
```
[OK]    16.05 RUs
```
Dekont

İstek ücretiniz farklılık gösterebilir.

Metot	Parametre
`ReadItem`	`id` dize değişkeni
`CreateItem`	`customerCart` anonim tür değişkeni
`CreateItem`	`customerContactInfo` anonim tür değişkeni

Veri Gezgini son verileri doğrulama

Öğeleri sarmak için Azure portalındaki Veri Gezgini kullanarak verileri ve bu öğreticide oluşturduğunuz kapsayıcıyı görüntüleyebilirsiniz.

Azure portalında mevcut NoSQL hesabı API'nize gidin.
Kaynak menüsünde Veri Gezgini'ı seçin.
Veri Gezgini sayfasında veritabanını genişletin cosmicworks ve kapsayıcıyı customers seçin.
Komut çubuğunda Yeni SQL sorgusu'nu seçin.
Sorgu düzenleyicisinde bu SQL sorgu dizesini inceleyin.
```
SELECT * FROM c
```
Sorguyu çalıştırmak ve sonuçları gözlemlemek için Sorguyu Yürüt'e tıklayın.

Sonuçlar, bu öğreticide oluşturulan üç öğeye sahip bir JSON dizisi içermelidir. Tüm öğelerin aynı hiyerarşik bölüm anahtarı değerine, ancak benzersiz kimlik alanlarına sahip olduğunu gözlemleyin. Dahil edilen örnek çıktı kısa olması için kesilir.

[
  {
    "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"
    },
    ...
  }
]

Kaynakları temizleme

Artık gerekli olmadığında, bu öğreticide kullanılan veritabanını silin. Bunu yapmak için hesap sayfasına gidin, Veri Gezgini seçin, veritabanını seçin cosmicworks ve ardından Sil'i seçin.

Sonraki adımlar

Azure Cosmos DB kullanarak ilk .NET konsol uygulamanızı oluşturduğunuza göre, mevcut bir web uygulamasını Azure Cosmos DB verilerini kullanacak şekilde güncelleştireceğiniz sonraki öğreticiyi deneyin.

Öğretici: NoSQL için Azure Cosmos DB ile ASP.NET web uygulaması geliştirme