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

Makale
04/10/2024

UYGULANANLAR: NoSQL

.NET için Azure SDK, C# dilinde LINQ veya SQL sorgu dizesi kullanarak NoSQL kapsayıcısı için API'deki verileri sorgulamanıza olanak tanır. Bu öğreticide, API'den sorgulamak için yer tutucu verileri kullanan mevcut bir ASP.NET web uygulamasını güncelleştirme işlemi izlenecektir.

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

NoSQL için API kullanarak veritabanı ve kapsayıcı oluşturma ve doldurma
Şablondan ASP.NET web uygulaması oluşturma
.NET için Azure SDK'sını kullanarak NoSQL kapsayıcısı için API'den veri sorgulama

Ö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 bir veritabanı ve kapsayıcı oluşturacaksınız. Ardından dotnet aracını kullanarak cosmicworks bu hesabı verilerle dolduracaksınız.

Azure portalında mevcut NoSQL hesabı API'nize gidin.
Kaynak menüsünde Anahtarlar'ı seçin.
Anahtarlar sayfasında BİRİnCİl BAĞLANTI DIZESİ* alanının değerini gözlemleyin ve kaydedin. Bu değer öğretici boyunca kullanılacaktır.
Kaynak menüsünde Veri Gezgini'ı seçin.
Veri Gezgini sayfasında, komut çubuğundaKi Yeni Kapsayıcı seçeneğini belirleyin.

Yeni Kapsayıcı iletişim kutusunda aşağıdaki ayarlarla yeni bir kapsayıcı oluşturun:

Ayar	Value
Veritabanı kimliği	`cosmicworks`
Veritabanı aktarım hızı türü	El ile
Veritabanı aktarım hızı miktarı	`1000`
Kapsayıcı kimliği	`products`
Bölüm anahtarı	`/category/name`

Veri Gezgini her alanda çeşitli değerler içeren Yeni Kapsayıcı iletişim kutusunun ekran görüntüsü.

Önemli

Bu öğreticide, veri geçişi performansını en üst düzeye çıkarmak için önce veritabanını paylaşılan aktarım hızı olarak 1.000 RU/sn'ye kadar ölçeklendireceğiz. Veri geçişi tamamlandıktan sonra, sağlanan aktarım hızının ölçeğini 400 RU/sn'ye düşüreceğiz.

Veritabanını ve kapsayıcıyı oluşturmak için Tamam'ı seçin.
Kapsayıcıyı verilerle doldurmak için komutları çalıştırmak için bir terminal açın.

İpucu

İsteğe bağlı olarak burada Azure Cloud Shell'i kullanabilirsiniz.

NuGet'ten dotnet aracının cosmicworks v2'sini yükleyin.

dotnet tool install --global cosmicworks  --version 2.*

Bu laboratuvarın önceki bölümlerinde cosmicworks kaydettiğiniz URI ve BİRİnCİl ANAHTAR değerlerini kullanarak NoSQL hesabına yönelik API'nizi örnek ürün verileriyle doldurmak için aracını kullanın. Bu kaydedilen değerler sırasıyla ve key parametreleri için endpoint kullanılır.
```
cosmicworks \
    --number-of-products 1759 \
    --number-of-employees 0 \
    --disable-hierarchical-partition-keys \
    --connection-string <nosql-connection-string>
```

Komut satırı aracının çıkışını gözlemleyin. Kapsayıcıya 1759 öğe eklemelidir. Dahil edilen örnek çıktı kısa olması için kesilir.

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

Hesabınızın Veri Gezgini sayfasına dönün.
Veri bölümünde veritabanı düğümünü cosmicworks genişletin ve ölçeklendir'i seçin.
Aktarım hızını 1.000'den 400'edüşürün.
Komut çubuğunda Kaydet'i seçin.
Veri bölümünde products kapsayıcı düğümünü genişletin ve seçin.
Komut çubuğunda Yeni SQL sorgusu'nu seçin.

Sorgu düzenleyicisinde bu SQL sorgu dizesini ekleyin.

SELECT
  p.sku,
  p.price
FROM products p
WHERE p.price < 2000
ORDER BY p.price DESC

Sorguyu çalıştırmak ve sonuçları gözlemlemek için Sorguyu Yürüt'e tıklayın.
Sonuçlar, en yüksek fiyattan en düşük değere sıralanmış 2.000'den küçük bir price değere sahip kapsayıcıdaki tüm öğelerin sayfalandırılmış dizisi olmalıdır. Kısa olması için çıkışın bir alt kümesi buraya eklenir.
```
[
  {
    "sku": "BK-R79Y-48",
    "price": 1700.99
  },
  ...
  {
    "sku": "FR-M94B-46",
    "price": 1349.6
  },
...
```

Sorgu düzenleyicisinin içeriğini bu sorguyla değiştirin ve sonuçları gözlemlemek için Sorguyu Yürüt'e yeniden tıklayın.

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)

Sonuçlar, yalnızca ad değerine Tag-32sahip en az bir etiket içeren öğeleri içerecek şekilde filtrelenmiş daha küçük bir öğe dizisi olmalıdır. Yine, kısa bir süre için çıkışın bir alt kümesi buraya eklenir.

[
  ...
  {
    "name": "HL Touring Frame - Yellow, 60",
    "category": "Components",
    "subcategory": "Touring Frames",
    "tags": [
      "Components",
      "Touring Frames",
      "Yellow",
      "60"
    ]
  },
  ...
]

ASP.NET web uygulaması oluşturma

Şimdi örnek proje şablonunu kullanarak yeni bir ASP.NET web uygulaması oluşturacaksınız. Ardından kaynak kodu keşfedecek ve .NET için Azure SDK'sını kullanarak Azure Cosmos DB bağlantısı eklemeden önce uygulamayı tanımak için örneği çalıştıracaksınız.

Önemli

Bu öğretici, NuGet'ten paketleri saydam bir şekilde çeker. Paket kaynaklarınızı doğrulamak için kullanabilirsiniz dotnet nuget list source . NuGet'i paket kaynağı olarak kullanmıyorsanız, siteyi kaynak olarak yüklemek için kullanın dotnet nuget add source .

Boş bir dizinde bir terminal açın.
NuGet'ten cosmicworks.template.web proje şablonu paketini yükleyin.
```
dotnet new install cosmicworks.template.web
```
Yeni yüklenen dotnet new cosmosdbnosql-webapp şablonu kullanarak yeni bir web uygulaması projesi oluşturun.
```
dotnet new cosmosdbnosql-webapp
```
Web uygulaması projesini derleyin ve çalıştırın.
```
dotnet run
```

Run komutunun çıkışını gözlemleyin. Çıktı, uygulamanın çalıştığı bağlantı noktalarının ve URL'lerin listesini içermelidir.

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

Yeni bir tarayıcı açın ve çalışan web uygulamasına gidin. Çalışan uygulamanın üç sayfasını da gözlemleyin.
Çalışan işlemi sonlandırarak çalışan uygulamayı durdurun.

İpucu

Çalışan bir işlemi durdurmak için Ctrl+C komutunu kullanın. Alternatif olarak, terminali kapatıp yeniden açabilirsiniz.
Çalışma alanı olarak geçerli proje klasörünü kullanarak Visual Studio Code'yu açın.

İpucu

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.

Hizmetler/ICosmosService.cs dosyasına gidin ve dosyayı açın. RetrieveActiveProductsAsync ve RetrieveAllProductsAsync varsayılan yöntem uygulamalarını gözlemleyin. Bu yöntemler, projeyi ilk kez çalıştırırken kullanılacak statik bir ürün listesi oluşturur. Yöntemlerden birinin kesilmiş bir örneği burada verilmiştir.

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

Hizmetler/CosmosService.cs dosyasına gidin ve dosyasını açın. CosmosService sınıfının geçerli uygulamasını gözlemleyin. Bu sınıf ICosmosService arabirimini uygular ancak hiçbir yöntemi geçersiz kılmaz. Bu bağlamda, arabiriminde uygulamanın geçersiz kılınma işlemi sağlanana kadar sınıfı varsayılan arabirim uygulamasını kullanır.
```
public class CosmosService : ICosmosService
{ }
```
Son olarak Models/Product.cs ve Models/Category.cs dosyalarına gidin ve açın. Her dosyada tanımlanan kayıt türlerini gözlemleyin. Bu türler bu öğretici boyunca sorgularda kullanılacaktır.
```
public record Product(
    string id,
    Category category,
    string sku,
    string name,
    string description,
    decimal price
);
```
```
public record Category(
    string name
);
```

.NET SDK'sını kullanarak verileri sorgulama

Ardından bu örnek projeye .NET için Azure SDK'sını ekleyecek ve kitaplığını kullanarak NoSQL kapsayıcısı için API'den veri sorgulayacaksınız.

Terminale geri dönüp NuGet'ten Microsoft.Azure.Cosmos paketi ekleyin.
```
dotnet add package Microsoft.Azure.Cosmos
```
Projeyi derleyin.
```
dotnet build
```
Visual Studio Code'a geri dönüp Services/CosmosService.cs dosyasına yeniden gidin.
ve Microsoft.Azure.Cosmos.Linq ad alanları için yeni bir using yönergesi Microsoft.Azure.Cosmos ekleyin.
```
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;
```
CosmosService sınıfı içinde adlı _clienttürüne CosmosClient yeni private readonly bir üye ekleyin.
```
private readonly CosmosClient _client;
```
sınıfı için CosmosService yeni bir boş oluşturucu oluşturun.
```
public CosmosService()
{ }
```
Oluşturucu içinde, daha önce laboratuvara CosmosClient kaydettiğiniz BİRİnCİl BAĞLANTI DIZESİ değeriyle bir dize parametresi geçirerek sınıfının yeni bir örneğini oluşturun. Bu yeni örneği üyede depolayın _client .
```
public CosmosService()
{ 
    _client = new CosmosClient(
        connectionString: "<primary-connection-string>"
    );
}
```
CosmosService sınıfına geri dönüp adlı containertüründe Container yeni private bir özellik oluşturun. Veritabanını ve products kapsayıcıyı döndürmek için get erişimcisinicosmicworks ayarlayın.
```
private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}
```
adlı RetrieveAllProductsAsync , bir döndüren IEnumerable<Product>yeni bir zaman uyumsuz yöntem oluşturun.
```
public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }
```
Sonraki adımlar için bu kodu yöntemine RetrieveAllProductsAsync ekleyin.
1. GetItemLinqQueryable<> Dil ile tümleşik sorgu (LINQ) oluşturmak için kullanabileceğiniz türde IQueryable<> bir nesne almak için genel yöntemini kullanın. Bu nesneyi adlı queryablebir değişkende depolayın.
```
var queryable = container.GetItemLinqQueryable<Product>();
```
2. ve OrderByDescending uzantısı yöntemlerini kullanarak Where bir LINQ sorgusu oluşturun. ToFeedIterator Azure Cosmos DB'den veri almak ve yineleyiciyi adlı feedbir değişkende depolamak üzere bir yineleyici oluşturmak için uzantı yöntemini kullanın. Yineleyiciyi daha sonra atmak için bu ifadenin tamamını bir using deyimine sarmalayın.
```
using FeedIterator<Product> feed = queryable
    .Where(p => p.price < 2000m)
    .OrderByDescending(p => p.price)
    .ToFeedIterator();
```
3. Genel List<> türü kullanarak adlı results yeni bir değişken oluşturun.
```
List<Product> results = new();
```
4. değişkeninin özelliği feed false döndürene kadar HasMoreResults yinelenecek bir while döngüsü oluşturun. Bu döngü, sunucu tarafı sonuçların tüm sayfalarında döngü gerçekleştirmenizi sağlar.
```
while (feed.HasMoreResults)
{ }
```
5. while döngüsü içinde, zaman uyumsuz olarak değişkeninin ReadNextAsync yöntemini çağırın feed ve sonucu adlı responsebir değişkende depolayın.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}
```
6. Hala while döngüsünün içinde, yanıttaki her öğeyi gözden geçirip listeye results eklemek için bir foreach döngüsü kullanın.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}
```
7. results Listeyi yönteminin çıktısı RetrieveAllProductsAsync olarak döndürür.
```
return results;
```
adlı RetrieveActiveProductsAsync , bir döndüren IEnumerable<Product>yeni bir zaman uyumsuz yöntem oluşturun.
```
public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }
```
Sonraki adımlar için bu kodu yöntemine RetrieveActiveProductsAsync ekleyin.
1. Her öğenin etiketler dizisine filtrenin (@tagFilter) uygulandığı birden çok alanı almak için SQL sorgusuyla adlı sql yeni bir dize oluşturun.
```
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)
""";
```
2. Dizeyi sql tek sorgu parametresi olarak geçirme adlı query yeni QueryDefinition bir değişken oluşturun. Ayrıca, değeri red@tagFilter parametreye uygulamak için akışkan yöntemini kullanınWithParameter.
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "red");
```
3. 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 FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);
```
4. Birden çok sonuç sayfasında yineleme yapmak ve değeri genel List<> adlandırılmış sonuçlarda depolamak için bir while döngüsü kullanın. Sonuçları yöntemin çıktısı RetrieveActiveProductsAsync olarak döndürür.
```
List<Product> results = new();

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}

return results;
```
Services/CosmosClient.cs dosyasını kaydedin.

İpucu

Kodunuzun doğru olduğundan emin değilseniz, kaynak kodunuzu GitHub'da örnek kodla karşılaştırabilirsiniz.

Son uygulamayı doğrulama

Son olarak, uygulamayı çalışırken yeniden yüklemeler etkinleştirilmiş olarak çalıştıracaksınız. Uygulamayı çalıştırmak kodunuzun NoSQL için API'den verilere erişebildiğini doğrular.

Terminale geri dönüp uygulamayı çalıştırın.
```
dotnet run
```
Run komutunun çıktısı, uygulamanın çalıştığı bağlantı noktalarının ve URL'lerin listesini içermelidir. Yeni bir tarayıcı açın ve çalışan web uygulamasına gidin. Çalışan uygulamanın üç sayfasını da gözlemleyin. Her sayfada artık Azure Cosmos DB'den canlı veriler bulunmalıdır.

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'yi kullanarak ilk .NET web uygulamanızı oluşturduğunuza göre artık daha fazla veri içeri aktarmak, karmaşık sorgular gerçekleştirmek ve NoSQL için Azure Cosmos DB kaynaklarınızı yönetmek için SDK'yı ayrıntılı olarak gözden geçirin.

NoSQL ve .NET için Azure Cosmos DB ile çalışmaya başlama