Trabajando con el AWS CDK en C#

.NET es un lenguaje de cliente totalmente compatible AWS CDK y se considera estable. C# es el lenguaje principal de .NET para el que ofrecemos ejemplos y soporte. Puede escribir AWS CDK aplicaciones 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 AWS CDK aplicaciones en C# con herramientas conocidas, como Visual Studio, Visual Studio Code, el dotnet comando y el NuGet administrador de paquetes. Los módulos que componen la biblioteca AWS Construct se distribuyen a través de nuget.org.

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

Comience con C#

Para trabajar con el AWS CDK, debe tener una AWS cuenta y credenciales y tener instalados Node.js y el AWS CDK kit de herramientas. Consulte Empezando con la AWS CDK.

AWS CDK Las aplicaciones de C# 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 AWS Construct Library.

Creación de un proyecto

Para crear un AWS CDK proyecto nuevo, se invoca 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 Amazon.CDK.Lib NuGet paquete. Tanto él como sus dependencias se instalan automáticamente mediante NuGet.

Gestión de los módulos de AWS Construct Library

El ecosistema.NET usa el administrador de NuGet paquetes. 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 similarAmazon.CDK.AWS.SERVICE-NAME.Alpha, donde el nombre del servicio es un nombre abreviado sin el prefijo AWS o de Amazon. Por ejemplo, el nombre NuGet del paquete del AWS IoT módulo esAmazon.CDK.AWS.IoT.Alpha. Si no encuentra el paquete que quiere, busque en Nuget.org.

El soporte de AWS Construct Library de algunos servicios se encuentra en más de un módulo. Por ejemplo, AWS IoT tiene un segundo módulo llamadoAmazon.CDK.AWS.IoT.Actions.Alpha.

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

Recomendamos escribir using directivas de C# para las construcciones principales de CDK y para cada AWS servicio 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 usar el nombre completo de un tipo (incluido su espacio de nombres) sin una instrucción using.

Administrar las dependencias en C#

En las AWS CDK aplicaciones de C#, 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 utilizar herramientas compatibles, como Paket, MyGeto incluso editar el .csproj archivo directamente.

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á Visual Studio 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 de Visual Studio NuGet

Se puede acceder a NuGet las herramientas de Visual Studio desde Herramientas > Administrador de NuGet paquetes > Administrar NuGet paquetes para la solución. Utilice la pestaña Examinar para buscar los paquetes de AWS Construct Library 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.

NuGet La consola

La NuGet consola es una interfaz PowerShell basada NuGet que funciona en el contexto de un proyecto de Visual Studio. Puede abrirlo en Visual Studio seleccionando Herramientas > Gestor de NuGet paquetes > Consola de Package Manager. 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 muchas capacidades, dotnet puede añadir NuGet dependencias 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 nuget comandos puede instalar y actualizar NuGet paquetes. 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 nuget herramienta con AWS CDK proyectos creados porcdk init. Si está utilizando otro tipo de proyecto y quiere usarlonuget, consulte la referencia de NuGet CLI.

AWS CDK modismos en C#

Props

Todas las clases de AWS Construct Library se instancian con tres argumentos: el ámbito en el que se define la construcción (su elemento principal en el árbol de construcciones), un identificador y props, un conjunto de pares clave/valor que la construcción utiliza para configurar los recursos que crea. Otras clases y métodos también utilizan el patrón de “conjunto 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 añadir casualmente una nueva propiedad con el nombre que utilizó para su propia 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 algunos APIs, AWS CDK utiliza JavaScript matrices u objetos sin tipo como entrada a un método. (Consulte, por ejemplo, el método AWS CodeBuild de BuildSpec.fromObject()). 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> JavaScript las matrices se representan como object[] tipos de string[] matrices 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 AWS CDK objetos 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

Compila AWS CDK 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).