Öğretici: NoSQL için Azure Cosmos DB ile ASP.NET web uygulaması geliştirme
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
Ö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 vekey
parametreleri içinendpoint
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-32
sahip 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
veRetrieveAllProductsAsync
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önergesiMicrosoft.Azure.Cosmos
ekleyin.using Microsoft.Azure.Cosmos; using Microsoft.Azure.Cosmos.Linq;
CosmosService sınıfı içinde adlı
_client
türüneCosmosClient
yeniprivate 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ı
container
türündeContainer
yeniprivate
bir özellik oluşturun. Veritabanını veproducts
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ürenIEnumerable<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.GetItemLinqQueryable<>
Dil ile tümleşik sorgu (LINQ) oluşturmak için kullanabileceğiniz türdeIQueryable<>
bir nesne almak için genel yöntemini kullanın. Bu nesneyi adlıqueryable
bir değişkende depolayın.var queryable = container.GetItemLinqQueryable<Product>();
ve
OrderByDescending
uzantısı yöntemlerini kullanarakWhere
bir LINQ sorgusu oluşturun.ToFeedIterator
Azure Cosmos DB'den veri almak ve yineleyiciyi adlıfeed
bir 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();
Genel
List<>
türü kullanarak adlıresults
yeni bir değişken oluşturun.List<Product> results = new();
değişkeninin özelliği
feed
false döndürene kadarHasMoreResults
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) { }
while döngüsü içinde, zaman uyumsuz olarak değişkeninin
ReadNextAsync
yöntemini çağırınfeed
ve sonucu adlıresponse
bir değişkende depolayın.while (feed.HasMoreResults) { var response = await feed.ReadNextAsync(); }
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); } }
results
Listeyi yönteminin çıktısıRetrieveAllProductsAsync
olarak döndürür.return results;
adlı
RetrieveActiveProductsAsync
, bir döndürenIEnumerable<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.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) """;
Dizeyi
sql
tek sorgu parametresi olarak geçirme adlıquery
yeniQueryDefinition
bir değişken oluşturun. Ayrıca, değerired
@tagFilter
parametreye uygulamak için akışkan yöntemini kullanınWithParameter
.var query = new QueryDefinition( query: sql ) .WithParameter("@tagFilter", "red");
Azure Cosmos DB'den
GetItemQueryIterator<>
veri alan bir yineleyici oluşturmak için genel yöntemi vequery
değişkenini kullanın. Yineleyiciyi adlıfeed
bir 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 );
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.
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.
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin