这是 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 语言（例如 Visual Bas AWS ic 或 F\$1）编写 AWS CDK 应用程序，但对在 CDK 中使用这些语言的支持有限。

你可以使用 Visual Stu AWS dio、Visual Studio Code、`dotnet`命令和 NuGet 包管理器等熟悉的工具在 C\$1 中开发 CDK 应用程序。构成 AWS 构造库的模块通过 [nuget](https://www.nuget.org/packages?q=amazon.cdk.aws) .org 分发。

我们建议在 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 工具包。请参阅 [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 物联网模块的 NuGet 软件包名称是`Amazon.CDK.AWS.IoT.Alpha`。如果您找不到想要的包，请[搜索 Nuget.org](https://www.nuget.org/packages?q=amazon.cdk.aws)。

**注意**  
[CDK API Reference 的 .NET 版本](https://docs.aws.amazon.com/cdk/api/latest/dotnet/api/index.html)也显示了包名称。

某些服务的 AWS 构造库支持位于多个模块中。例如， AWS 物联网有第二个名为的模块`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 有四个标准的、基本上等同的接口。使用适合您需求和工作方式的接口。您还可以使用兼容的工具，例如 [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>
```

### 视觉工作室 NuGet 图形用户界面
<a name="manage-dependencies-csharp-vs-nuget-gui"></a>

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

**注意**  
所有被视为 “实验性” 的 Con AWS struct Library 模块（参见 [AWS CDK 版本控制](versioning.md)）都被标记为预发行版， NuGet 并带有名称后缀。`alpha`

![\[NuGet 包管理器显示各种服务的 Amazon CDK <shared id="AWS"/> alpha 套餐。\]](http://docs.aws.amazon.com/zh_cn/cdk/v2/guide/images/visual-studio-nuget.png)


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

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

 NuGet 控制台是一个 PowerShell基于 Visual Studio 项目的界面 NuGet ，可以在 Visual Studio 项目的上下文中运行。你可以在 Visual Studio 中通过选择 “**工具**” > “**NuGet 包管理器” > “Packag** e Man **ager 控制台**” 将其打开。有关使用此工具的更多信息，请参阅[使用 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`可以向 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 软件包。但是，该工具要求您 Visual Studio 项目的设置方式与 `cdk init` 设置项目的方式不同。（技术细节：`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>

所有 C AWS onstruct Library 类都使用三个参数进行实例化：定义构造的*作用域*（构造树中的父级）、*id* 和 *props*（构造函数用来配置其创建的资源的一 key/value 组对）。其他类和方法也使用“属性捆绑包”模式作为参数。

在 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 将被忽略。

Future 版本的 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 中，`string[]`数组表示为`object[]`或数组类型。

**提示**  
您可以定义简短的别名，以便更容易使用这些特定的词典类型。  

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

### 缺失值
<a name="csharp-missing-values"></a>

在 C\$1 中，道具等 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 解决方案（`.sln`）文件的目录。