這是 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 語言。您可以選擇以其他 .NET 語言撰寫 AWS CDK 應用程式，例如 Visual Basic 或 F\$1，但 AWS 提供將這些語言與 CDK 搭配使用的有限支援。

您可以使用熟悉的工具在 C\$1 中開發 AWS CDK 應用程式，包括 Visual Studio、Visual Studio Code、 `dotnet`命令和 NuGet 套件管理員。構成 AWS 建構程式庫的模組會透過 https：//[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 工具鏈包含 `dotnet`，這是用於建置和執行 .NET 應用程式和管理 NuGet 套件的命令列工具。即使您主要在 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 有一個名為 的第二個模組`Amazon.CDK.AWS.IoT.Actions.Alpha`。

大多數 AWS CDK 應用程式中所需的 AWS CDK 主要模組會以 匯入 C\$1 程式碼`Amazon.CDK`。 AWS Construct Library 中各種服務的模組會在 下運作`Amazon.CDK.AWS `。例如，Amazon S3 模組的命名空間為 `Amazon.CDK.AWS.S3`。

建議您為每個 C\$1 來源檔案中所使用的 CDK 核心建構和每個 AWS 服務撰寫 C\$1 `using`指令。您可能會發現使用命名空間或類型的別名，有助於解決名稱衝突。您可以隨時使用類型的完整名稱 （包括其命名空間），無需`using`陳述式。

## 在 C\$1 中管理相依性
<a name="work-with-cdk-csharp-dependencies"></a>

在 C\$1 AWS CDK 應用程式中，您可以使用 NuGet 管理相依性。NuGet 有四個標準且大部分同等的界面。使用符合您的需求和工作風格。您也可以使用相容的工具，例如 [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`的檔案包含一個`<ItemGroup>`容器，將您的相依性列為 `<PackageReference`元素。

```
<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 工具可從 **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution** 存取。使用**瀏覽**索引標籤來尋找您要安裝的 AWS 建構程式庫套件。您可以選擇所需的版本，包括模組的發行前版本，並將其新增至任何開啟的專案。

**注意**  
所有被視為「實驗性」的 AWS Construct Library 模組 （請參閱 [AWS CDK 版本控制](versioning.md)) 在 NuGet 中標記為發行前，並具有`alpha`名稱尾碼。

![\[NuGet 套件管理員顯示適用於各種服務的 Amazon CDK<shared id="AWS"/> Alpha 套件。\]](http://docs.aws.amazon.com/zh_tw/cdk/v2/guide/images/visual-studio-nuget.png)


查看**更新**頁面以安裝新版本的套件。

### NuGet 主控台
<a name="manage-dependencies-csharp-vs-nuget-console"></a>

NuGet 主控台是 NuGet 的 PowerShell 型界面，可在 Visual Studio 專案的內容中運作。您可以選擇**工具** > **NuGet Package Manager** > **Package Manager Console**，在 Visual Studio 中開啟它。如需使用此工具的詳細資訊，請參閱在 [Visual Studio 中使用套件管理員主控台安裝和管理套件](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`可以將 NuGet 相依性新增至 Visual Studio 專案。

假設您位於與 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 套件。不過，它需要您的 Visual Studio 專案的設定方式與`cdk init`設定專案的方式不同。（技術詳細資訊： `nuget` 適用於 `Packages.config` 專案，同時 `cdk init`會建立較新的 `PackageReference`專案。)

我們不建議使用 `nuget`工具搭配 建立的 AWS CDK 專案`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>

### 屬性
<a name="csharp-props"></a>

所有 AWS 建構程式庫類別都是使用三個引數來執行個體化：定義建構*的範圍* （其在建構樹狀結構中的父系）、*id* 和 *props*，即建構函數用來設定其建立之資源的金鑰/值對套件。其他類別和方法也會針對引數使用「屬性組合」模式。

在 C\$1 中，props 使用 props 類型來表示。以類似 C\$1 的方式，我們可以使用物件初始化器來設定各種屬性。在這裡，我們使用 `Bucket` 建構模組建立 Amazon S3 儲存貯體；其對應的道具類型為 `BucketProps`。

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

**提示**  
將套件`Amazon.JSII.Analyzers`新增至您的專案，以在 Visual Studio 中取得 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"
});
```

呼叫父類別的初始化或覆寫方法時，您通常可以傳遞您收到的道具。新類型與其父項相容，您新增的額外道具會被忽略。

未來的 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 中，prop 等 AWS CDK 物件中的遺失值會以 表示`null`。Null-conditional 成員存取運算子`?.`和 Null Coalescing 運算子`??`方便使用這些值。

```
// 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 解決方案 (`.sln`) 檔案的目錄。