İngilizce dilinde oku

Aracılığıyla paylaş

.NET için Azure SDK'sını kullanarak kaynak yönetimi

  • Makale

.NET için Azure SDK yönetim düzlemi kitaplıkları, .NET uygulamalarının içinden Azure kaynakları oluşturmanıza, sağlamanıza ve yönetmenize yardımcı olur. Tüm Azure hizmetlerinin karşılık gelen yönetim kitaplıkları vardır.

Yönetim kitaplıklarıyla (örneğin, Azure.ResourceManager.Compute) Azure.ResourceManagerile başlayan ad alanlarıyla, Azure portalı, Azure CLI veya diğer kaynak yönetimi araçları aracılığıyla gerçekleştirebileceğiniz görevlerin aynısını gerçekleştirmek için yapılandırma ve dağıtım programları yazabilirsiniz.

Bu paketler, aşağıdakiler dahil olmak üzere tüm Azure SDK'ları arasında paylaşılan temel özellikler sağlayan yeni Azure SDK yönergelerini izler:

  • Sezgisel Azure Kimlik kitaplığı.
  • Özel ilkeleri olan bir HTTP işlem hattı.
  • Hata yönetimi.
  • Dağıtılmış izleme.

Not

Bazı paketlerin hala yayın öncesi sürüm olduğunu fark edebilirsiniz. Ek Azure servislerinin yönetim düzlemi kütüphanelerinin aşamalı sürümleri sürecine başlanmıştır. Belirli bir Azure kaynağı için kararlı bir sürüm paketi arıyorsanız ve şu anda sadece bir yayın öncesi sürüm mevcutsa, lütfen Azure SDK for .NET GitHub deposundabir sorun oluşturun.

Kullanmaya başlama

Önkoşullar

Paketi yükleme

.NET için Azure Identity ve Azure kaynak yönetimi NuGet paketlerini yükleyin. Mesela:

PowerShell 
Install-Package Azure.Identity
Install-Package Azure.ResourceManager
Install-Package Azure.ResourceManager.Resources
Install-Package Azure.ResourceManager.Compute
Install-Package Azure.ResourceManager.Network

İstemcinin kimliğini doğrulama

Kimliği doğrulanmış istemci oluşturmak için varsayılan seçenek DefaultAzureCredentialkullanmaktır. Tüm yönetim API'leri aynı uç noktadan geçtiğinden kaynaklarla etkileşim kurmak için yalnızca bir üst düzey ArmClient oluşturulması gerekir.

Azure ile kimlik doğrulaması yapmak ve ArmClientoluşturmak için verilen ArmClient kimlik bilgilerini oluşturun:

C# 
using Azure.Identity;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;

// Code omitted for brevity

ArmClient client = new ArmClient(new DefaultAzureCredential());

Azure.Identity.DefaultAzureCredential sınıfı hakkında daha fazla bilgi için DefaultAzureCredential Classbölümüne bakın.

Yönetim SDK'sı Hızlı Başvuru Kılavuzu

.NET için Azure yönetim SDK'sını kullanmaya başlamak için tipik bir Azure service bus ad alanı oluşturma/listeleme/güncelleştirme/silme göreviniz olduğunu düşünün:

  1. Üzerinde çalışmak istediğiniz abonelikte ve kaynak grubunda kimlik doğrulaması yapın.
C# 
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ServiceBus;

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = client.GetDefaultSubscription();
ResourceGroupResource resourceGroup =
    client.GetDefaultSubscription().GetResourceGroup(resourceGroupName);
  1. Azure kaynağınızı yönetmek için ilgili yöntemi bulun.
Operasyon Yöntem
Kaynak tanımlayıcısı olan bir kaynak alma client.GetServiceBusQueueResource(ResourceIdentifier resourceIdentifier)
Liste resourceGroup.GetServiceBusNamespaces()
Dizin resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName)
Ekle/Güncelleştir resourceGroup.GetServiceBusNamespaces().CreateOrUpdate(Azure.WaitUntil waitUntil, string name, ServiceBusNamespaceData data)
İçerir resourceGroup.GetServiceBusNamespaces().Exists(string servicebusNamespaceName)
Silmek client.GetServiceBusQueueResource(ResourceIdentifior resourceIdentifior).Delete() veya resourceGroup.GetServiceBusNamespace(string servicebusNamespaceName).Delete()

Kaynak grubunun kendisi de dahil olmak üzere tüm Azure kaynaklarının yukarıdaki örneğe benzer bir kod kullanılarak ilgili yönetim SDK'sı tarafından yönetilebileceğini unutmayın. Doğru Azure yönetim SDK paketini bulmak için adı aşağıdaki kalıpta olan paketleri arayın: Azure.ResourceManager.{ResourceProviderName}.

ResourceIdentifier hakkında daha fazla bilgi edinmek için lütfen Yapılandırılmış Kaynak Tanımlayıcısıbakın.

Temel kavramlar

Azure Kaynak Hiyerarşisi'nin anlaşılması

Ortak görevleri gerçekleştirmek için gereken istemci sayısını ve bu istemcilerin her birinin sahip olduğu yedekli parametre sayısını azaltmak için SDK'da Azure'daki nesne hiyerarşisini taklit eden bir nesne hiyerarşisi kullanıma sunulmuştur. SDK'daki her kaynak istemcisi, uygun abonelik ve kaynak grubu kapsamında olan alt kaynakların istemcilerine erişim yöntemlerine sahiptir.

Bunu başarmak için Azure'daki tüm kaynaklar için üç standart tür sunuyoruz:

Kaynak {ResourceName} sınıfı

Bu tür, ayrıntıları {ResourceName}Data türü olarak gösteren bir Data özelliği içeren tam kaynak istemci nesnesini temsil eder. Ayrıca abonelik kimliği veya kaynak adı gibi kapsam parametrelerini geçirmeye gerek kalmadan bu kaynaktaki tüm işlemlere erişebilir. Artık her şey tam bir kaynak istemcisi olarak döndürüldüğü için, liste çağrılarının sonucunda işlemleri doğrudan yürütmek kolaylaşır.

C# 
ArmClient client = new ArmClient(new DefaultAzureCredential());
string resourceGroupName = "myResourceGroup";
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
await foreach (VirtualMachineResource virtualMachine in resourceGroup.GetVirtualMachinesAsync())
{
    //previously we would have to take the resourceGroupName and the vmName from the vm object
    //and pass those into the powerOff method as well as we would need to execute that on a separate compute client
    await virtualMachine.PowerOffAsync(WaitUntil.Completed);
}

{ResourceName}Data sınıfını

Bu tür, belirli bir kaynağı oluşturan modeli temsil eder. Bu genellikle HTTP GET gibi bir hizmet çağrısından alınan yanıt verileridir ve temel alınan kaynakla ilgili ayrıntıları sağlar. Daha önce bu, Model sınıfıyla temsil edilirdi.

{ResourceName}Collection sınıfını

Bu tür, belirli bir üst kaynağa ait bir kaynak koleksiyonunda gerçekleştirebileceğiniz işlemleri temsil eder. Bu nesne, mantıksal toplama işlemlerinin çoğunu sağlar.

Koleksiyon Davranışı Koleksiyon Yöntemi
Yinele/Listele GetAll()
Dizin Get(dize adı)
Ekle CreateOrUpdate(Azure.WaitUntil waitUntil, dize adı, {ResourceName}Veri verileri)
İçerir Exists(dize adı)

Çoğu durumda kaynağın üst öğesi ResourceGroup'dir, ancak bazı durumlarda kaynağın kendisi alt kaynağa sahiptir; örneğin, Alt AğVirtualNetworkalt öğesidir. ResourceGroup kendisi bir Aboneliğin alt öğesidir

Hepsini bir araya getirmek

Şirketimizin tüm sanal makinelerin sahibiyle etiketlenmesini şart koştuğunu düşünün. Etiketi belirli bir kaynak grubundaki eksik sanal makinelere eklemek için bir program yazmakla görevlendirildik.

C# 
// First we construct our armClient
ArmClient client = new ArmClient(new DefaultAzureCredential());

// Next we get a resource group object
// ResourceGroup is a {ResourceName}Resource object from above
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup =
   await subscription.GetResourceGroupAsync("myRgName");

// Next we get the collection for the virtual machines
// vmCollection is a {ResourceName}Collection object from above
VirtualMachineCollection virtualMachineCollection = await resourceGroup.GetVirtualMachines();

// Next we loop over all vms in the collection
// Each vm is a {ResourceName}Resource object from above
await foreach(VirtualMachineResource virtualMachine in virtualMachineCollection)
{
   // We access the {ResourceName}Data properties from vm.Data
   if(!virtualMachine.Data.Tags.ContainsKey("owner"))
   {
       // We can also access all operations from vm since it is already scoped for us
       await virtualMachine.AddTagAsync("owner", GetOwner());
   }
}

Yapılandırılmış Kaynak Tanımlayıcısı

Kaynak kimlikleri kaynağın kendisi hakkında yararlı bilgiler içerir, ancak ayrıştırılması gereken düz dizelerdir. Kendi ayrıştırma mantığınızı uygulamak yerine, ayrıştırma işlemini sizin yerinize yapacak bir ResourceIdentifier nesnesi kullanabilirsiniz.

Örnek: ResourceIdentifier nesnesi kullanarak kimlik ayrıştırma

C# 
string resourceId = "/subscriptions/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resourceGroups/workshop2021-rg/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet";
ResourceIdentifier id = new ResourceIdentifier(resourceId);
Console.WriteLine($"Subscription: {id.SubscriptionId}");
Console.WriteLine($"ResourceGroup: {id.ResourceGroupName}");
Console.WriteLine($"Vnet: {id.Parent.Name}");
Console.WriteLine($"Subnet: {id.Name}");

Ancak, bu özelliklerden bazılarının null olabileceğini unutmayın. Genellikle kaynak kimliğinin türünü kimlik dizesinin kendisine göre anlayabilirsiniz. Ancak emin değilseniz özelliklerin null olup olmadığını denetleyin.

Örnek: Kaynak Tanımlayıcı Oluşturucu

Saf bir string'den resourceId'ı el ile oluşturmak istemeyebilirsiniz. Her {ResourceName}Resource sınıfı, kaynak tanımlayıcı dizesini oluşturmanıza yardımcı olabilecek statik bir yönteme sahiptir.

C# 
ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "resourceGroupName",
        "resourceName");

Mevcut kaynakları yönetme

Yönetim istemci kitaplıkları kullanılırken zaten var olan kaynaklarda işlem gerçekleştirmek yaygın bir kullanım örneğidir. Bu senaryoda, genellikle dize olarak üzerinde çalışmak istediğiniz kaynağın tanımlayıcısına sahipsinizdir. Yeni nesne hiyerarşisi, belirli bir üst unsur kapsamında tedarik ve çalışma için harika olsa da, bu özel durum söz konusu olduğunda en verimli yöntem değildir.

Bir AvailabilitySetResource nesnesine nasıl erişebileceğinize ve doğrudan kaynak tanımlayıcısıyla nasıl yönetebileceğinize bir örnek aşağıda verilmiştir:

C# 
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.Compute;
using System;
using System.Threading.Tasks;

// Code omitted for brevity

ResourceIdentifier subscriptionId =
    SubscriptionResource.CreateResourceIdentifier("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");

ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        subscriptionId.SubscriptionId,
        "resourceGroupName",
        "resourceName");

// We construct a new armClient to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the specific subscription this resource belongs to
SubscriptionResource subscription = client.GetSubscriptionResource(subscriptionId);
// Next we get the specific resource group this resource belongs to
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceId.ResourceGroupName);
// Finally we get the resource itself
// Note: for this last step in this example, Azure.ResourceManager.Compute is needed
AvailabilitySetResource availabilitySet = await resourceGroup.GetAvailabilitySetAsync(resourceId.Name);

Bu yaklaşım çok fazla kod gerektiriyor ve Azure'a üç API çağrısı yapılıyor. Aynı işlem daha az kodla ve istemcide sağladığımız uzantı yöntemleri kullanılarak API çağrıları olmadan yapılabilir. Bu uzantı yöntemleri, bir kaynak tanımlayıcısı geçirmenize ve kapsamlı bir kaynak istemcisi almanıza olanak sağlar. Döndürülen nesne bir {ResourceName}Resource. Verileri almak için Azure'a henüz ulaşmadığından, Data özelliğini çağırmak özel durum oluşturur; kaynak örneğinin veri içerdiğini söylemek için HasData özelliğini kullanabilir veya kaynak verilerini almak için kaynakta Get veya GetAsync yöntemini çağırabilirsiniz.

Bu nedenle, önceki örnek şu şekilde görünür:

C# 
ResourceIdentifier resourceId =
    AvailabilitySetResource.CreateResourceIdentifier(
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "resourceGroupName",
        "resourceName");
// We construct a new armClient to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the AvailabilitySet resource client from the armClient
// The method takes in a ResourceIdentifier but we can use the implicit cast from string
AvailabilitySetResource availabilitySet = client.GetAvailabilitySetResource(resourceId);
// At this point availabilitySet.Data will be null and trying to access it will throw exception
// If we want to retrieve the objects data we can simply call get
availabilitySet = await availabilitySet.GetAsync();
// we now have the data representing the availabilitySet
Console.WriteLine(availabilitySet.Data.Name);

Kaynak olup olmadığını denetleme

Almak istediğiniz kaynağın var olup olmadığından emin değilseniz veya yalnızca var olup olmadığını denetlemek istiyorsanız, herhangi bir {ResourceName}Collection sınıfından çağrılabilen Exists() veya ExistsAsync() yöntemlerini kullanabilirsiniz.

Exists() bir Response<bool> döndürürken, ExistsAsync() asenkron versiyonu bir Task<Response<bool>>döndürür. Response<bool> nesnesinde, bir kaynağın var olup olmadığını denetlemek için Value özelliğini ziyaret edebilirsiniz. Kaynak mevcut değilse Valuefalse'dir ve bunun tersi de geçerlidir.

Paketlerin önceki sürümlerinde RequestFailedException yakalamanız ve 404 durum kodunu incelemeniz gerekirdi. Bu yeni API ile bunun geliştirici üretkenliğini artırabileceğini ve kaynak erişimini iyileştirebileceğini umuyoruz.

C# 
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";

try
{
    ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
    // At this point, we are sure that myRG is a not null Resource Group, so we can use this object to perform any operations we want.
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine($"Resource Group {resourceGroupName} does not exist.");
}

Şimdi bu kolaylık yöntemleriyle aşağıdakileri yapabiliriz.

C# 
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";

bool exists = await subscription.GetResourceGroups().ExistsAsync(resourceGroupName).Value;

if (exists)
{
    Console.WriteLine($"Resource Group {resourceGroupName} exists.");

    // We can get the resource group now that we know it exists.
    // This does introduce a small race condition where resource group could have been deleted between the check and the get.
    ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
}
else
{
    Console.WriteLine($"Resource Group {rgName} does not exist.");
}

Örnekler

Kaynak grubu oluşturma

C# 
// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Now we get a ResourceGroup collection for that subscription
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroupCollection = subscription.GetResourceGroups();

// With the collection, we can create a new resource group with an specific name
string resourceGroupName = "myRgName";
AzureLocation location = AzureLocation.WestUS2;
ResourceGroupData resourceGroupData = new ResourceGroupData(location);
ResourceGroupResource resourceGroup = (await resourceGroupCollection.CreateOrUpdateAsync(resourceGroupName, resourceGroupData)).Value;

Tüm kaynak gruplarını listeleme

C# 
// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
// Now we get a ResourceGroup collection for that subscription
ResourceGroupCollection resourceGroupCollection = subscription.GetResourceGroups();
// With GetAllAsync(), we can get a list of the resources in the collection
await foreach (ResourceGroupResource resourceGroup in resourceGroupCollection)
{
    Console.WriteLine(resourceGroup.Data.Name);
}

Kaynak grubunu güncelleştirme

C# 
// Note: Resource group named 'myRgName' should exist for this example to work.
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
resourceGroup = await resourceGroup.AddTagAsync("key", "value");

Kaynak grubunu silme

C# 
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
string resourceGroupName = "myRgName";
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync(resourceGroupName);
await resourceGroup.DeleteAsync();

Daha ayrıntılı örnekler için mevcut örneklerine göz atın.

Sorun giderme

  • Raporlamaya yönelik bir hatanız veya öneriniz varsa GitHub sorunlarını aracılığıyla bir sorun oluşturun ve soruna "Önizleme" etiketini eklediğinizden emin olun.
  • Yardıma ihtiyacınız varsa önceki sorularıdenetleyin veya Azure ve .NET etiketlerini kullanarak StackOverflow'da yeni sorular sorun.
  • Kimlik doğrulamasıyla ilgili sorun yaşıyorsanız, DefaultAzureCredential belgelerine bakın.

Sonraki adımlar

Daha fazla örnek kod

Ek Belgeler

Eski SDK'dan bu önizlemeye geçiş gerçekleştiriyorsanız, bu Geçiş kılavuzuna göz atın.

Azure SDK hakkında daha fazla bilgi için bkz. Azure SDK Sürümleri.