C# AWS CDK での の操作

.NET は、 用に完全にサポートされているクライアント言語であり AWS CDK 、安定していると見なされます。C# は、例とサポートを提供する主要な .NET 言語です。Visual Basic や F# など、他の .NET 言語の AWS CDK アプリケーションを作成することを選択できますが、これらの言語を CDK で使用するためのサポート AWS は限られています。

Visual Studio、Visual Studio Code、 dotnet コマンド、 NuGet パッケージマネージャーなどの使い慣れたツールを使用して、C# で AWS CDK アプリケーションを開発できます。 AWS コンストラクトライブラリで構成されるモジュールは、nuget.org 経由で配布されます。

Windows で Visual Studio 2019 (任意のエディション) を使用して、C# で AWS CDK アプリケーションを開発することをお勧めします。

C# の開始方法

を使用するには AWS CDK、 AWS アカウントと認証情報が必要です。また、Node.js と AWS CDK Toolkit がインストールされている必要があります。の開始方法 AWS CDK を参照してください。

C# AWS CDK アプリケーションには .NET Core v3.1 以降が必要です。こちらは から入手できます。

.NET ツールチェーンにはdotnet、.NET アプリケーションを構築および実行し、 NuGet パッケージを管理するためのコマンドラインツールである が含まれています。Visual Studio で主に作業する場合でも、このコマンドはバッチ操作や AWS 構成ライブラリパッケージのインストールに役立ちます。

「プロジェクトの作成」

空のディレクトリcdk initで を呼び出して、新しい AWS CDK プロジェクトを作成します。--language オプションを使用して、 を指定しますcsharp。

mkdir my-project
cd my-project
cdk init app --language csharp

cdk init は、プロジェクトフォルダの名前を使用して、クラス、サブフォルダ、ファイルなど、プロジェクトのさまざまな要素に名前を付けます。フォルダ名のハイフンはアンダースコアに変換されます。ただし、名前は C# 識別子の形式に従う必要があります。例えば、数字で開始したり、スペースを含めたりしないでください。

結果のプロジェクトには、 Amazon.CDK.Lib NuGet パッケージへの参照が含まれます。とその依存関係は によって自動的にインストールされます NuGet。

AWS コンストラクトライブラリモジュールの管理

.NET エコシステムは NuGet パッケージマネージャーを使用します。コアクラスとすべての安定したサービスコンストラクトを含むメイン CDK パッケージは、 ですAmazon.CDK.Lib。新しい機能が開発中である実験モジュールは、 のように名前が付けられAmazon.CDK.AWS.SERVICE-NAME.Alpha、サービス名は AWS または Amazon プレフィックスのない短縮名です。例えば、 AWS IoT モジュールの NuGet パッケージ名は ですAmazon.CDK.AWS.IoT.Alpha。必要なパッケージが見つからない場合は、Nuget.org を検索します。

一部のサービスの AWS 「コンストラクトライブラリ」のサポートは、複数のモジュールにあります。例えば、 には という名前の 2 番目のモジュール AWS IoT がありますAmazon.CDK.AWS.IoT.Actions.Alpha。

ほとんどの AWS CDK アプリで必要となる AWS CDKのメインモジュールは、C# コードで としてインポートされますAmazon.CDK。 AWS コンストラクトライブラリのさまざまなサービスのモジュールは、 にありますAmazon.CDK.AWS。例えば、Amazon S3 モジュールの名前空間は ですAmazon.CDK.AWS.S3。

CDK コアコンストラクトと、各 C# ソースファイルで使用する AWS サービスごとに C# usingディレクティブを記述することをお勧めします。名前の競合を解決するには、名前空間またはタイプにエイリアスを使用する方が便利な場合があります。using ステートメントを使用せずに、タイプの名前 (名前空間を含む) をいつでも使用できます。

での依存関係の管理 C#

C# AWS CDK apps では、依存関係の管理に を使用します NuGet。 NuGet には、主に同等のインターフェイスが 4 つあります。ニーズと作業スタイルに合ったものを使用してください。Paket MyGetや などの互換性のあるツールを使用したり、.csprojファイルを直接編集したりすることもできます。

NuGet では、依存関係のバージョン範囲を指定することはできません。すべての依存関係は特定のバージョンに固定されます。

依存関係を更新すると、Visual Studio は NuGet を使用して、次回ビルド時に各パッケージの指定されたバージョンを取得します。Visual Studio を使用していない場合は、 dotnet restore コマンドを使用して依存関係を更新します。

プロジェクトファイルの直接編集

プロジェクトの .csproj ファイルには、依存関係を<PackageReference要素としてリストする <ItemGroup>コンテナが含まれています。

<ItemGroup>
    <PackageReference Include="Amazon.CDK.Lib" Version="2.14.0" />
    <PackageReference Include="Constructs" Version="%constructs-version%" />
</ItemGroup>

Visual Studio NuGet GUI

Visual Studio の NuGet ツールには、ツール > NuGet パッケージマネージャー > ソリューションの NuGet パッケージの管理からアクセスできます。参照タブを使用して、インストールする AWS 構成ライブラリパッケージを検索します。モジュールのプレリリースバージョンを含む目的のバージョンを選択し、開いているプロジェクトに追加できます。

更新ページを見て、パッケージの新しいバージョンをインストールします。

NuGet コンソール

NuGet コンソールは、Visual Studio プロジェクトのコンテキスト NuGet で動作する PowerShellベースの インターフェイスです。Visual Studio で開くには、ツール > NuGet パッケージマネージャー > パッケージマネージャーコンソール を選択します。このツールの使用の詳細については、Visual Studio の「パッケージマネージャーコンソールを使用したパッケージのインストールと管理」を参照してください。

dotnet コマンド

dotnet コマンドは、Visual Studio C# プロジェクトを操作するための主要なコマンドラインツールです。Windows コマンドプロンプトから呼び出すことができます。多くの機能の中で、 dotnetは Visual Studio プロジェクトに依存関係を追加できます NuGet。

Visual Studio プロジェクト (.csproj) ファイルと同じディレクトリにいると仮定して、次のようなコマンドを実行してパッケージをインストールします。メイン CDK ライブラリはプロジェクトの作成時に含まれているため、実験的なモジュールを明示的にインストールするだけで済みます。実験モジュールでは、明示的なバージョン番号を指定する必要があります。

dotnet add package Amazon.CDK.AWS.IoT.Alpha -v VERSION-NUMBER

別のディレクトリからコマンドを発行できます。これを行うには、 addキーワードの後に、プロジェクトファイル、またはそれを含むディレクトリへのパスを含めます。次の例では、プロジェクトのメインディレクトリにいることを前提 AWS CDK としています。

dotnet add src/PROJECT-DIR package Amazon.CDK.AWS.IoT.Alpha -v VERSION-NUMBER

パッケージの特定のバージョンをインストールするには、 -vフラグと目的のバージョンを含めます。

パッケージを更新するには、インストールに使用したのと同じdotnet addコマンドを発行します。実験的なモジュールの場合は、ここでも明示的なバージョン番号を指定する必要があります。

dotnet コマンドを使用したパッケージの管理の詳細については、「dotnet CLI を使用したパッケージのインストールと管理」を参照してください。

nuget コマンド

nuget コマンドラインツールは NuGet パッケージをインストールおよび更新できます。ただし、Visual Studio プロジェクトの設定方法は、プロジェクトcdk initの設定方法とは異なります。（技術的な詳細: はPackages.configプロジェクトとnuget連携し、 はより新しいスタイルのPackageReferenceプロジェクトcdk initを作成します。）

によって作成された AWS CDK プロジェクトで nuget ツールを使用することはお勧めしませんcdk init。別のタイプのプロジェクトを使用していて、 を使用する場合はnuget、 NuGet CLI リファレンスを参照してください。

AWS CDK C# のイディオム

プロンプト

すべての AWS Construct Library クラスは、3 つの引数を使用してインスタンス化されます。コンストラクトが定義されているスコープ (コンストラクトツリー内の親）、ID 、props は、コンストラクトが作成するリソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドも引数に「属性のバンドル」パターンを使用します。

C# では、props は props 型を使用して表現されます。イディオマティック C# 方式では、オブジェクトイニシャライザを使用してさまざまなプロパティを設定できます。ここでは、 Bucketコンストラクトを使用して Amazon S3 バケットを作成します。対応するプロパティタイプは ですBucketProps。

var bucket = new Bucket(this, "MyBucket", new BucketProps {
    Versioned = true
});

クラスを拡張したり、メソッドを上書きしたりする場合、親クラスでは理解できない独自の目的で追加のプロップスを受け入れることをお勧めします。これを行うには、適切なプロパティタイプをサブクラス化し、新しい属性を追加します。

// extend BucketProps for use with MimeBucket
class MimeBucketProps : BucketProps {
    public string MimeType { get; set; }
}

// hypothetical bucket that enforces MIME type of objects inside it
class MimeBucket : Bucket {
     public MimeBucket( readonly Construct scope, readonly string id, readonly MimeBucketProps props=null) : base(scope, id, props) {
         // ...
     }
}

// instantiate our MimeBucket class 
var bucket = new MimeBucket(this, "MyBucket", new MimeBucketProps {
    Versioned = true,
    MimeType = "image/jpeg"
});

親クラスのイニシャライザまたはオーバーライドされたメソッドを呼び出す場合、通常、受信したプロパを渡すことができます。新しいタイプは親と互換性があり、追加した追加のプロップは無視されます。

の将来のリリースでは、独自のプロパティに使用した名前で新しいプロパティが同時に追加 AWS CDK される可能性があります。これによりコンストラクトやメソッドを使用する技術的な問題が発生することはありません (プロパティが「チェーン上」に渡されないため、親クラスや上書きされたメソッドは単にデフォルト値を使用するため）。ただし、コンストラクトのユーザーに混乱が生じる可能性があります。プロパティに名前を付けることで、この潜在的な問題を回避し、コンストラクトに明確に属させることができます。新しいプロパティが多数ある場合は、適切に名前が付けられたクラスにバンドルし、単一のプロパティとして渡します。

一般的な構造

一部の APIs、 AWS CDK は JavaScript 配列または型指定されていないオブジェクトをメソッドへの入力として使用します。（例えば、 AWS CodeBuildの BuildSpec.fromObject()メソッドを参照してください。） C# では、これらのオブジェクトは として表されますSystem.Collections.Generic.Dictionary<String, Object>。値がすべて文字列の場合、Dictionary<String, String>. JavaScript arrays は C# の object[]または string[]配列タイプとして表現できます。

using StringDict = System.Collections.Generic.Dictionary<string, string>;
using ObjectDict = System.Collections.Generic.Dictionary<string, object>;

欠落した値

C# では、props などの AWS CDK オブジェクトの欠損値は で表されますnull。null 条件付きメンバーアクセス演算子?.と null 結合演算子??は、これらの値を操作するのに役立ちます。

// mimeType is null if props is null or if props.MimeType is null
string mimeType = props?.MimeType;

// mimeType defaults to text/plain. either props or props.MimeType can be null
string MimeType = props?.MimeType ?? "text/plain";

構築、合成、デプロイ

は、アプリケーションを実行する前に AWS CDK 自動的にコンパイルします。ただし、エラーを確認してテストを実行するために、アプリケーションを手動で構築すると便利です。これを行うには、Visual Studio で F6 を押すか、コマンドラインdotnet build srcから を発行します。ここで、 srcは Visual Studio Solution (.sln) ファイルを含むプロジェクトディレクトリ内のディレクトリです。

AWS CDK アプリケーションで定義されたスタックは、合成して個別にデプロイすることも、以下のコマンドを使用してまとめてデプロイすることもできます。通常、プロジェクトを発行するときは、プロジェクトのメインディレクトリにいる必要があります。

1 つのコマンドで合成またはデプロイする複数のスタックの名前を指定できます。アプリケーションが 1 つのスタックのみを定義している場合は、指定する必要はありません。

cdk synth                 # app defines single stack
cdk deploy Happy Grumpy   # app defines two or more stacks; two are deployed

また、ワイルドカード * (任意の文字数) と ? (任意の 1 文字) を使用して、パターンでスタックを識別することもできます。ワイルドカードを使用する場合は、パターンを引用符で囲みます。そうしないと、シェルは AWS CDK Toolkit に渡す前に、現在のディレクトリ内のファイルの名前に拡張しようとする可能性があります。

cdk synth "Stack?"    # Stack1, StackA, etc.
cdk deploy "*Stack"   # PipeStack, LambdaStack, etc.

cdk コマンドの完全なドキュメントについては、「」を参照してくださいAWS CDK ツールキット (cdk コマンド）。