これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# C\$1 での AWS CDK の使用
<a name="work-with-cdk-csharp"></a>

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

Visual Studio、Visual Studio Code、 `dotnet` コマンド、NuGet パッケージマネージャーなどの使い慣れたツールを使用して、C\$1 で AWS CDK アプリケーションを開発できます。 AWS コンストラクトライブラリを構成するモジュールは、[nuget.org](https://www.nuget.org/packages?q=amazon.cdk.aws) を介して配布されます。

Windows で [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) (任意のエディション) を使用して C\$1 で AWS CDK アプリケーションを開発することをお勧めします。

## C\$1 の使用を開始する方法
<a name="csharp-prerequisites"></a>

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

C\$1 AWS CDK アプリケーションには .NET 8.0 以降が必要です。[こちらで](https://dotnet.microsoft.com/en-us/download/dotnet)入手できます。

**注記**  
サードパーティー言語の廃止: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (製品終了) までのみサポートされ、事前の通知によって変更されます。

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

## プロジェクトの作成
<a name="csharp-newproject"></a>

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

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

 `cdk init` はプロジェクトフォルダの名前を使用し、クラス、サブフォルダ、ファイルなどのプロジェクトのさまざまな要素に名前を付けます。フォルダ名に含まれるハイフンはアンダースコアに変換されます。ただし、それ以外の場合、名前は C\$1 識別子の形式に従う必要があります。例えば、数字で始まったり、スペースを含めたりすることはできません。

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

## AWS コンストラクトライブラリモジュールの管理
<a name="csharp-managemodules"></a>

.NET エコシステムは NuGet パッケージマネージャーを使用します。コアクラスおよびすべての安定したサービスコンストラクトを含むメイン CDK パッケージは `Amazon.CDK.Lib` です。新しい機能がアクティブな開発段階にある実験モジュールは、 のように名前が付けられ`Amazon.CDK.AWS.<SERVICE-NAME>.Alpha`ます。サービス名は、 AWS または Amazon プレフィックスのない短縮名です。たとえば、 AWS IoT モジュールの NuGet パッケージ名は です`Amazon.CDK.AWS.IoT.Alpha`。必要なパッケージが見つからない場合、[Nuget.org を検索](https://www.nuget.org/packages?q=amazon.cdk.aws)してください。

**注記**  
[CDK API リファレンスの .NET エディション](https://docs.aws.amazon.com/cdk/api/latest/dotnet/api/index.html)には、パッケージ名も表示されます。

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

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

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

## C\$1 の依存関係の管理
<a name="work-with-cdk-csharp-dependencies"></a>

C\$1 AWS CDK アプリでは、NuGet を使用して依存関係を管理します。NuGet には 4 つの標準インターフェイスがあり、ほとんどが同等です。ニーズと働き方に合ったものを使用してください。[Paket](https://fsprojects.github.io/Paket/) や [MyGet](https://www.myget.org/) などの互換性のあるツールを使用するか、`.csproj` ファイルを直接編集することもできます。

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

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

### プロジェクトファイルの直接編集
<a name="manage-dependencies-csharp-direct-edit"></a>

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

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

### Visual Studio の NuGet GUI
<a name="manage-dependencies-csharp-vs-nuget-gui"></a>

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

**注記**  
「実験的」と見なされるすべての AWS コンストラクトライブラリモジュール ([AWS CDK バージョニング](versioning.md)を参照) には、NuGet でプレリリースとしてフラグが付けられ、`alpha`名前のサフィックスが付いています。

![\[さまざまなサービスの Amazon CDK<shared id="AWS"/> アルファパッケージを示す NuGet パッケージマネージャー。\]](http://docs.aws.amazon.com/ja_jp/cdk/v2/guide/images/visual-studio-nuget.png)


**[更新プログラム]** ページを参照し、パッケージの新しいバージョンをインストールします。

### NuGet コンソール
<a name="manage-dependencies-csharp-vs-nuget-console"></a>

NuGet コンソールは、Visual Studio プロジェクトのコンテキストで動作する NuGet 用の PowerShell ベースのインターフェイスです。**[ツール]** > **[NuGet パッケージマネージャー]** > **[パッケージマネージャーコンソール]** を選択し、Visual Studio で開くことができます。このツールの使用の詳細については、「[Visual Studio の Package Manager コンソールを使用したパッケージのインストールと管理](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-powershell)」を参照してください。

### `dotnet` コマンド
<a name="manage-dependencies-csharp-vs-dotnet-command"></a>

`dotnet` コマンドは、Visual Studio C\$1 プロジェクトで作業するための主要なコマンドラインツールです。すべての 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](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli)」を参照してください。

### `nuget` コマンド
<a name="manage-dependencies-csharp-vs-nuget-command"></a>

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

によって作成された AWS CDK プロジェクトで `nuget` ツールを使用することはお勧めしません`cdk init`。プロジェクトの別のタイプを使用し、`nuget` を使用する場合、「[NuGet CLIリファレンス](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference)」を参照してください。

## AWS C\$1 の CDK イディオム
<a name="csharp-cdk-idioms"></a>

### Props
<a name="csharp-props"></a>

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

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

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

**ヒント**  
パッケージ `Amazon.JSII.Analyzers` をプロジェクトに追加し、Visual Studio の props 定義で必要な値を確認します。

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

### 汎用構造
<a name="csharp-generic-structures"></a>

一部の APIs では、 AWS CDK はメソッドへの入力として JavaScript 配列または型なしオブジェクトを使用します。( AWS CodeBuild の [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html)メソッドなどを参照してください）。C\$1 では、これらのオブジェクトは `System.Collections.Generic.Dictionary<String, Object>` として表されます。値がすべて文字列の場合、`Dictionary<String, String>` を使用できます。JavaScript 配列は、C\$1 で `object[]` または `string[]` 配列タイプとして表されます。

**ヒント**  
これらの特定のディクショナリタイプを使用しやすくするため、短いエイリアスを定義できます。  

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

### 欠落した値
<a name="csharp-missing-values"></a>

C\$1 では、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 アプリケーションの構築と実行
<a name="csharp-running"></a>

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