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#.

Comece com 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 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#; 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 comoAmazon.CDK.AWS.SERVICE-NAME.Alpha, em que o nome do serviço é um nome curto sem um prefixo AWS ou 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 aquela 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 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 <ItemGroup> que lista suas dependências como elementos <PackageReference.

<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 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.

O comando dotnet

O comando dotnet é a principal ferramenta de linha de comando para trabalhar com projetos em C# do Visual Studio. 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 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 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 palavra-chave add. O exemplo a seguir pressupõe que você esteja no diretório principal do seu projeto AWS CDK .

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 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.

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 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#

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 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#, props são expressos usando um tipo de props. No estilo em C# 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
});

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 você pode 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. Você pode 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, AWS CDK usa JavaScript matrizes ou objetos não digitados como entrada para um método. (Veja, por exemplo, o método BuildSpec.fromObject() de AWS CodeBuild.) Em C#, esses objetos são representados como System.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";

Compilação e execução de aplicações CDK

O compila AWS CDK automaticamente seu aplicativo antes de executá-lo. No entanto, pode ser útil criar sua aplicação 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 é o diretório no diretório do projeto que contém o arquivo Visual Studio Solution (.sln).