.NET Aspire Azure tümleştirmelerine genel bakış

, uygulamaları oluşturmak ve dağıtmak için en popüler bulut platformudur. için SDK'sı, hizmetlerinin kolayca yönetilmesini ve kullanılmasını sağlar. .NET Aspire, yeni kaynaklar eklemek veya mevcut hizmetlere bağlanmak için ücretsiz olduğunuz Azure hizmetleriyle bir dizi tümleştirme sağlar. Makale, Azure'deki tüm .NET Aspire tümleştirmelerinin ortak yönlerini detaylandırarak, bunların nasıl kullanılacağını anlamanıza yardımcı olmayı amaçlar.

Azure kaynakları ekle

Tüm .NET AspireAzure barındırma tümleştirmeleri Azure kaynakları kullanıma sunar ve kurala göre AddAzure* API'ler kullanılarak eklenir. Bu kaynakları .NET Aspire uygulama konağınıza eklediğinizde, bunlar bir Azure hizmetini temsil ederler. AddAzure* API, IResourceBuilder<T>'nin T kaynağı türü olduğu bir Azure'i döndürür. Bu IResourceBuilder<T> (oluşturucu) arabirimleri, Azureiçinde temel kaynağını yapılandırmanıza olanak tanıyan akıcı bir API sağlar. Yeni Azure kaynakları eklemek, kaynakları var olan olarak işaretlemek ve kaynakların çeşitli yürütme bağlamlarında nasıl davranacağını yapılandırmak için API'ler vardır.

Tipik geliştirici deneyimi

.NET Aspire uygulama konağınız Azure kaynaklar içerdiğinde ve bunu yerel olarak çalıştırdığınızda (tipik geliştirici F5 veya dotnet run deneyimi), Azure kaynaklarıAzure aboneliğinizde sağlanır. Bu, geliştirici olarak uygulamanızın bağlamında yerel ortamda hata ayıklama yapmanıza olanak tanır.

.NET .NET Aspire, maliyetleri varsayılan olarak Temel veya StandartStok Tutma Birimi (SKU) kullanarak Azure tümleştirmeleri için en aza indirmeyi amaçlar. Bu mantıklı varsayılanlar sağlansa da Azure kaynaklarını gereksinimlerinize uyacak şekilde özelleştirebilirsiniz. Ayrıca, bazı tümleştirmeler yerel geliştirme, test ve hata ayıklama için yararlı olan öykünücülerini veya kapsayıcılarını destekler. Varsayılan olarak, uygulamanızı yerel olarak çalıştırdığınızda, Azure kaynakları gerçek Azure hizmetini kullanır. Ancak yerel öykünücüleri veya kapsayıcıları kullanacak şekilde yapılandırabilir ve yerel geliştirme sırasında gerçek Azure hizmetiyle ilişkili maliyetlerden kaçınabilirsiniz.

Yerel öykünücüler

Bazı Azure hizmetleri yerel olarak çalışacak şekilde simüle edilebilir. Şu anda .NET Aspire aşağıdaki Azure öykünücülerini destekler:

Azure kaynaklarınızın yerel öykünücüleri kullanmasını sağlamak için, RunAsEmulator kaynak oluşturucusunun Azure yöntemini ardışık olarak çağırın. Bu yöntem, Azure kaynağını gerçek Azure hizmeti yerine yerel öykünücüyü kullanacak şekilde yapılandırır.

Yerel kapsayıcılar

Bazı Azure kaynakları, açık kaynak veya şirket içi kapsayıcılar kullanılarak yerel olarak değiştirilebilir. Kapsayıcıdaki bir Azure kaynağını yerel olarak değiştirmek için, RunAsContainer kaynak oluşturucusunda Azure yöntemine bir çağrı zincirleyin. Bu yöntem, Azure kaynağını gerçek Azure hizmeti yerine yerel geliştirme ve test için hizmetin kapsayıcılı bir sürümünü kullanacak şekilde yapılandırır.

Şu anda .NET Aspire kapsayıcı olarak aşağıdaki Azure hizmetlerini destekler:

Azure tümleştirme API'lerini anlama

.NET .NET Aspire'nin gücü, inanılmaz bir geliştirici iç döngüsü sağlama yeteneğinde yatmaktadır. Azure tümleştirmeleri de diğerlerinden farklı değildir. Onlar, tüm Azure kaynaklarında paylaşılan bir ortak API ve desen kümesi sağlarlar. Bu API'ler ve desenler, Azure kaynaklarla tutarlı bir şekilde çalışmayı kolaylaştırmak için tasarlanmıştır.

Önceki kapsayıcılar bölümünde, Azure hizmetlerinin kapsayıcılarda yerel olarak nasıl çalıştırılacağını öğrendiniz. .NET .NET Aspirehakkında bilginiz varsa, yerel AddAzureRedis("redis").RunAsContainer() kapsayıcısı almak için docker.io/library/redis çağırmanın AddRedis("redis")'den ne kadar farklı olduğunu merak edebilirsiniz çünkü her ikisi de aynı yerel kapsayıcıyla sonuçlanır.

Yanıt, yerel olarak çalıştırılırken bir fark olmamasıdır. Ancak, yayımlandıklarında farklı kaynaklar elde edersiniz:

Aynı durum SQL ve PostgreSQL hizmetleri için de geçerlidir:

Çalıştırma ve yayımlama modları arasındaki fark hakkında daha fazla bilgi için bkz. .NET.NET Aspire uygulama konağı: Yürütme bağlamı.

Azure kaynaklarını farklı modlarda ifade etmek için API'ler

Dağıtılmış uygulama oluşturucusu, uygulama ana bilgisayarının bir parçası olarak, oluşturucu desenini kullanarak kaynakları AddAzure*uygulama modeline ekler. Geliştiriciler bu kaynakları yapılandırabilir ve davranışlarını farklı yürütme bağlamlarında tanımlayabilir. Azure barındırma tümleştirmeleri, bu kaynakların nasıl "yayımlanması" ve "çalıştırılması" gerektiğini belirtmek için API'ler sağlar.

Uygulama ana bilgisayarı çalıştığında, uygulama ana bilgisayarının veya modunda olup olmadığını belirlemek için Publish kullanılır. Bu API'lerin adlandırma kuralları, kaynak için hedeflenen eylemi gösterir.

Aşağıdaki tabloda, Azure kaynaklarını ifade etmek için kullanılan adlandırma kuralları özetlemektedir:

Yürütme modları hakkında daha fazla bilgi için bkz. yürütme bağlamı .

Genel çalıştırma modu API kullanım örnekleri

Çalışma zamanı sırasında mevcut bir kaynakla dağıtmaya veya güncelleştirmeye gerek kalmadan dinamik olarak etkileşim kurmanız gerektiğinde RunAsExisting kullanın. Dağıtım yapılandırmasının bir parçası olarak mevcut kaynakları bildirirken doğru kapsamların ve izinlerin uygulandığından emin olmak için PublishAsExisting kullanın. Son olarak, her iki yapılandırmada da mevcut kaynakları bildirirken, referansları parametreleştirme gereğiyle birlikte AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) kullanın.

IsExisting(IResource) IResource uzantısı yöntemini çağırarak bir kaynağın mevcut kaynak olarak işaretlenip işaretlenmediğini sorgulayabilirsiniz. Daha fazla bilgi için bkz. Azuremevcut kaynaklarını kullanma.

Mevcut Azure kaynaklarını kullanma

.NET Aspire, mevcut Azure kaynaklarına başvurma desteği sağlar. Var olan bir kaynağı PublishAsExisting, RunAsExistingve AsExisting API'leri aracılığıyla işaretlersiniz. Bu API'ler geliştiricilerin zaten dağıtılmış Azure kaynaklara başvurmasına, bunları yapılandırmasına ve Bicep şablonlarını kullanarak uygun dağıtım bildirimleri oluşturmasına olanak sağlar.

Bu API'lerle ilişkili mevcut kaynaklar, .NET.NET Aspire'in altyapı olarak kodlama yeteneklerisayesinde, rol atamaları ve diğer özelleştirmelerle geliştirilebilir. Bu API'ler, Bicep şablonlarıyla dağıtılabilir Azure kaynaklarla sınırlıdır.

Mevcut Azure kaynaklarını çalıştırma modu için yapılandırma

RunAsExisting yöntemi, dağıtılmış bir uygulama "çalıştır" modunda yürütülürken kullanılır. Bu modda, başvuruda bulunan Azure kaynağının zaten var olduğunu varsayar ve yürütme sırasında kaynağı sağlamadan onunla tümleşir. bir Azure kaynağını mevcut olarak işaretlemek için kaynak oluşturucusunun RunAsExisting yöntemini çağırın. Aşağıdaki örneği göz önünde bulundurun:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Önceki kod:

• Yeni bir builder örneği oluşturur.
• Oluşturucuya existingServiceBusName adlı bir parametre ekler.
• oluşturucuya Azure Service Bus adlı bir messaging kaynağı ekler.
• RunAsExisting kaynak oluşturucusunun serviceBus yöntemini çağırır ve existingServiceBusName parametresini geçirir; alternatif olarak, string parametre aşırı yüklemesini kullanabilirsiniz.
• queue kaynağına serviceBus adlı bir kuyruk ekler.

Varsayılan olarak, Service Bus parametre başvurusunun aynı Azure kaynak grubunda olduğu varsayılır. Ancak, farklı bir kaynak grubundaysa, uygun kaynak gruplandırma işlemini doğru belirtmek için kaynak grubunu açıkça parametre olarak geçirebilirsiniz.

Mevcut Azure kaynaklarını yayımlama modu için yapılandırma

PublishAsExisting yöntemi, amaç yayımlama modu sırasında zaten var olan bir Azure kaynağını bildirmek ve bunlara başvurmak olduğunda "yayımlama" modunda kullanılır. Bu API, Bicep'teki mevcut kaynaklarla eşleşen kaynak tanımlarını içeren bildirimlerin ve şablonların oluşturulmasını kolaylaştırır.

bir Azure kaynağını "yayımlama" modunda var olarak işaretlemek için kaynak oluşturucusunda PublishAsExisting yöntemini çağırın. Aşağıdaki örneği göz önünde bulundurun:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .PublishAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Önceki kod:

• Yeni bir builder örneği oluşturur.
• Oluşturucuya existingServiceBusName adlı bir parametre ekler.
• oluşturucuya Azure Service Bus adlı bir messaging kaynağı ekler.
• PublishAsExisting kaynak oluşturucusunun serviceBus yöntemini çağırır ve existingServiceBusName parametresini geçirir; alternatif olarak, string parametre aşırı yüklemesini kullanabilirsiniz.
• queue kaynağına serviceBus adlı bir kuyruk ekler.

Uygulama konağı yayımlama modunda yürütüldükten sonra oluşturulan bildirim dosyası, mevcut existingResourceName kaynağına başvurmak için kullanılabilecek Azure parametresini içerir. Bildirim dosyasının aşağıdaki oluşturulmuş kısmi kod parçacığını göz önünde bulundurun:

"messaging": {
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingServiceBusName": "{existingServiceBusName.value}",
    "principalType": "",
    "principalId": ""
  }
},
"queue": {
  "type": "value.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}"
}

Bildirim dosyası hakkında daha fazla bilgi için, dağıtım aracı oluşturucuları için bildirim biçimine .NET.NET Aspire bakın.

Ayrıca, oluşturulan Bicep şablonu mevcut existingResourceName kaynağına başvurmak için kullanılabilecek Azure parametresini içerir. Aşağıdaki oluşturulan Bicep şablonunu göz önünde bulundurun:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param existingServiceBusName string

param principalType string

param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingServiceBusName
}

resource messaging_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(messaging.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: messaging
}

resource queue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  name: 'queue'
  parent: messaging
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

Oluşturulan Bicep şablonları hakkında daha fazla bilgi için bkz. Kod olarak altyapı ve diğer yayımlama API'lerini göz önünde bulundurun .

Tüm modlarda mevcut Azure kaynaklarını yapılandırma

AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) yöntemi, dağıtılmış uygulama "çalıştır" veya "yayımla" modunda çalışırken kullanılır. AsExisting yöntemi her iki senaryoda da çalıştığından, yalnızca kaynak adına veya kaynak grubu adına parametreli başvuruyu destekler. Bu yaklaşım hem test hem de üretim ortamlarında aynı kaynağın kullanılmasını önlemeye yardımcı olur.

bir Azure kaynağını mevcut olarak işaretlemek için kaynak oluşturucusunun AsExisting yöntemini çağırın. Aşağıdaki örneği göz önünde bulundurun:

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Önceki kod:

• Yeni bir builder örneği oluşturur.
• Oluşturucuya existingServiceBusName adlı bir parametre ekler.
• oluşturucuya Azure Service Bus adlı bir messaging kaynağı ekler.
• AsExisting kaynak oluşturucusunun serviceBus yöntemini çağırır ve existingServiceBusName parametresini geçirir.
• queue kaynağına serviceBus adlı bir kuyruk ekler.

Bağlantı dizeleriyle mevcut Azure kaynaklarını ekleme

, kaynakları da dahil olmak üzeremevcut kaynaklara bağlanma olanağı sağlar. bağlantı dizelerini ifade etmek, Azure uygulamanızda kullanmak istediğiniz mevcut .NET Aspire kaynaklarınız olduğunda kullanışlıdır. AddConnectionString API'si, uygulama ana bilgisayarının yürütme bağlamı ile birlikte, koşullu olarak uygulama modeline bir bağlantı dizesi eklemek için kullanılır.

Aşağıdaki örneği göz önünde bulundurun; burada yayın modunda bir Azure Depolama kaynağı eklerken, çalıştırma modunda mevcut bir Azure Depolamaya bir bağlantı dizesi eklersiniz:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureStorage("storage")
    : builder.AddConnectionString("storage");

builder.AddProject<Projects.Api>("api")
       .WithReference(storage);

// After adding all resources, run the app...

Önceki kod:

• Yeni bir builder örneği oluşturur.
• "Yayımla" modunda Azure adlı bir storage Depolama kaynağı ekler.
• "Çalıştır" modunda Azure adlı mevcut bir storage Depolamaya bağlantı dizesi ekler.
• Oluşturucuya api adlı bir proje ekler.
• api projesi, moddan bağımsız olarak storage kaynağına başvurur.

Kullanıcı API projesi, uygulama ana bilgisayarı tarafından nasıl yapılandırıldığına dair bilgisi olmadan bağlantı dizesi bilgilerini kullanır. "Yayımlama" modunda kod, yeni bir Depolama kaynağı ekler ve bu da olarak dağıtım bildirimine yansıtılır. "Çalıştır" modundayken bağlantı dizesi, uygulama konağı tarafından görünen bir yapılandırma değerine karşılık gelir. Hedef kaynak için tüm rol atamalarının yapılandırıldığı varsayılır. Bu, bağlantı dizesini depolamak için büyük olasılıkla bir ortam değişkeni veya kullanıcı gizli dizisi yapılandıracağınız anlamına gelir. Yapılandırma, ConnectionStrings__storage (veya ConnectionStrings:storage) yapılandırma anahtarından çözülür. Bu yapılandırma değerleri, uygulama çalıştırıldığında görüntülenebilir. Daha fazla bilgi için bkz. Kaynak ayrıntıları.

birinci sınıf AsExisting API ile modellenen mevcut kaynaklardan farklı olarak, bağlantı dizeleri olarak modellenen mevcut kaynak ek rol atamaları veya altyapı özelleştirmeleriyle geliştirilemez.

Azure Kapsayıcı Uygulaması Olarak Yayımla

.NET .NET Aspire temel kaynakları altyapı yönetimini azaltan sunucusuz bir platform olan Azure Container Appsolarak yayımlamanıza olanak tanır. Desteklenen kaynak türlerinden bazıları şunlardır:

• ContainerResource: Belirtilen kapsayıcıyı temsil eder.
• ExecutableResource: Belirtilen yürütülebilir işlemi temsil eder.
• ProjectResource: Belirtilen .NET projelerini temsil eder.

Bu kaynakları yayımlamak için aşağıdaki API'leri kullanın:

• AzureContainerAppContainerExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)
• AzureContainerAppProjectExtensions.PublishAsAzureContainerApp<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure,ContainerApp>)

Bu API'ler, kaynakları Azure Kapsayıcı Uygulaması olarak yayımlanacak şekilde yapılandırır ve gerekli altyapı ile Bicep dosyalarını uygulama konağınıza eklemek için dolaylı olarak AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder)'i çağırır. Örneğin, aşağıdaki kodu göz önünde bulundurun:

var builder = DistributedApplication.CreateBuilder();

var env = builder.AddParameter("env");

var api = builder.AddProject<Projects.AspireApi>("api")
                 .PublishAsAzureContainerApp<Projects.AspireApi>((infra, app) =>
                 {
                     app.Template.Containers[0].Value!.Env.Add(new ContainerAppEnvironmentVariable
                     {
                         Name = "Hello",
                         Value = env.AsProvisioningParameter(infra)
                     });
                 });

Önceki kod:

• Yeni bir builder örneği oluşturur.
• Oluşturucuya env adlı bir parametre ekler.
• Oluşturucuya api adlı bir proje ekler.
• infra'ün AzureResourceInfrastructure ve app'in ContainerAppolduğu durumlarda, api kaynak oluşturucusunun PublishAsAzureContainerApp yöntemini çağırarak, Azure Container App altyapısını yapılandıran bir lambda ifadesi geçirir.
  • env parametresini kullanarak kapsayıcı uygulamasına Hello adlı bir ortam değişkeni ekler.
  • AsProvisioningParameter yöntemi, env'i altyapıda ya yeni bir ProvisioningParameter olarak ele almak ya da aynı ada sahip bir parametre mevcutsa var olan bicep parametresini yeniden kullanmak için kullanılır.

Daha fazla bilgi için bkz. ContainerApp ve AsProvisioningParameter.

Kod olarak altyapı

Azure için .NET SDK'sı, 📦Azure sağlama NuGet paketi ve hizmete özgü Azure sağlama paketlerinden oluşan bir dizi sunar. Bu Azure sağlama kitaplıkları, Azure altyapısını .NET'da yerel olarak bildirimli bir şekilde belirtmeyi kolaylaştırır. API'leri, C# dilinde nesne yönelimli bir altyapı yazmanıza olanak tanır ve bunun sonucunda Bicep ile çalışabilirsiniz. Bicep, kaynakları beyan yoluyla dağıtmak için kullanılan bir alan-özel dili (DSL)dır.

Azure kaynakları el ile sağlamak mümkün olsa da .NET AspireAzure kaynakları ifade etmek için bir dizi API sağlayarak süreci basitleştirir. Bu API'ler, .NET Aspire arabirimini genişleten AzureIDistributedApplicationBuilder barındırma kitaplıklarında uzantı yöntemleri olarak kullanılabilir. Uygulama konağınıza Azure kaynakları eklediğinizde, bunlar dolaylı olarak uygun sağlama işlevselliğini sağlar. Başka bir deyişle, herhangi bir sağlama API'sini doğrudan çağırmanız gerekmez.

.NET Aspire modelleri Azure barındırma tümleştirmelerinin içinde Azure kaynakları modellediğinden, bu kaynaklar Azure SDK kullanılarak sağlanır. Sizin için gerekli olan Azure kaynaklarını tanımlayan Bicep dosyaları oluşturulmaktadır. Oluşturulan Bicep dosyaları, uygulamanızı yayımladığınızda bildirim dosyasıyla birlikte çıkarılır.

Oluşturulan Bicep dosyalarını etkilemenin birkaç yolu vardır:

• Azure. Özelleştirme sağlama:
  • Altyapıyı yapılandırma: Azure kaynak altyapısını özelleştirin.
  • Azure altyapısı ekleme: Uygulama konağınıza Azure altyapısını el ile ekleyin.
• özel Bicep şablonlarınıkullanın:
  • Bicep dosyasına referans ekleme: Diskteki bir Bicep dosyasına referans ekleyin.
  • Referans Bicep iç içe: İç içe bir Bicep şablonu ekleyin.

Yerel sağlama ve Azure.Provisioning

Terimleri karıştırmaktan kaçınmak ve "sağlamayı" netleştirmeye yardımcı olmak için, yerel sağlama ile Azure sağlamaarasındaki farkı anlamak önemlidir.

• Yerel sağlama:

  Varsayılan olarak, Azure kaynakları eklemek için Azure barındırma tümleştirme API'lerinden herhangi birini çağırdığınızda, AddAzureProvisioning(IDistributedApplicationBuilder) API örtük olarak çağrılır. Bu API, uygulama konağı başlatıldığında Azure kaynakları sağlamak için kullanılan bağımlılık ekleme (DI) kapsayıcısına hizmetleri kaydeder. Bu kavram, yerel sağlamaolarak bilinir. Daha fazla bilgi için bkz. Yerel Azure sağlama.

• Azure.Provisioning:

  Azure.Provisioning NuGet paketine başvurur ve Bicep oluşturmak için C# kullanmanıza olanak tanıyan bir kitaplık kümesidir. Azure barındırma tümleştirmeleri .NET Aspire altında bu kitaplıkları kullanarak ihtiyacınız olan Azure kaynaklarını tanımlayan Bicep dosyaları oluşturur. Daha fazla bilgi için Azure.Provisioning özelleştirme'ye bakın.

Azure.Provisioning özelleştirme

Tüm .NET AspireAzure barındırma tümleştirmeleri çeşitli Azure kaynaklarını kullanıma sunar ve bunların tümü AzureProvisioningResource türünün alt sınıflarıdır ve AzureBicepResourcedevralır. Bu, genel olarak bu türle kısıtlanmış uzantıları etkinleştirir ve akıcı bir API'nin altyapıyı istediğiniz gibi özelleştirmesine olanak tanır. .NET .NET Aspire varsayılan değerler sağlasa da, bu API'leri kullanarak oluşturulan Bicep'i etkileyebilirsiniz.

Altyapıyı yapılandırma

Çalışmakta olduğunuz Azure kaynağından bağımsız olarak, temel altyapısını yapılandırmak için ConfigureInfrastructure uzantı yöntemine ardışık çağrıda bulunursunuz. Bu yöntem, Azuretüründe bir configure temsilcisi geçirerek Action<AzureResourceInfrastructure> kaynağının altyapısını özelleştirmenizi sağlar. AzureResourceInfrastructure türü, Azure.Provisioning.Infrastructurealt sınıfıdır. Bu tür, Azure kaynağının temel altyapısını yapılandırmak için çok büyük bir API yüzey alanı sunar.

Aşağıdaki örneği göz önünde bulundurun:

var sku = builder.AddParameter("storage-sku");

var storage = builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();

        var storageAccount = resources.OfType<StorageAccount>().Single();

        storageAccount.Sku = new StorageSku
        {
            Name = sku.AsProvisioningParameter(infra)
        };
    });

Önceki kod:

• storage-skuadlı bir parametre ekler.
• Azureadlı AddAzureStorage API'sine storage Depolama ekler.
• ConfigureInfrastructure'a bir çağrıyı zincirleyerek Azure Depolama altyapısını özelleştirir:
  • Sağlanabilir kaynakları elde eder.
  • Tek bir StorageAccount'ı filtreler.
  • storage-sku parametresini StorageAccount.Sku özelliğine atar:
    • StorageSku yeni bir örneğinin, Name API'sinin sonucundan atanan AsProvisioningParameter özelliği vardır.

Bu, dış bir parametrenin Depolama altyapısına akışını örnekler ve oluşturulan Bicep dosyasının istenen yapılandırmayı yansıtmasını sağlar.

Azure altyapısı ekleme

Tüm Azure hizmetleri .NET Aspire tümleştirmeleri olarak kullanıma sunulmaz. Daha sonra olabilecek olmasına rağmen, Azure.Provisioning.* kitaplıklarında mevcut olan hizmetleri sağlayabilirsiniz. Azure Container Registry'yi yönetmekle sorumlu çalışan hizmetiniz olduğu bir senaryo düşünün. Şimdi bir uygulama konak projesinin 📦Azure.Provisioning.ContainerRegistry NuGet paketine bağımlılık aldığını hayal edin.

AddAzureInfrastructure Container Registry altyapısını uygulama konağınıza eklemek için Azure API'sini kullanabilirsiniz:

var acr = builder.AddAzureInfrastructure("acr", infra =>
{
    var registry = new ContainerRegistryService("acr")
    {
        Sku = new()
        {
            Name = ContainerRegistrySkuName.Standard
        },
    };
    infra.Add(registry);

    var output = new ProvisioningOutput("registryName", typeof(string))
    {
        Value = registry.Name
    };
    infra.Add(output);
});

builder.AddProject<Projects.WorkerService>("worker")
       .WithEnvironment(
            "ACR_REGISTRY_NAME",
            new BicepOutputReference("registryName", acr.Resource));

Önceki kod:

• AddAzureInfrastructure, acradıyla çağrılır.
• configureInfrastructure Container Registry altyapısını özelleştirmek için Azure bir temsilci sağlar:
  • Bir ContainerRegistryService örneğini, acr adıyla ve standart bir SKU ile oluşturur.
  • Azure Container Registry hizmetini infra değişkenine ekler.
  • ProvisioningOutput adında, registryName türünde ve Azure Container Registry ismine karşılık gelen bir değere sahip bir string örneği oluşturur.
  • Çıktıyı infra değişkenine ekler.
• Oluşturucuya worker adlı bir proje ekler.
• Projede WithEnvironment ortam değişkenini ACR_REGISTRY_NAME çıkışının değerine ayarlamak için registryName'a bir çağrı zincirler.

İşlev, Azure hizmeti doğrudan bir Azure tümleştirmesi olarak kullanıma sunulmasa bile uygulama ana bilgisayarınız projesine nasıl .NET Aspire altyapısı ekleneceğini gösterir. Ayrıca, Azure Container Registry'nin çıkışını bağlı bir projenin ortamına nasıl aktaracağınızı da gösterir.

Ortaya çıkan Bicep dosyasını dikkate alın.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('acr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Standard'
  }
}

output registryName string = acr.name

Bicep dosyası, Azure API tarafından tanımlanan AddAzureInfrastructure Container Registry'nin istenen yapılandırmasını yansıtır.

Özel Bicep şablonlarını kullanma

İstediğiniz bulut sağlayıcısı olarak Azure hedeflerken, altyapınızı kod olarak tanımlamak için Bicep'i kullanabilirsiniz. Daha temiz bir söz dizimi ve modülerlik ve kod yeniden kullanımı için daha iyi destek ile yazma deneyimini önemli ölçüde basitleştirmeyi amaçlar.

.NET .NET Aspire önceden oluşturulmuş bicep şablonları kümesi sağlarken, bazen şablonları özelleştirmek veya kendi şablonunuzu oluşturmak isteyebilirsiniz. Bu bölümde, Bicep şablonlarını özelleştirmek için kullanabileceğiniz kavramlar ve ilgili API'ler açıklanmaktadır.

için dağıtım hikayesinin bir parçası olarak, (), projenizi anlamanızı ve onu 'ye dağıtabilme yeteneğini sağlar. azd CLI, uygulamayı Azure'e dağıtmak için Bicep şablonlarını kullanır.

Aspire.Hosting.Azure paketini yükleme

Bicep dosyalarına başvurmak istediğinizde, Azure barındırma tümleştirmelerinden hiçbirini kullanmıyor olmanız mümkündür. Bu durumda, Aspire.Hosting.Azure paketini yükleyerek Bicep dosyalarına başvurmaya devam edebilirsiniz. Bu paket, Bicep dosyalarına başvurmak ve Azure kaynaklarını özelleştirmek için gerekli API'leri sağlar.

Bu işlevlerden herhangi birini kullanmak için 📦Aspire.Hosting.Azure NuGet paketi yüklenmelidir.

dotnet add package Aspire.Hosting.Azure

<PackageReference Include="Aspire.Hosting.Azure"
                  Version="*" />

Daha fazla bilgi için bkz. dotnet add package veya .NET uygulamalarında paket bağımlılıklarını yönetme.

Örneklerden neler bekleyebileceğiniz

Bu bölümdeki tüm örneklerde Aspire.Hosting.Azure ad alanını kullandığınız varsayılır. Ayrıca örneklerde IDistributedApplicationBuilder bir örneğiniz olduğu varsayılır:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

Varsayılan olarak, Bicep ile ilgili herhangi bir API'yi çağırdığınızda, uygulama başlatma sırasında AddAzureProvisioning kaynaklarını dinamik olarak oluşturma desteği ekleyen bir çağrı da Azure'a yapılır. Daha fazla bilgi için bkz. yerel ayarlama ve Azure.Provisioning.

Bicep dosyalarına referans ver

Hayal edin ki, storage.bicep Depolama Hesabı sağlayan bir Bicep şablonunuz var ve bu şablon Azure adlı bir dosyada bulunuyor.

param location string = resourceGroup().location
param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Disk üzerindeki Bicep dosyasına başvuru eklemek için AddBicepTemplate yöntemini çağırın. Aşağıdaki örneği göz önünde bulundurun:

builder.AddBicepTemplate(
    name: "storage",
    bicepFile: "../infra/storage.bicep");

Önceki kod, ../infra/storage.bicepkonumunda bulunan bir Bicep dosyasına bir referans ekler. Dosya yolları, uygulama konağı projesine göre olmalıdır. Bu başvuru, uygulamanın kaynak koleksiyonuna AzureBicepResource adıyla bir "storage" eklenmesine neden olur ve API kaynağı daha fazla özelleştirmek için kullanılabilecek bir IResourceBuilder<AzureBicepResource> örneği döndürür.

Bicep satır içi referansı

Diskte bicep dosyası olması en yaygın senaryo olsa da, Bicep şablonlarını satır içine de ekleyebilirsiniz. Satır içi şablonlar, kodda şablon tanımlamak istediğinizde veya şablonu dinamik olarak oluşturmak istediğinizde yararlı olabilir. Satır içi Bicep şablonu eklemek için bicep şablonuyla AddBicepTemplateString yöntemini stringolarak çağırın. Aşağıdaki örneği göz önünde bulundurun:

builder.AddBicepTemplateString(
        name: "ai",
        bicepContent: """
        @description('That name is the name of our application.')
        param cognitiveServiceName string = 'CognitiveService-${uniqueString(resourceGroup().id)}'

        @description('Location for all resources.')
        param location string = resourceGroup().location

        @allowed([
          'S0'
        ])
        param sku string = 'S0'

        resource cognitiveService 'Microsoft.CognitiveServices/accounts@2021-10-01' = {
          name: cognitiveServiceName
          location: location
          sku: {
            name: sku
          }
          kind: 'CognitiveServices'
          properties: {
            apiProperties: {
              statisticsEnabled: false
            }
          }
        }
        """
    );

Bu örnekte, Bicep şablonu satır içi string olarak tanımlanır ve "ai"adıyla uygulamanın kaynaklar koleksiyonuna eklenir. Bu örnek bir Azure yapay zeka kaynağı sağlar.

Parametreleri Bicep şablonlarına geçirme

Bicep, şablonun davranışını özelleştirmek için kullanılabilecekparametreleri kabul etme desteği sunar. .NET .NET Aspire'den bir Bicep şablonuna parametre geçirmek için, aşağıdaki örnekte gösterildiği gibi WithParameter yöntemine zincirleme çağrıları yapın:

var region = builder.AddParameter("region");

builder.AddBicepTemplate("storage", "../infra/storage.bicep")
       .WithParameter("region", region)
       .WithParameter("storageName", "app-storage")
       .WithParameter("tags", ["latest","dev"]);

Önceki kod:

• "region" örneğine builder adlı bir parametre ekler.
• ../infra/storage.bicep konumunda bulunan bir Bicep dosyasına başvuru ekler.
• standart parametre çözümlemesi kullanılarak çözümlenen "region" parametresini Bicep şablonuna geçirir.
• "storageName" parametresini sabit kodlanmış değeriyle Bicep şablonuna geçirir.
• "tags" parametresini bir dizi dizeyle Bicep şablonuna geçirir.

Daha fazla bilgi için bkz. dış parametreler.

İyi bilinen parametreler

.NET .NET Aspire, Bicep şablonlarına geçirilebilen iyi bilinen parametreler kümesi sağlar. Bu parametreler, Bicep şablonlarına uygulama ve ortam hakkında bilgi sağlamak için kullanılır. Aşağıdaki iyi bilinen parametreler kullanılabilir:

İyi bilinen bir parametre kullanmak için parametre adını WithParametergibi WithParameter(AzureBicepResource.KnownParameters.KeyVaultName) yöntemine geçirin. İyi bilinen parametrelerin değerlerini geçirmezsiniz çünkü .NET.NET Aspire bunları sizin adınıza çözümler.

Bir Azure Event Grid webhook kurmak istediğiniz bir örneği düşünün. Bicep şablonunu aşağıdaki gibi tanımlayabilirsiniz:

param topicName string
param webHookEndpoint string
param principalId string
param principalType string
param location string = resourceGroup().location

// The topic name must be unique because it's represented by a DNS entry. 
// must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-".

resource topic 'Microsoft.EventGrid/topics@2023-12-15-preview' = {
  name: toLower(take('${topicName}${uniqueString(resourceGroup().id)}', 50))
  location: location

  resource eventSubscription 'eventSubscriptions' = {
    name: 'customSub'
    properties: {
      destination: {
        endpointType: 'WebHook'
        properties: {
          endpointUrl: webHookEndpoint
        }
      }
    }
  }
}

resource EventGridRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(topic.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7'))
  scope: topic
  properties: {
    principalId: principalId
    principalType: principalType
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7')
  }
}

output endpoint string = topic.properties.endpoint

Bu Bicep şablonu, topicName, webHookEndpoint, principalId, principalTypeve isteğe bağlı locationgibi çeşitli parametreleri tanımlar. Bu parametreleri Bicep şablonuna geçirmek için aşağıdaki kod parçacığını kullanabilirsiniz:

var webHookApi = builder.AddProject<Projects.WebHook_Api>("webhook-api");

var webHookEndpointExpression = ReferenceExpression.Create(
        $"{webHookApi.GetEndpoint("https")}/hook");

builder.AddBicepTemplate("event-grid-webhook", "../infra/event-grid-webhook.bicep")
       .WithParameter("topicName", "events")
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalId)
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalType)
       .WithParameter("webHookEndpoint", () => webHookEndpointExpression);

• webHookApi projesi, builder'e referans olarak eklenir.
• topicName parametresine sabit kodlanmış bir ad değeri geçirilir.
• webHookEndpoint parametresi, api rotası ile /hook proje referanslarının "https" uç noktasından URL'ye çözümlenen bir ifade olarak aktarılır.
• principalId ve principalType parametreleri iyi bilinen parametreler olarak geçirilir.

İyi bilinen parametreler kural tabanlıdır ve WithParameter API'sini kullanarak geçirildiğinde buna karşılık gelen bir değerle eşlik edilmemelidir. İyi bilinen parametreler, önceki örnekte gösterildiği gibi Bicep şablonlarına eklendiğinderol atamaları gibi bazı yaygın işlevleri basitleştirir. Event Grid web kancasının belirtilen uç noktaya olay göndermesi için rol atamaları gereklidir. Daha fazla bilgi için bkz. Event Grid Veri Gönderici rol ataması.

Bicep referanslarından çıktılar elde etme

Bicep şablonlarına parametre geçirmenin yanı sıra, Bicep şablonlarından da çıkışlar alabilirsiniz. Aşağıdaki Bicep şablonunu, outputadında bir endpoint tanımladığı için göz önünde bulundurun.

param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = myStorageAccount.properties.primaryEndpoints.blob

Bicep, endpointadlı bir çıktı tanımlar. Bicep şablonundan çıktı almak için aşağıdaki C# kod parçacığında gösterildiği gibi bir GetOutput örneğinde IResourceBuilder<AzureBicepResource> yöntemini çağırın:

var storage = builder.AddBicepTemplate(
        name: "storage",
        bicepFile: "../infra/storage.bicep"
    );

var endpoint = storage.GetOutput("endpoint");

Bu örnekte, Bicep şablonunun çıkışı alınır ve bir endpoint değişkeninde depolanır. Genellikle, bu çıkışı bir ortam değişkeni olarak ona bağlı olan başka bir kaynağa geçirirsiniz. Örneğin, bu uç noktaya bağımlı olan ASP.NET Core Minimal API projeniz varsa, aşağıdaki kod parçacığını kullanarak çıkışı projeye ortam değişkeni olarak geçirebilirsiniz:

var storage = builder.AddBicepTemplate(
                name: "storage",
                bicepFile: "../infra/storage.bicep"
            );

var endpoint = storage.GetOutput("endpoint");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>(
        name: "apiservice"
    )
    .WithEnvironment("STORAGE_ENDPOINT", endpoint);

Daha fazla bilgi için bakınız Bicep çıkışları.

Bicep referanslarından gizli çıktılara erişme

Bicep ile çalışırken gizli bilgiler için çıkışlardan kaçınmak önemlidir. Bir çıkış gizliolarak kabul ediliyorsa ve bu nedenle günlüklerde veya başka yerlerde gösterilmemesi gerekiyorsa, ona bu şekilde davranabilirsiniz. Bu, gizli anahtarı Azure Key Vault'da depolayıp Bicep şablonuna referans verilerek gerçekleştirilebilir. .NET Aspire Azure tümleştirmesi, Bicep şablonundan gelen çıktıları güvenli bir şekilde depolamak için bir desen sağlar. Bu desen, kaynakların keyVaultName'de gizli bilgileri depolamak için Azure Key Vault parametresini kullanmasına olanak tanır.

Gizli çıktıların güvenliğini sağlama konseptinin anlaşılmasına yardımcı olan bir örnek olarak aşağıdaki Bicep şablonunu göz önünde bulundurun.

param databaseAccountName string
param keyVaultName string

param databases array = []

@description('Tags that will be applied to all resources')
param tags object = {}

param location string = resourceGroup().location

var resourceToken = uniqueString(resourceGroup().id)

resource cosmosDb 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
    name: replace('${databaseAccountName}-${resourceToken}', '-', '')
    location: location
    kind: 'GlobalDocumentDB'
    tags: tags
    properties: {
        consistencyPolicy: { defaultConsistencyLevel: 'Session' }
        locations: [
            {
                locationName: location
                failoverPriority: 0
            }
        ]
        databaseAccountOfferType: 'Standard'
    }

    resource db 'sqlDatabases@2023-04-15' = [for name in databases: {
        name: '${name}'
        location: location
        tags: tags
        properties: {
            resource: {
                id: '${name}'
            }
        }
    }]
}

var primaryMasterKey = cosmosDb.listKeys(cosmosDb.apiVersion).primaryMasterKey

resource vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
    name: keyVaultName

    resource secret 'secrets@2023-07-01' = {
        name: 'connectionString'
        properties: {
            value: 'AccountEndpoint=${cosmosDb.properties.documentEndpoint};AccountKey=${primaryMasterKey}'
        }
    }
}

Önceki Bicep şablonu, diğer birkaç parametre arasında keyVaultName parametresini bekler. Ardından bir Azure Cosmos DB kaynağı tanımlar ve connectionString adı verilen sırrı Azure Key Vault içine saklar, bu da Cosmos DB örneğine tam bağlantı dizesini temsil eder. Bu gizli dizi bağlantı dizesi değerine erişmek için aşağıdaki kod parçacığını kullanabilirsiniz:

var cosmos = builder.AddBicepTemplate("cosmos", "../infra/cosmosdb.bicep")
    .WithParameter("databaseAccountName", "fallout-db")
    .WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)
    .WithParameter("databases", ["vault-33", "vault-111"]);

var connectionString =
    cosmos.GetSecretOutput("connectionString");

builder.AddProject<Projects.WebHook_Api>("api")
    .WithEnvironment(
        "ConnectionStrings__cosmos",
        connectionString);

Önceki kod parçacığında, cosmos Bicep şablonu builder'e referans olarak eklenir. Bicep şablonundan alınan connectionString gizli çıkış, bir değişkende depolanır. Gizli çıktı daha sonra ConnectionStrings__cosmos projesine bir ortam değişkeni (api) olarak geçirilir. Bu ortam değişkeni Cosmos DB örneğine bağlanmak için kullanılır.

Bu kaynak dağıtıldığında, temel alınan dağıtım mekanizması Azure Key Vault'den gizli öğeleri otomatik olarak referans alır. Gizli izolasyonu garanti etmek için .NET.NET Aspire her kaynak için bir Anahtar Kasası oluşturur.

Yayımcılık

Uygulamanızı yayımladığınızda, Azure tarafından üretilen sağlama Bicep, Azure Developer CLI aboneliğinizde Azure kaynaklarını oluşturmak için kullanılır. .NET .NET Aspire yayımlama bildirimioluşturur ve bu da yayımlama sürecinin önemli bir parçasıdır. Azure Developer CLI, Azure kaynaklarını yönetmek için bir dizi komut sağlayan bir komut satırı aracıdır.

Yayımlama ve dağıtım hakkında daha fazla bilgi için bkz. Azure Developer CLI kullanarak .NET Aspire projesini Azure Container Apps'a dağıtma (ayrıntılı kılavuz).