次の方法で共有

.NET 用 Microsoft Azure Resource Manager クライアント ライブラリ

  • [アーティクル]

Microsoft Azure Resource Managerは、Azure のデプロイと管理サービスです。 お使いの Azure アカウント内のリソースを作成、更新、および削除できる管理レイヤーを提供します。

このライブラリは、Microsoft Azure のリソース グループとリソース管理機能を提供します。

このライブラリは 、新しい Azure SDK ガイドラインに従い、多くのコア機能を提供します。

- Support MSAL.NET, Azure.Identity is out of box for supporting MSAL.NET.
- Support [OpenTelemetry](https://opentelemetry.io/) for distributed tracing.
- HTTP pipeline with custom policies.
- Better error-handling.
- Support uniform telemetry across all languages.

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用の Microsoft Azure リソース管理コア ライブラリをインストールします。

dotnet add package Azure.ResourceManager

前提条件

クライアントを認証する

認証されたクライアントを作成するための既定のオプションは、DefaultAzureCredential を使用することです。 すべての管理 API は同じエンドポイントを通過するため、リソースを操作するには、1 つの最上位レベル ArmClient のみを作成する必要があります。

Azure に対して認証を行い、 を ArmClient作成するには、次のコードを実行します。

using System;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Compute;
using Azure.ResourceManager.Resources;

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

クラスのその他の Azure.Identity.DefaultAzureCredential ドキュメント については、このドキュメントを参照してください。

主要な概念

Azure リソースの階層について

一般的なタスクの実行に必要なクライアントの数と、各クライアントが受け取る冗長パラメーターの数の両方を減らすために、Azure のオブジェクト階層を模倣するオブジェクト階層を SDK に導入しました。 SDK の各リソース クライアントには、スコープが既に適切なサブスクリプションとリソース グループに設定されている、その子のリソース クライアントにアクセスするためのメソッドが含まれています。

この目標を達成するために、Azure のすべてのリソースに 3 つの標準の種類を導入します。

[リソース]Resource.cs

このクラスは、詳細を [Resource]Data 型として公開する Data プロパティを含む完全なリソース クライアント オブジェクトを表します。 また、サブスクリプション ID やリソース名などのスコープ パラメーターを渡すことなく、そのリソースのすべての操作にアクセスすることもできます。 このリソース クラスは、リスト呼び出しの結果に対する操作を直接実行するのに便利です。これは、すべてが完全なリソース クライアントとして返されるためです。

ArmClient client = new ArmClient(new DefaultAzureCredential());
string resourceGroupName = "myResourceGroup";
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroups = subscription.GetResourceGroups();
ResourceGroupResource resourceGroup = await resourceGroups.GetAsync(resourceGroupName);
await foreach (VirtualMachineResource virtualMachine in resourceGroup.GetVirtualMachines())
{
    //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);
}

[Resource]Data.cs

このクラスは、特定のリソースを構成するモデルを表します。 通常、このクラスは HTTP GET などのサービス呼び出しからの応答データであり、基になるリソースに関する詳細を提供します。 以前は、このクラスは Model クラスによって表されていました。

[Resource]Collection.cs

このクラスは、特定の親リソースに属するリソースのコレクションに対して実行できる操作を表します。 このクラスは、ほとんどの論理コレクション操作を提供します。

コレクションの動作 コレクション メソッド
反復/リスト GetAll()
インデックス Get(文字列名)
追加 CreateOrUpdate(文字列名, [Resource]Data データ)
Contains Exists(文字列名)

ほとんどの場合、親が ResourceGroup になります。 たとえば、Subnet は VirtualNetwork の子であり、ResourceGroup は Subscription の子です。

まとめ

会社で、すべての仮想マシンに所有者のタグを付ける必要があるとしましょう。 私たちは、特定のリソース グループ内で不足しているすべての仮想マシンにタグを追加するプログラムの作成を任せられました。

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

// Next we get a resource group object
// ResourceGroupResource is a [Resource] object from above
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroups = subscription.GetResourceGroups();
ResourceGroupResource resourceGroup = await resourceGroups.GetAsync("myRgName");

// Next we get the collection for the virtual machines
// vmCollection is a [Resource]Collection object from above
VirtualMachineCollection virtualMachines = resourceGroup.GetVirtualMachines();

// Next we loop over all vms in the collection
// Each vm is a [Resource] object from above
await foreach (VirtualMachineResource virtualMachine in virtualMachines)
{
   // We access the [Resource]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", "tagValue");
   }
}

構造化リソース識別子

リソース ID にはリソース自体に関する有用な情報が含まれていますが、プレーンな文字列であり、解析が必要です。 独自の解析ロジックを実装する代わりに、 の解析を行うオブジェクトをnew ResourceIdentifier("myid");使用ResourceIdentifierできます。

例: ResourceIdentifier オブジェクトを使用した ID の解析

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

リソース識別子による既存のリソースの管理

管理クライアント ライブラリを使用する場合、既に存在するリソースで操作を実行することは一般的なユース ケースです。 このシナリオでは、通常、文字列として使用するリソースの識別子を指定します。 新しいオブジェクト階層は、プロビジョニングと特定の親のスコープ内での作業に適していますが、この特定のシナリオに関しては最も効率的ではありません。

オブジェクトにアクセスし、ID を使用して直接管理する AvailabilitySet 方法の例を次に示します。

ResourceIdentifier id = new ResourceIdentifier("/subscriptions/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resourceGroups/workshop2021-rg/providers/Microsoft.Compute/availabilitySets/ws2021availSet");
// We construct a new client to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the collection of subscriptions
SubscriptionCollection subscriptions = client.GetSubscriptions();
// Next we get the specific subscription this resource belongs to
SubscriptionResource subscription = await subscriptions.GetAsync(id.SubscriptionId);
// Next we get the collection of resource groups that belong to that subscription
ResourceGroupCollection resourceGroups = subscription.GetResourceGroups();
// Next we get the specific resource group this resource belongs to
ResourceGroupResource resourceGroup = await resourceGroups.GetAsync(id.ResourceGroupName);
// Next we get the collection of availability sets that belong to that resource group
AvailabilitySetCollection availabilitySets = resourceGroup.GetAvailabilitySets();
// Finally we get the resource itself
// Note: for this last step in this example, Azure.ResourceManager.Compute is needed
AvailabilitySetResource availabilitySet = await availabilitySets.GetAsync(id.Name);

この方法では、Azure に対して多くのコードと 3 つの API 呼び出しが必要でした。 提供されている拡張メソッドをクライアント自体で使用すると、同じことを少ないコードで、API 呼び出しを必要とせずに行うことができます。 これらの拡張メソッドを使用すると、リソース識別子を渡し、スコープが設定されているリソース クライアントを取得できます。 返されるオブジェクトは、上記の [リソース] です。データを取得するために Azure に到達していないので、Data プロパティは null になります。

そのため、上の例は、最終的に次のようになります。

ResourceIdentifier resourceId = new ResourceIdentifier("/subscriptions/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resourceGroups/workshop2021-rg/providers/Microsoft.Compute/availabilitySets/ws2021availSet");
// We construct a new client to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the AvailabilitySetResource resource client from the client
// 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
// 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);

また、各リソースを構成 ResourceIdentifier する部分のみがわかっている場合は、それらの部分から完全な文字列を構築するための静的メソッドを提供するオプションも提供します。 上記の例は次のようになります。

string subscriptionId = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
string resourceGroupName = "workshop2021-rg";
string availabilitySetName = "ws2021availSet";
ResourceIdentifier resourceId = AvailabilitySetResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, availabilitySetName);
// We construct a new client to work with
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Next we get the AvailabilitySetResource resource client from the client
// 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
// 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);

[Resource] が存在するかどうかを確認する

取得するリソースが存在するかどうかがわからない場合、またはリソースが存在する場合にチェックしたい場合は、任意の [Resource]Collection クラスから呼び出すことができるメソッドを使用Exists()できます。

Exists() 指定 ExistsAsync() されたリソースが存在しない場合、bool は false になる場所を返 Response<bool> します。 これらのメソッドはどちらも、基になる未加工の応答に引き続きアクセスできます。

これらのメソッドが導入される前に、 をキャッチ RequestFailedException し、404 の状態コードを調べる必要があります。

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroups = subscription.GetResourceGroups();
string resourceGroupName = "myRgName";

try
{
    ResourceGroupResource resourceGroup = await resourceGroups.GetAsync(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.");
}

ここで、これらの便利なメソッドを使用して、次のコードを実行できます。

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroups = subscription.GetResourceGroups();
string resourceGroupName = "myRgName";

bool exists = await resourceGroups.ExistsAsync(resourceGroupName);

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 resourceGroups.GetAsync(resourceGroupName);
}
else
{
    Console.WriteLine($"Resource Group {resourceGroupName} does not exist.");
}

例

リソース グループを作成する

// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
// Now we get a ResourceGroupResource collection for that subscription
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroups = 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);
ArmOperation<ResourceGroupResource> operation = await resourceGroups.CreateOrUpdateAsync(WaitUntil.Completed, resourceGroupName, resourceGroupData);
ResourceGroupResource resourceGroup = operation.Value;

すべてのリソース グループの一覧表示

// First, initialize the ArmClient and get the default subscription
ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
// Now we get a ResourceGroupResource collection for that subscription
ResourceGroupCollection resourceGroups = subscription.GetResourceGroups();
// We can then iterate over this collection to get the resources in the collection
await foreach (ResourceGroupResource resourceGroup in resourceGroups)
{
    Console.WriteLine(resourceGroup.Data.Name);
}

リソース グループの更新

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

リソース グループの削除

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource subscription = await client.GetDefaultSubscriptionAsync();
ResourceGroupCollection resourceGroups = subscription.GetResourceGroups();
string resourceGroupName = "myRgName";
ResourceGroupResource resourceGroup = await resourceGroups.GetAsync(resourceGroupName);
await resourceGroup.DeleteAsync(WaitUntil.Completed);

GenericResource リストを取得する

ArmClient client = new ArmClient(new DefaultAzureCredential());
SubscriptionResource sub = client.GetDefaultSubscription();
AsyncPageable<GenericResource> networkAndVmWithTestInName = sub.GetGenericResourcesAsync(
    // Set filter to only return virtual network and virtual machine resource with 'test' in the name
    filter: "(resourceType eq 'Microsoft.Network/virtualNetworks' or resourceType eq 'Microsoft.Compute/virtualMachines') and substringof('test', name)",
    // Include 'createdTime' and 'changeTime' properties in the returned data
    expand: "createdTime,changedTime"
    );

int count = 0;
await foreach (var res in networkAndVmWithTestInName)
{
    Console.WriteLine($"{res.Id.Name} in resource group {res.Id.ResourceGroupName} created at {res.Data.CreatedOn} and changed at {res.Data.ChangedOn}");
    count++;
}
Console.WriteLine($"{count} resources found");

GenericResource の作成

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

var subnetName = "samplesubnet";
var addressSpaces = new Dictionary<string, object>()
{
    { "addressPrefixes", new List<string>() { "10.0.0.0/16" } }
};
var subnet = new Dictionary<string, object>()
{
    { "name", subnetName },
    { "properties", new Dictionary<string, object>()
        {
            { "addressPrefix", "10.0.1.0/24" }
        }
    }
};
var subnets = new List<object>() { subnet };
var data = new GenericResourceData(AzureLocation.EastUS)
{
    Properties = BinaryData.FromObjectAsJson(new Dictionary<string, object>()
    {
        { "addressSpace", addressSpaces },
        { "subnets", subnets }
    })
};
ResourceIdentifier id = new ResourceIdentifier("/subscriptions/{subscription_id}/resourceGroups/{resourcegroup_name}/providers/Microsoft.Network/virtualNetworks/{vnet_name}");

var createResult = await client.GetGenericResources().CreateOrUpdateAsync(WaitUntil.Completed, id, data);
Console.WriteLine($"Resource {createResult.Value.Id.Name} in resource group {createResult.Value.Id.ResourceGroupName} created");

GenericResource の更新

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

var subnetName = "samplesubnet";
var addressSpaces = new Dictionary<string, object>()
{
    { "addressPrefixes", new List<string>() { "10.0.0.0/16" } }
};
var subnet = new Dictionary<string, object>()
{
    { "name", subnetName },
    { "properties", new Dictionary<string, object>()
        {
            { "addressPrefix", "10.0.1.0/24" }
        }
    }
};
var subnets = new List<object>() { subnet };
var data = new GenericResourceData(AzureLocation.EastUS)
{
    Properties = BinaryData.FromObjectAsJson(new Dictionary<string, object>()
    {
        { "addressSpace", addressSpaces },
        { "subnets", subnets }
    })
};
ResourceIdentifier id = new ResourceIdentifier("/subscriptions/{subscription_id}/resourceGroups/{resourcegroup_name}/providers/Microsoft.Network/virtualNetworks/{vnet_name}");

var createResult = await client.GetGenericResources().CreateOrUpdateAsync(WaitUntil.Completed, id, data);
Console.WriteLine($"Resource {createResult.Value.Id.Name} in resource group {createResult.Value.Id.ResourceGroupName} updated");

GenericResourc タグを更新する

ArmClient client = new ArmClient(new DefaultAzureCredential());
ResourceIdentifier id = new ResourceIdentifier("/subscriptions/{subscription_id}/resourceGroups/{resourcegroup_name}/providers/Microsoft.Network/virtualNetworks/{vnet_name}");
GenericResource resource = client.GetGenericResources().Get(id).Value;

GenericResourceData updateTag = new GenericResourceData(AzureLocation.EastUS);
updateTag.Tags.Add("tag1", "sample-for-genericresource");
ArmOperation<GenericResource> updateTagResult = await resource.UpdateAsync(WaitUntil.Completed, updateTag);

Console.WriteLine($"Resource {updateTagResult.Value.Id.Name} in resource group {updateTagResult.Value.Id.ResourceGroupName} updated");

GenericResource を取得する

ArmClient client = new ArmClient(new DefaultAzureCredential());
ResourceIdentifier id = new ResourceIdentifier("/subscriptions/{subscription_id}/resourceGroups/{resourcegroup_name}/providers/Microsoft.Network/virtualNetworks/{vnet_name}");

Response<GenericResource> getResultFromGenericResourceCollection = await client.GetGenericResources().GetAsync(id);
Console.WriteLine($"Resource {getResultFromGenericResourceCollection.Value.Id.Name} in resource group {getResultFromGenericResourceCollection.Value.Id.ResourceGroupName} got");

GenericResource resource = getResultFromGenericResourceCollection.Value;
Response<GenericResource> getResultFromGenericResource = await resource.GetAsync();
Console.WriteLine($"Resource {getResultFromGenericResource.Value.Id.Name} in resource group {getResultFromGenericResource.Value.Id.ResourceGroupName} got");

GenericResource が存在するかどうかを確認する

ArmClient client = new ArmClient(new DefaultAzureCredential());
ResourceIdentifier id = new ResourceIdentifier("/subscriptions/{subscription_id}/resourceGroups/{resourcegroup_name}/providers/Microsoft.Network/virtualNetworks/{vnet_name}");

bool existResult = await client.GetGenericResources().ExistsAsync(id);
Console.WriteLine($"Resource exists: {existResult}");

GenericResource の削除

ArmClient client = new ArmClient(new DefaultAzureCredential());
ResourceIdentifier id = new ResourceIdentifier("/subscriptions/{subscription_id}/resourceGroups/{resourcegroup_name}/providers/Microsoft.Network/virtualNetworks/{vnet_name}");
GenericResource resource = client.GetGenericResources().Get(id).Value;

var deleteResult = await resource.DeleteAsync(WaitUntil.Completed);
Console.WriteLine($"Resource deletion response status code: {deleteResult.WaitForCompletionResponse().Status}");

より詳細な例については、サンプルを用意していますので、ご覧ください。

Azure Resource Manager テスト

テストを実行するには: dotnet test

コード カバレッジを使用してテストを実行し、HTML レポートを自動生成するには: dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura

カバレッジ レポートは、表示用の html 形式で azure-proto-core-test に対する相対パスに/coverage 配置されます

レポートは、適切なビューアー プラグインを使用して VS または VsCode を表示することもできます

実行中に、コマンド ラインに簡潔なレポートも表示されます。

1 つのファイルまたはテストを使用してテストを実行する

コード カバレッジを使用してテストを実行し、1 つのテストだけで HTML レポートを自動生成するには: dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura --filter <test-to-run>

トラブルシューティング

次のステップ

その他のサンプル コード

その他のドキュメント

古い SDK から移行する場合は、こちらの移行ガイドをチェックしてください。

Microsoft Azure SDK の詳細については、 こちらの Web サイトを参照してください。

共同作成

このリポジトリへの投稿の詳細については、 投稿ガイドを参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベルやコメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順に従ってください。 このアクションは、CLA を使用してすべてのリポジトリで 1 回だけ実行する必要があります。

このプロジェクトは、「Microsoft のオープン ソースの倫理規定」を採用しています。 詳しくは、倫理規定についてよくある質問に関する記事を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。