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 ツールチェーンには、.NET アプリケーションを構築および実行し、NuGet パッケージを管理するための dotnet コマンドラインツールが含まれています。主に 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 ベースのインターフェイスです。[ツール] > [NuGet パッケージマネージャー] > [パッケージマネージャーコンソール] を選択し、Visual Studio で開くことができます。このツールの使用の詳細については、「Visual Studio の Package Manager コンソールを使用したパッケージのインストールと管理」を参照してください。

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 パッケージをインストールおよび更新できます。ただし、cdk init がプロジェクトをセットアップする方法とは異なる方法で、Visual Studio プロジェクトをセットアップする必要があります。(技術的詳細: nuget は Packages.config プロジェクトと連動する一方、cdk init はより新しいスタイルの PackageReference プロジェクトを作成します。)

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

AWS CDK C# のイディオム

Props

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

C# では、props は props 型を使用して表現されます。特異な C# 方式では、オブジェクト初期化子を使用してさまざまなプロパティを設定できます。ここでは、Bucket コンストラクトを使用して Amazon S3 バケットを作成します。対応する props 型は BucketProps です。

var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps {
    Versioned = true
});

クラスを拡張したり、メソッドを上書きしたりするとき、親クラスで理解されない用途のために追加の props を受け入れることができます。これを行うには、適切な props 型をサブクラス化し、新しい属性を追加します。

// 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, "amzn-s3-demo-bucket", new MimeBucketProps {
    Versioned = true,
    MimeType = "image/jpeg"
});

親クラスの初期化子または上書きされたメソッドを呼び出すとき、一般的に受け取った props を渡すことができます。新しい型は親と互換性があり、追加した props は無視されます。

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

汎用構造

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

CDK アプリケーションの構築と実行

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