Trabalhando com o AWS CDK em C#

.NET é uma linguagem de cliente totalmente compatível com o AWS CDK e é considerada estável. C# é a principal linguagem.NET para a qual fornecemos exemplos e suporte. Você pode optar por escrever AWS CDK aplicativos em outras linguagens.NET, como Visual Basic ou F#, mas AWS oferece suporte limitado para o uso dessas linguagens com o CDK.

Você pode desenvolver AWS CDK aplicativos em C# 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.

Sugerimos usar o Visual Studio 2019 (qualquer edição) no Windows para desenvolver AWS CDK aplicativos em C#.

Conceitos básicos do C#

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 Começando com o AWS CDK.

Os AWS CDK aplicativos C# exigem o.NET Core v3.1 ou posterior, disponível aqui.

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 AWS CDK projeto invocando cdk init em um diretório vazio. Use a --language opção e especifiquecsharp:

mkdir my-project
cd my-project
cdk init app --language csharp

cdk initusa o nome da pasta do projeto para nomear vários elementos do projeto, incluindo classes, subpastas e arquivos. Os hífens no nome da pasta são convertidos em sublinhados. No entanto, caso contrário, o nome deve seguir a forma de um identificador C#; por exemplo, ele não deve começar com um número ou 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 todas as construções de serviço estáveis, é. Amazon.CDK.Lib Os módulos experimentais, nos quais a nova funcionalidade está em desenvolvimento ativo, são nomeados comoAmazon.CDK.AWS.SERVICE-NAME.Alpha, em que o nome do serviço é um nome curto sem um prefixo AWS ou da Amazon. Por exemplo, o nome do NuGet pacote do AWS IoT módulo éAmazon.CDK.AWS.IoT.Alpha. Se você não conseguir encontrar o pacote desejado, pesquise NuGet.org.

O suporte da AWS Construct Library de alguns serviços está em mais de um módulo. Por exemplo, AWS IoT tem um segundo módulo chamadoAmazon.CDK.AWS.IoT.Actions.Alpha.

O módulo principal AWS CDK do, que você precisará na maioria dos AWS CDK aplicativos, é importado no código C# comoAmazon.CDK. Os módulos para os vários serviços da AWS Construct Library estão abaixoAmazon.CDK.AWS. Por exemplo, o namespace do módulo Amazon S3 é. Amazon.CDK.AWS.S3

Recomendamos escrever using diretivas em C# 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#. 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

Gerenciando dependências em C#

Em AWS CDK aplicativos C#, você gerencia dependências usando. NuGet NuGet tem quatro interfaces padrão, em sua maioria equivalentes. Use aquele que se adapte às suas necessidades e estilo de trabalho. Você também pode usar ferramentas compatíveis, como o Paket MyGetou 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 dotnet restore comando para atualizar suas dependências.

Editando o arquivo do projeto diretamente

O .csproj arquivo do seu projeto contém um <ItemGroup> contêiner que lista suas dependências como <PackageReference elementos.

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

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. Você pode 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.

Consulte a página Atualizações para instalar novas versões dos 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 console do Package Manager no Visual Studio.

O dotnet comando

O dotnet comando é a principal ferramenta de linha de comando para trabalhar com projetos do Visual Studio C#. Você pode 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 o seguinte para instalar um pacote. Como a biblioteca principal do CDK está incluída quando você cria 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 VERSION-NUMBER

Você pode 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 add palavra-chave. O exemplo a seguir pressupõe que você esteja no diretório principal do seu AWS CDK projeto.

dotnet add src/PROJECT-DIR package Amazon.CDK.AWS.IoT.Alpha -v VERSION-NUMBER

Para instalar uma versão específica de um pacote, inclua o -v sinalizador e a versão desejada.

Para atualizar um pacote, emita o mesmo dotnet add comando 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 dotnet comando, consulte Instalar e gerenciar pacotes usando a CLI dotnet.

O nuget comando

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 Packages.config projetos e cdk init cria um projeto de estilo mais novoPackageReference.)

Não recomendamos o uso da nuget ferramenta com AWS CDK projetos criados porcdk init. Se você estiver usando outro tipo de projeto e quiser usá-lonuget, consulte a Referência da NuGet CLI.

AWS CDK expressões idiomáticas em C#

Adereços

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 pares de chave/valor 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#, adereços são expressos usando um tipo de adereços. No estilo idiomático do C#, podemos usar um inicializador de objetos para definir as várias propriedades. Aqui, estamos criando um bucket do Amazon S3 usando a Bucket construção; seu tipo de props correspondente é. BucketProps

var bucket = new Bucket(this, "MyBucket", new BucketProps {
    Versioned = true
});

Ao estender uma classe ou substituir um método, talvez você queira aceitar adereços 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, "MyBucket", new MimeBucketProps {
    Versioned = true,
    MimeType = "image/jpeg"
});

Ao chamar o inicializador ou o método substituído da classe principal, geralmente você pode passar os adereços que recebeu. O novo tipo é compatível com seu pai, e os adereços 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 sua construção 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 da sua construção. Você pode evitar esse problema em potencial nomeando suas propriedades de forma que elas claramente pertençam à sua construção. Se houver muitas propriedades novas, agrupe-as em uma classe com nome apropriado e passe-as como uma única propriedade.

Estruturas genéricas

Em algumas APIs, o AWS CDK usa JavaScript matrizes ou objetos não digitados como entrada para um método. (Veja, por exemplo, AWS CodeBuild o BuildSpec.fromObject()método de.) Em C#, esses objetos são representados comoSystem.Collections.Generic.Dictionary<String, Object>. Nos casos em que os valores são todos cadeias de caracteres, você pode usarDictionary<String, String>. JavaScript matrizes são representadas como object[] ou tipos string[] de matriz em C#.

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

Valores ausentes

Em C#, valores ausentes em AWS CDK objetos 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";

Construindo, sintetizando e implantando

O compila AWS CDK automaticamente seu aplicativo antes de executá-lo. No entanto, pode ser útil criar seu aplicativo manualmente para verificar erros e executar testes. Você pode fazer isso pressionando F6 no Visual Studio ou emitindo a dotnet build src partir da linha de comando, onde src está o diretório no diretório do projeto que contém o arquivo Visual Studio Solution (.sln).

As pilhas definidas em seu AWS CDK aplicativo podem ser sintetizadas e implantadas individualmente ou em conjunto usando os comandos abaixo. Geralmente, você deve estar no diretório principal do seu projeto ao emiti-los.

Você pode especificar os nomes de várias pilhas a serem sintetizadas ou implantadas em um único comando. Se seu aplicativo definir apenas uma pilha, você não precisará especificá-la.

cdk synth                 # app defines single stack
cdk deploy Happy Grumpy   # app defines two or more stacks; two are deployed

Você também pode usar os curingas * (qualquer número de caracteres) e? (qualquer caractere único) para identificar pilhas por padrão. Ao usar curingas, coloque o padrão entre aspas. Caso contrário, o shell pode tentar expandi-lo para os nomes dos arquivos no diretório atual antes de serem passados para o AWS CDK Toolkit.

cdk synth "Stack?"    # Stack1, StackA, etc.
cdk deploy "*Stack"   # PipeStack, LambdaStack, etc.

Para obter a documentação completa do cdk comando, consulteAWS CDK Kit de ferramentas (cdkcomando).