Utilización del CDK AWS en C#

.NET es un lenguaje de cliente totalmente compatible con AWS CDK y se lo considera estable. C# es el lenguaje principal de .NET para el que ofrecemos ejemplos y soporte. Puede escribir aplicaciones de AWS CDK en otros lenguajes .NET, como Visual Basic o F#, pero AWS ofrece una compatibilidad limitada para el uso de estos lenguajes con el CDK.

Puede desarrollar aplicaciones de AWS CDK en C# con herramientas conocidas, como Visual Studio, Visual Studio Code, el comando dotnet y el administrador de paquetes NuGet. Los módulos que componen la Biblioteca de constructos de AWS se distribuyen a través de nuget.org.

Sugerimos usar Visual Studio 2019 (cualquier edición) en Windows para desarrollar aplicaciones de AWS CDK en C#.

Introducción a C#

Para trabajar con el AWS CDK, debe tener una cuenta de AWS y credenciales, y haber instalado Node.js y el kit de herramientas de AWS CDK. Consulte Introducción al AWS CDK.

Las aplicaciones C# de AWS CDK requieren .NET Core v3.1 o una versión posterior, disponible aquí.

La cadena de herramientas de .NET incluye dotnet, una herramienta de línea de comandos para crear y ejecutar aplicaciones .NET y administrar paquetes NuGet. Aunque trabaje principalmente en Visual Studio, este comando puede resultar útil para operaciones por lotes y para instalar paquetes de la Biblioteca de constructos de AWS.

Creación de un proyecto

Cree un nuevo proyecto AWS CDK, mediante la invocación de cdk init en un directorio vacío. Utilice la opción --language y especifique csharp:

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

cdk init utiliza el nombre de la carpeta del proyecto para asignar un nombre a varios elementos del proyecto, incluidas las clases, las subcarpetas y los archivos. Los guiones del nombre de la carpeta se convierten en guiones bajos. Sin embargo, de lo contrario, el nombre debe seguir la forma de un identificador de C#; por ejemplo, no debe comenzar por un número ni contener espacios.

El proyecto resultante incluye una referencia al paquete NuGet de Amazon.CDK.Lib. NuGet lo instala automáticamente, así como a sus dependencias.

Administración de los módulos de la Biblioteca de constructos de AWS

El ecosistema .NET usa el administrador de paquetes NuGet. El paquete CDK principal, que contiene las clases principales y todos los constructos de servicio estables, es Amazon.CDK.Lib. Los módulos experimentales, en los que se está desarrollando una nueva funcionalidad, reciben un nombre como Amazon.CDK.AWS.<SERVICE-NAME>.Alpha, donde el nombre del servicio es un nombre abreviado sin AWS o el prefijo de Amazon. Por ejemplo, el nombre del paquete NuGet del módulo AWS IoT es Amazon.CDK.AWS.IoT.Alpha. Si no encuentra el paquete que quiere, busque en Nuget.org.

El soporte de la Biblioteca de constructos de AWS de algunos servicios se encuentra en más de un módulo. Por ejemplo, AWS IoT tiene un segundo módulo llamado Amazon.CDK.AWS.IoT.Actions.Alpha.

El módulo principal de AWS CDK, que necesitará en la mayoría de las aplicaciones de AWS CDK, se importa en código C# como Amazon.CDK. Los módulos de los distintos servicios de la Biblioteca de constructos de AWS se encuentran como Amazon.CDK.AWS . Por ejemplo, el espacio de nombres del módulo Amazon S3 es Amazon.CDK.AWS.S3.

Recomendamos escribir directivas C# de using para los constructos principales de CDK y para cada servicio de AWS que utilice en cada uno de sus archivos fuente de C#. Puede que le resulte práctico usar un alias para un espacio de nombres o un tipo para resolver conflictos de nombres. Siempre puede utilizar el nombre completo de un tipo (incluido su espacio de nombres) sin una instrucción using.

Administración de dependencias en C#

En las aplicaciones de C# de AWS CDK, las dependencias se administran mediante NuGet. NuGet tiene cuatro interfaces estándar, en su mayoría equivalentes. Utilice la que mejor se adapte a sus necesidades y estilo de trabajo. También puede usar herramientas compatibles, como Paket o MyGet, o incluso editar directamente el archivo .csproj.

NuGet no permite especificar rangos de versiones para las dependencias. Cada dependencia está anclada a una versión específica.

Tras actualizar las dependencias, Visual Studio utilizará NuGet para recuperar las versiones especificadas de cada paquete la próxima vez que compile. Si no usa Visual Studio, use el comando dotnet restore para actualizar las dependencias.

Edición del archivo de proyecto directamente

El archivo del proyecto .csproj tiene un contenedor <ItemGroup> en el que se enumeran las dependencias como elementos <PackageReference.

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

La GUI NuGet de Visual Studio

Se puede acceder a las herramientas NuGet de Visual Studio desde Herramientas > Administrador de paquetes NuGet > Administrar paquete NuGet para obtener una solución. Utilice la pestaña Examinar para buscar los paquetes de la Biblioteca de constructos de AWS que desee instalar. Puede elegir la versión que desee, incluidas las versiones preliminares de sus módulos, y agregarlas a cualquiera de los proyectos abiertos.

Consulte la página de Actualizaciones para instalar nuevas versiones de sus paquetes.

La consola NuGet

La consola NuGet es una interfaz de NuGet basada en PowerShell que funciona en el contexto de un proyecto de Visual Studio. Puede abrirlo en Visual Studio seleccionando Herramientas > Administrador de paquetes NuGet > Consola del Administrador de paquetes. Para obtener más información sobre el uso de esta herramienta, consulte Instalar y administrar paquetes con la consola del Administrados de paquetes en Visual Studio.

El comando dotnet

El comando dotnet es la principal herramienta de línea de comandos para trabajar con proyectos de C# de Visual Studio. Puede invocarlo desde cualquier petición de comandos de Windows. Entre sus múltiples capacidades, dotnet puede agregar dependencias NuGet a un proyecto de Visual Studio.

Suponiendo que se encuentra en el mismo directorio que el archivo de proyecto (.csproj) de Visual Studio, ejecute un comando como el siguiente para instalar un paquete. Como la biblioteca principal de CDK se incluye al crear un proyecto, solo necesita instalar de forma explícita los módulos experimentales. Los módulos experimentales requieren que especifique un número de versión explícito.

dotnet add package Amazon.CDK.AWS.IoT.Alpha -v <VERSION-NUMBER>

Puede ejecutar el comando desde otro directorio. Para hacerlo, incluya la ruta al archivo del proyecto o al directorio que lo contiene después de la palabra clave add. En el siguiente ejemplo se supone que se encuentra en el directorio principal del proyecto de AWS CDK.

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

Para instalar una versión específica de un paquete, incluya el marcador -v y la versión deseada.

Para actualizar un paquete, ejecute el mismo comando dotnet add que utilizó para instalarlo. Para módulos experimentales, nuevamente, debe especificar un número de versión explícito.

Para obtener más información sobre la administración de paquetes mediante el comando dotnet, consulte Instalación y administración de paquetes mediante la CLI de dotnet.

El comando nuget

La herramienta de línea de comandos nuget puede instalar y actualizar paquetes de NuGet. Sin embargo, requiere que el proyecto de Visual Studio se configure de forma diferente a como cdk init configura los proyectos. (Detalles técnicos: nuget funciona con proyectos Packages.config, mientras que cdk init crea un proyecto PackageReference de estilo más nuevo).

No recomendamos el uso de la herramienta nuget con proyectos de AWS CDK creados por cdk init. Si está utilizando otro tipo de proyecto y quiere usar nuget, consulte la Referencia de la CLI de NuGet.

Modismos de AWS CDK en C#

Props

Se crean las instancias de todas las clases de la Biblioteca de constructos de AWS con tres argumentos: el ámbito en el que se define el constructo (su elemento principal en el árbol de constructos), un id y props, un conjunto de pares clave/valor que el constructo utiliza para configurar los recursos que crea. Otras clases y métodos también utilizan el patrón de "agrupación de atributos" como argumento.

En C#, los props se expresan mediante un tipo de props. Al estilo idiomático de C#, podemos usar un inicializador de objetos para establecer las distintas propiedades. Aquí estamos creando un bucket de Amazon S3 con el constructo Bucket; su tipo de props correspondiente es BucketProps.

var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps {
    Versioned = true
});

Al ampliar una clase o anular un método, es posible que desee aceptar props adicionales para sus propios fines que la clase principal no comprenda. Para hacerlo, subclasifique el tipo de props apropiado y agregue los nuevos 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"
});

Al llamar al inicializador o al método anulado de la clase principal, normalmente puede pasar los props que ha recibido. El nuevo tipo es compatible con su principal y los props adicionales que agregue se ignoran.

Una futura versión del AWS CDK podría agregar casualmente una nueva propiedad con el nombre que utilizó para su propiedad. Esto no provocará ningún problema técnico al utilizar el constructo o el método (dado que la propiedad no pasa a un “nivel superior de la cadena”, la clase principal o el método anulado se limitará a utilizar un valor predeterminado), pero podría causar confusión a los usuarios del constructo. Puede evitar este posible problema asignando un nombre a sus propiedades de forma que pertenezcan claramente a su constructo. Si hay muchas propiedades nuevas, agrúpelas en una clase con el nombre adecuado y páselas como una sola propiedad.

Estructuras genéricas

En algunas API, AWS CDK utiliza matrices de JavaScript u objetos sin tipo como entrada a un método. (Consulte, por ejemplo, el método BuildSpec.fromObject() de AWS CodeBuild). En C#, estos objetos se representan como System.Collections.Generic.Dictionary<String, Object>. En los casos en que los valores son todos cadenas, puede utilizar Dictionary<String, String>. Las matrices de JavaScript se representan como tipos de matrices object[] o string[] en C#.

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

Valores faltantes

En C#, los valores que faltan en objetos del AWS CDK como los accesorios se representan mediante null: El operador de acceso a miembros con condiciones nulas ?. y el operador coalescente nulo ?? son prácticos para trabajar con estos 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";

Creación y ejecución de aplicaciones del CDK

AWS CDK compila automáticamente la aplicación antes de ejecutarla. Sin embargo, puede resultar útil compilar la aplicación manualmente para comprobar si hay errores y realizar pruebas. Para hacerlo, presione F6 en Visual Studio o ejecute dotnet build src desde la línea de comandos, donde src es el directorio en su directorio del proyecto que contiene el archivo de la solución de Visual Studio (.sln).