在 C# AWS CDK 中使用

。NET 是 完全支援的用戶端語言， AWS CDK 且 被視為穩定。C# 是我們提供範例和支援的主要 .NET 語言。您可以選擇以其他 .NET 語言撰寫 AWS CDK 應用程式，例如 Visual Basic 或 F#，但對將這些語言與 搭配使用 AWS 的支援有限CDK。

您可以使用熟悉的工具在 C# 中開發 AWS CDK 應用程式，包括 Visual Studio、Visual Studio Code、 dotnet 命令和 NuGet 套件管理員。包含 AWS Construct Library 的模組會透過 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 建構程式庫支援位於多個模組中。例如， AWS IoT 有一個名為 的第二個模組Amazon.CDK.AWS.IoT.Actions.Alpha。

大多數 AWS CDK 應用程式中需要 AWS CDK的 主模組會以 匯入 C# 程式碼Amazon.CDK。 AWS Construct Library 中各種服務的模組位於 下Amazon.CDK.AWS。例如，Amazon S3 模組的命名空間為 Amazon.CDK.AWS.S3。

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

在 中管理相依性 C#

在 C# AWS CDK apps 中，您可以使用 NuGet. NuGet has 的四個標準，主要是等效介面來管理相依性。使用符合您需求和工作風格的 。您也可以使用相容的工具，例如 Paket MyGet 或 ，甚至直接編輯.csproj檔案。

NuGet 不會讓您指定相依性的版本範圍。每個相依性都會固定到特定版本。

更新相依性後，Visual Studio 將在下次建置時 NuGet 用來擷取每個套件的指定版本。如果您不使用 Visual Studio，請使用 dotnet restore命令來更新您的相依性。

直接編輯專案檔案

專案.csproj的檔案包含<ItemGroup>容器，會將相依性列為<PackageReference元素。

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

Visual Studio NuGet GUI

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

請查看更新頁面，安裝新版本的套件。

NuGet 主控台

NuGet 主控台是 PowerShell的 型介面 NuGet ，可在 Visual Studio 專案的內容中運作。您可以選擇工具 > NuGet 套件管理員 > 套件管理員主控台 ，在 Visual Studio 中開啟它。如需使用此工具的詳細資訊，請參閱在 Visual Studio 中使用 Package Manager Console 安裝和管理套件。

dotnet 命令

dotnet 命令是使用 Visual Studio C# 專案的主要命令列工具。您可以從任何 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

nuget 命令

nuget 命令列工具可以安裝和更新 NuGet 套件。不過，它要求您的 Visual Studio 專案的設定與cdk init設定專案的方式不同。（技術詳細資訊：nuget使用Packages.config專案，同時cdk init建立較新的PackageReference專案。）

我們不建議使用 nuget工具搭配 建立的 AWS CDK 專案cdk init。如果您使用的是其他類型的專案，且想要使用 nuget，請參閱NuGet CLI參考 。

AWS CDK C# 中的慣用語

道具

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

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

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

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

未來的 版本 AWS CDK 可能會偶然新增具有您用於自己屬性名稱的新屬性。這不會導致任何使用建構或方法的技術問題 （因為您的屬性不會傳遞「透過鏈」，父類別或覆寫方法只會使用預設值），但可能會對建構的使用者造成混淆。您可以透過命名屬性來避免此潛在問題，以便它們明顯屬於您的建構。如果有許多新的屬性，請將它們綁定到具有適當名稱的類別中，並將其作為單一屬性傳遞。

一般結構

在某些 中APIs， AWS CDK 會使用 JavaScript 陣列或未輸入的物件作為方法的輸入。（例如，請參閱 AWS CodeBuildBuildSpec.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# 中，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應用程式

在執行應用程式之前， AWS CDK 會自動編譯應用程式。不過，手動建置應用程式以檢查錯誤和執行測試會很有用。您可以在 Visual Studio 中按 F6 或從dotnet build src命令列發出，其中 src是包含 Visual Studio Solution （.sln） 檔案的專案目錄中的目錄。