在 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 的模組會透過 https：//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 有四個標準介面，主要是同等介面。使用符合您需求和工作風格的 。您也可以使用相容的工具，例如 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 主控台是 NuGet 的 PowerShell 型界面，可在 Visual Studio 專案的內容中運作。您可以選擇工具 > NuGet Package Manager > Package Manager Console，在 Visual Studio 中開啟它。如需使用此工具的詳細資訊，請參閱在 Visual Studio 中使用套件管理員主控台安裝和管理套件。

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 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# 中，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) 檔案的目錄。