Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Trabalhando com o AWS CDK em C\$1
.NET é uma linguagem de cliente totalmente compatível com o AWS CDK e é considerada estável. C\$1 é a principal linguagem .NET para a qual fornecemos exemplos e suporte. Você pode optar por escrever aplicativos AWS CDK em outras linguagens do.NET, como Visual Basic ou F\$1, mas AWS oferece suporte limitado para o uso dessas linguagens com o CDK.
Você pode desenvolver aplicativos AWS CDK em C\$1 usando ferramentas conhecidas, incluindo Visual Studio, Visual Studio Code, o `dotnet` comando e o gerenciador de NuGet pacotes. Os módulos que compõem a AWS Construct Library são distribuídos via [nuget.org](https://www.nuget.org/packages?q=amazon.cdk.aws).
Sugerimos usar o [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) (qualquer edição) no Windows para desenvolver aplicativos AWS CDK em C\$1.
## Conceitos básicos do C\$1
Para trabalhar com o AWS CDK, você deve ter uma AWS conta e credenciais e ter instalado o Node.js e o AWS CDK Toolkit. Consulte [Introdução ao AWS CDK.](getting-started.md)
[Os aplicativos C\$1 AWS CDK exigem o.NET 8.0 ou posterior, disponível aqui.](https://dotnet.microsoft.com/en-us/download/dotnet)
**nota**
Suspensão de uso de linguagem de terceiros: a versão da linguagem só é suportada até seu EOL (End Of Life) compartilhado pelo fornecedor ou pela comunidade e está sujeita a alterações mediante aviso prévio.
O conjunto de ferramentas do.NET inclui `dotnet` uma ferramenta de linha de comando para criar e executar aplicativos.NET e gerenciar pacotes. NuGet Mesmo que você trabalhe principalmente no Visual Studio, esse comando pode ser útil para operações em lote e para instalar pacotes da AWS Construct Library.
## Criação de um projeto
Você cria um novo projeto AWS CDK invocando `cdk init` em um diretório vazio. Use a opção `--language` e especifique `csharp`:
```
mkdir my-project
cd my-project
cdk init app --language csharp
```
`cdk init` usa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Hifens no nome da pasta são convertidos em sublinhados. No entanto, o nome deve seguir a forma de um identificador C\$1; por exemplo, não deve começar com um número nem conter espaços.
O projeto resultante inclui uma referência ao `Amazon.CDK.Lib` NuGet pacote. Ele e suas dependências são instalados automaticamente pelo NuGet.
## Gerenciando módulos da AWS Construct Libr
O ecossistema.NET usa o gerenciador de NuGet pacotes. O pacote CDK principal, que contém as classes principais e todos os contêiners de serviço estáveis, é `Amazon.CDK.Lib`. Os módulos experimentais, nos quais a nova funcionalidade está em desenvolvimento ativo, são nomeados como`Amazon.CDK.AWS..Alpha`, em que o nome do serviço é um nome curto sem um prefixo AWS ou da Amazon. Por exemplo, o nome NuGet do pacote para o módulo de AWS IoT é. `Amazon.CDK.AWS.IoT.Alpha` Se você não conseguir encontrar o pacote desejado, [pesquise NuGet.org](https://www.nuget.org/packages?q=amazon.cdk.aws).
**nota**
A [edição .NET de referência de API do CDK](https://docs.aws.amazon.com/cdk/api/latest/dotnet/api/index.html) também mostra os nomes dos pacotes.
O suporte da AWS Construct Library de alguns serviços está em mais de um módulo. Por exemplo, a AWS IoT tem um segundo módulo chamado. `Amazon.CDK.AWS.IoT.Actions.Alpha`
O módulo principal do AWS CDK, que você precisará na maioria dos aplicativos AWS CDK, é importado em código C\$1 como. `Amazon.CDK` Os módulos para os vários serviços da AWS Construct Library estão abaixo`Amazon.CDK.AWS `. Por exemplo, o namespace do módulo do Amazon S3 é `Amazon.CDK.AWS.S3`.
Recomendamos escrever `using` diretivas em C\$1 para as construções principais do CDK e para cada AWS serviço que você usa em cada um dos seus arquivos de origem em C\$1. Talvez seja conveniente usar um alias para um namespace ou tipo para ajudar a resolver conflitos de nomes. Você sempre pode usar o nome totalmente qualificado de um tipo (incluindo seu namespace) sem uma declaração `using`.
## Gerenciamento de dependências em C\$1
Em aplicativos C\$1 AWS CDK, você gerencia dependências usando. NuGet NuGet tem quatro interfaces padrão, em sua maioria equivalentes. Use aquela que se adapte às suas necessidades e estilo de trabalho. Você também pode usar ferramentas compatíveis, como o [Paket [MyGet](https://www.myget.org/)](https://fsprojects.github.io/Paket/)ou até mesmo editar o `.csproj` arquivo diretamente.
NuGet não permite que você especifique intervalos de versão para dependências. Cada dependência é fixada em uma versão específica.
Depois de atualizar suas dependências, o Visual Studio usará NuGet para recuperar as versões especificadas de cada pacote na próxima vez que você criar. Se você não estiver usando o Visual Studio, use o comando `dotnet restore` para atualizar suas dependências.
### Edição do arquivo do projeto diretamente
O arquivo `.csproj` do seu projeto contém um contêiner `` que lista suas dependências como elementos de `
```
### A NuGet interface gráfica do Visual Studio
As NuGet ferramentas do Visual Studio podem ser acessadas em **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution**. Use a guia **Procurar** para encontrar os pacotes da AWS Construct Library que você deseja instalar. É possível escolher a versão desejada, incluindo as versões de pré-lançamento de seus módulos, e adicioná-las a qualquer um dos projetos abertos.
**nota**
Todos os módulos da AWS Construct Library considerados “experimentais” (consulte o controle de [versão do AWS CDK](versioning.md)) estão marcados como pré-lançamento e têm um sufixo de nome. NuGet `alpha`
![\[NuGet gerenciador de pacotes mostrando pacotes alfa do Amazon CDK para vários serviços.\]](http://docs.aws.amazon.com/pt_br/cdk/v2/guide/images/visual-studio-nuget.png)
Consulte a página **Atualizações** para instalar novas versões de seus pacotes.
### O NuGet console
O NuGet console é uma interface PowerShell baseada NuGet que funciona no contexto de um projeto do Visual Studio. Você pode abri-lo no Visual Studio escolhendo **Tools** > **NuGet Package Manager** > **Package Manager Console**. Para obter mais informações sobre o uso dessa ferramenta, consulte [Instalar e gerenciar pacotes com o Package Manager Console no Visual Studio](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-powershell).
### O comando `dotnet`
O comando `dotnet` é a principal ferramenta de linha de comando para trabalhar com projetos em C\$1 do Visual Studio. É possível invocá-lo em qualquer prompt de comando do Windows. Entre seus muitos recursos, `dotnet` pode adicionar NuGet dependências a um projeto do Visual Studio.
Supondo que você esteja no mesmo diretório do arquivo de projeto (`.csproj`) do Visual Studio, emita um comando como a seguir para instalar um pacote. Como a biblioteca principal do CDK está incluída ao criar um projeto, você só precisa instalar explicitamente os módulos experimentais. Os módulos experimentais exigem que você especifique um número de versão explícito.
```
dotnet add package Amazon.CDK.AWS.IoT.Alpha -v
```
É possível emitir o comando de outro diretório. Para fazer isso, inclua o caminho para o arquivo do projeto ou para o diretório que o contém após a palavra-chave `add`. O exemplo a seguir pressupõe que você esteja no diretório principal do seu projeto AWS CDK.
```
dotnet add src/ package Amazon.CDK.AWS.IoT.Alpha -v
```
Para instalar uma versão específica de um pacote, inclua o sinalizador `-v` e a versão desejada.
Para atualizar um pacote, execute o mesmo comando `dotnet add` usado para instalá-lo. Para módulos experimentais, novamente, você deve especificar um número de versão explícito.
Para obter mais informações sobre como gerenciar pacotes usando o comando `dotnet`, consulte [Instalar e gerenciar pacotes usando a CLI dotnet](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli).
### O comando `nuget`
A ferramenta de linha de `nuget` comando pode instalar e atualizar NuGet pacotes. No entanto, isso exige que seu projeto do Visual Studio seja configurado de forma diferente da forma como `cdk init` configura projetos. (Detalhes técnicos: `nuget` trabalha com projetos `Packages.config` e `cdk init` cria um projeto `PackageReference` de estilo mais novo.)
Não recomendamos o uso da `nuget` ferramenta com projetos AWS CDK criados por`cdk init`. Se você estiver usando outro tipo de projeto e quiser usá-lo`nuget`, consulte a Referência da [NuGet CLI](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference).
## AWS Expressões idiomáticas do CDK em C\$1
### Props
Todas as classes da AWS Construct Library são instanciadas usando três argumentos: o *escopo* no qual a construção está sendo definida (seu pai na árvore de construção), um *id* e *props*, um pacote de key/value pares que a construção usa para configurar os recursos que cria. Outras classes e métodos também usam o padrão “pacote de atributos” para argumentos.
Em C\$1, props são expressos usando um tipo de props. No estilo em C\$1 idiomático, podemos usar um inicializador de objetos para definir as várias propriedades. Aqui, estamos criando um bucket do Amazon S3 usando o constructo `Bucket`; seu tipo de props correspondente é `BucketProps`.
```
var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps {
Versioned = true
});
```
**dica**
Adicione o pacote `Amazon.JSII.Analyzers` ao seu projeto para obter os valores necessários verificando suas definições de props dentro do Visual Studio.
Ao estender uma classe ou substituir um método, talvez você queira aceitar propos adicionais para seus próprios propósitos que não sejam compreendidos pela classe principal. Para fazer isso, subclassifique o tipo de props apropriado e adicione os novos atributos.
```
// 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"
});
```
Ao chamar o inicializador ou o método substituído da classe principal, geralmente é possível passar os props que recebeu. O novo tipo é compatível com seu pai, e os propos extras adicionados são ignorados.
Uma versão futura do AWS CDK poderia coincidentemente adicionar uma nova propriedade com um nome que você usou para sua própria propriedade. Isso não causará problemas técnicos ao usar seu constructo ou método (como sua propriedade não é passada “para cima na cadeia”, a classe principal ou o método substituído simplesmente usará um valor padrão), mas pode causar confusão para os usuários do seu constructo. É possível evitar esse problema em potencial nomeando suas propriedades de forma que elas claramente pertençam ao seu constructo. Se houver muitas propriedades novas, agrupe-as em uma classe com nome apropriado e passe-as como uma única propriedade.
### Estruturas genéricas
Em alguns APIs, o AWS CDK usa JavaScript matrizes ou objetos não digitados como entrada para um método. (Veja, por exemplo, AWS CodeBuild o [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)método de.) Em C\$1, esses objetos são representados como `System.Collections.Generic.Dictionary`. Nos casos em que os valores são todos cadeias de caracteres, você pode usar`Dictionary`. JavaScript matrizes são representadas como `object[]` ou tipos `string[]` de matriz em C\$1.
**dica**
É possível definir aliases curtos para facilitar o trabalho com esses tipos específicos de dicionário.
```
using StringDict = System.Collections.Generic.Dictionary;
using ObjectDict = System.Collections.Generic.Dictionary;
```
### Valores ausentes
Em C\$1, os valores ausentes em objetos AWS CDK, como adereços, são representados por. `null` O operador de acesso de membro condicional nulo `?.` e o operador de coalescência nula `??` são convenientes para trabalhar com esses valores.
```
// 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";
```
## Compilação e execução de aplicações CDK
O AWS CDK compila automaticamente seu aplicativo antes de executá-lo. No entanto, pode ser útil criar sua aplicação manualmente para verificar erros e executar testes. É possível fazer isso pressionando F6 no Visual Studio ou emitindo a `dotnet build src` partir da linha de comando, onde `src` é o diretório no diretório do projeto que contém o arquivo Visual Studio Solution (`.sln`).