在 C# 中使用 AWS CDK

.NET 是一种 AWS CDK 完全支持且视为稳定的客户端语言。C# 是我们提供示例和支持的主要 .NET 语言。您可以选择使用其他 .NET 语言（例如 Visual Basic 或 F#）来编写 AWS CDK 应用程序，但在将这些语言与 CDK 搭配使用方面，AWS 提供的支持有限。

您可以使用熟悉的工具（包括 Visual Studio、Visual Studio Code、dotnet 命令和 NuGet 包管理器），以 C# 开发 AWS CDK 应用程序。通过 nuget.org 来分发构成 AWS 构造库的模块。

我们建议在 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 构造库中各种服务的模块位于 Amazon.CDK.AWS 下。例如，Amazon S3 模块的命名空间为 Amazon.CDK.AWS.S3。

我们建议为 CDK 核心构造以及您在每个 C# 源文件中使用的每项 AWS 服务编写 C# using 指令。您可能发现使用命名空间或类型的别名来帮助解决名称冲突会很方便。您始终可以使用类型的完全限定名称（包括其命名空间），而无需使用 using 语句。

在 C# 中管理依赖项

在 C# AWS CDK 应用程序中，您可以使用 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

可通过工具 > NuGet 软件包管理器 > 管理解决方案的 NuGet 软件包来访问 Visual Studio 的 NuGet 工具。使用浏览选项卡查找想要安装的 AWS 构造库软件包。您可以选择所需的版本，包括模块的预发布版本，然后将其添加到任何打开的项目中。

查看更新页面，以便安装软件包的新版本。

NuGet 控制台

NuGet 控制台是一个基于 PowerShell 的 NuGet 接口，可在 Visual Studio 项目的上下文中运行。您可以选择工具 > NuGet 包管理器 > 包管理器控制台在 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 工具与 cdk init 创建的 AWS CDK 项目一起使用。如果您正在使用其他类型的项目，并且想要使用 nuget，请参阅 NuGet CLI Reference。

C# 中的 AWS CDK 习语

Props

所有 AWS 构造库类都使用三个参数进行实例化：在其中定义构造的 scope（构造树中的父级）、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 的未来版本可能会碰巧添加一个新属性，其名称与您用于自己属性的名称相同。这不会导致使用您的构造或方法时出现任何技术问题（因为您的属性不会“向上沿链”传递，所以父类或重写的方法只会使用默认值），但可能会给您的构造用户带来困惑。您可以对属性进行命名来避免这个潜在问题，这样它们就明确属于您的构造。如果有许多新属性，请将其捆绑到一个适当命名的类中，然后将其作为单个属性进行传递。

通用结构

在某些 API 中，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# 中，AWS CDK 对象中的缺失值（例如 props）用 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 解决方案（.sln）文件的目录。