Travailler avec le AWS CDK en C#

. NETest une langue client entièrement prise en charge pour le AWS CDK et est considérée comme stable. Le C# est le principal. NETlangue pour laquelle nous fournissons des exemples et une assistance. Vous pouvez choisir d'écrire des AWS CDK applications dans un autre format. NETlangages, tels que Visual Basic ou F#, mais AWS offre un support limité pour l'utilisation de ces langages avec leCDK.

Vous pouvez développer des AWS CDK applications en C# à l'aide d'outils familiers tels que Visual Studio, Visual Studio Code, la dotnet commande et le gestionnaire de NuGet packages. Les modules composant la bibliothèque AWS Construct sont distribués via nuget.org.

Nous vous conseillons d'utiliser Visual Studio 2019 (n'importe quelle édition) sous Windows pour développer des AWS CDK applications en C#.

Commencez avec C#

Pour utiliser le AWS CDK, vous devez disposer d'un AWS compte et d'informations d'identification et avoir installé Node.js et le AWS CDK Toolkit. Consultez Commencer à utiliser le AWS CDK.

Les AWS CDK applications C# nécessitent. NETCore v3.1 ou version ultérieure, disponible ici.

Le. NETLa chaîne d'outils inclut dotnet un outil en ligne de commande pour la création et l'exécution. NETapplications et gestion des NuGet packages. Même si vous travaillez principalement dans Visual Studio, cette commande peut être utile pour les opérations par lots et pour installer les packages AWS Construct Library.

Création d’un projet

Vous créez un nouveau AWS CDK projet en l'invoquant cdk init dans un répertoire vide. Utilisez l'--languageoption et spécifiez csharp :

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

cdk initutilise le nom du dossier du projet pour nommer les différents éléments du projet, notamment les classes, les sous-dossiers et les fichiers. Les traits d'union figurant dans le nom du dossier sont convertis en traits de soulignement. Toutefois, le nom doit sinon prendre la forme d'un identifiant C# ; par exemple, il ne doit pas commencer par un chiffre ni contenir d'espaces.

Le projet qui en résulte inclut une référence au Amazon.CDK.Lib NuGet package. Il et ses dépendances sont installés automatiquement par NuGet.

Gestion des modules AWS de la bibliothèque Construct

Le. NETL'écosystème utilise le gestionnaire de NuGet packages. Le CDK package principal, qui contient les classes de base et toutes les constructions de service stables, estAmazon.CDK.Lib. Les modules expérimentaux, dans lesquels de nouvelles fonctionnalités sont en cours de développement actifAmazon.CDK.AWS.SERVICE-NAME.Alpha, sont nommés comme suit : le nom du service est un AWS nom court sans préfixe Amazon. Par exemple, le nom NuGet du package pour le AWS IoT module estAmazon.CDK.AWS.IoT.Alpha. Si vous ne trouvez pas le package que vous recherchez, recherchez NuGet.org.

La prise en charge de la bibliothèque AWS Construct par certains services se trouve dans plusieurs modules. Par exemple, AWS IoT possède un deuxième module nomméAmazon.CDK.AWS.IoT.Actions.Alpha.

Le AWS CDK module principal, dont vous aurez besoin dans la plupart des AWS CDK applications, est importé en code C# sous Amazon.CDK le nom de. Les modules des différents services de la bibliothèque AWS Construct se trouvent sous cette rubriqueAmazon.CDK.AWS. Par exemple, l'espace de noms du module Amazon S3 estAmazon.CDK.AWS.S3.

Nous vous recommandons d'écrire using des directives C# pour les constructions de CDK base et pour chaque AWS service que vous utilisez dans chacun de vos fichiers source C#. Il peut être pratique d'utiliser un alias pour un espace de noms ou un type afin de résoudre les conflits de noms. Vous pouvez toujours utiliser le nom complet d'un type (y compris son espace de noms) sans instruction. using

Gestion des dépendances dans C#

Dans les AWS CDK applications C#, vous gérez les dépendances à l'aide NuGet de. NuGet possède quatre interfaces standard, pour la plupart équivalentes. Utilisez celui qui correspond à vos besoins et à votre style de travail. Vous pouvez également utiliser des outils compatibles, tels que Paket MyGetou même modifier directement le .csproj fichier.

NuGet ne vous permet pas de spécifier des plages de versions pour les dépendances. Chaque dépendance est associée à une version spécifique.

Après avoir mis à jour vos dépendances, Visual Studio récupérera les versions spécifiées de chaque package lors de la prochaine génération. NuGet Si vous n'utilisez pas Visual Studio, utilisez la dotnet restore commande pour mettre à jour vos dépendances.

Modification directe du fichier de projet

Le .csproj fichier de votre projet contient un <ItemGroup> conteneur qui répertorie vos dépendances sous forme d'<PackageReferenceéléments.

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

Le Visual Studio NuGet GUI

Les NuGet outils de Visual Studio sont accessibles depuis Outils > Gestionnaire de NuGet packages > Gérer les NuGet packages pour la solution. Utilisez l'onglet Parcourir pour rechercher les packages AWS Construct Library que vous souhaitez installer. Vous pouvez choisir la version souhaitée, y compris les versions préliminaires de vos modules, et les ajouter à tous les projets ouverts.

Consultez la page Mises à jour pour installer les nouvelles versions de vos packages.

La NuGet console

La NuGet console est une interface PowerShell basée NuGet qui fonctionne dans le contexte d'un projet Visual Studio. Vous pouvez l'ouvrir dans Visual Studio en choisissant Outils > Gestionnaire de NuGet packages > Console du gestionnaire de packages. Pour plus d'informations sur l'utilisation de cet outil, voir Installer et gérer des packages à l'aide de la console Package Manager dans Visual Studio.

La dotnet commande

La dotnet commande est le principal outil de ligne de commande permettant de travailler avec des projets Visual Studio C#. Vous pouvez l'invoquer à partir de n'importe quelle invite de commande Windows. Parmi ses nombreuses fonctionnalités, dotnet vous pouvez ajouter NuGet des dépendances à un projet Visual Studio.

En supposant que vous vous trouvez dans le même répertoire que le fichier de projet Visual Studio (.csproj), exécutez une commande comme celle-ci pour installer un package. Comme la CDK bibliothèque principale est incluse lorsque vous créez un projet, il vous suffit d'installer explicitement des modules expérimentaux. Les modules expérimentaux nécessitent que vous indiquiez un numéro de version explicite.

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

Vous pouvez exécuter la commande depuis un autre répertoire. Pour ce faire, incluez le chemin du fichier de projet ou du répertoire qui le contient après le add mot clé. L'exemple suivant suppose que vous vous trouvez dans le répertoire principal de votre AWS CDK projet.

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

Pour installer une version spécifique d'un package, incluez le -v drapeau et la version souhaitée.

Pour mettre à jour un package, exécutez la même dotnet add commande que celle que vous avez utilisée pour l'installer. Pour les modules expérimentaux, vous devez à nouveau spécifier un numéro de version explicite.

Pour plus d'informations sur la gestion des packages à l'aide de la dotnet commande, voir Installer et gérer des packages à l'aide du dotnet CLI.

La nuget commande

L'outil de ligne de nuget commande peut installer et mettre à jour NuGet des packages. Cependant, cela nécessite que votre projet Visual Studio soit configuré différemment de la manière dont cdk init les projets sont configurés. (Détails techniques : nuget fonctionne avec des Packages.config projets, tout en cdk init créant un projet de style plus récentPackageReference.)

Nous ne recommandons pas l'utilisation de l'nugetoutil avec AWS CDK des projets créés parcdk init. Si vous utilisez un autre type de projet et que vous souhaitez l'utilisernuget, consultez la NuGet CLIréférence.

AWS CDK expressions idiomatiques en C#

accessoires

Toutes les classes de la bibliothèque de AWS construction sont instanciées à l'aide de trois arguments : la portée dans laquelle la construction est définie (son parent dans l'arbre de construction), un identifiant, et props, un ensemble de paires clé/valeur que la construction utilise pour configurer les ressources qu'elle crée. D'autres classes et méthodes utilisent également le modèle « bundle of attributes » pour les arguments.

En C#, les accessoires sont exprimés à l'aide d'un type d'accessoire. En langage C# idiomatique, nous pouvons utiliser un initialiseur d'objet pour définir les différentes propriétés. Nous créons ici un compartiment Amazon S3 à l'aide de cette Bucket construction ; le type d'accessoire correspondant estBucketProps.

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

Lorsque vous étendez une classe ou que vous remplacez une méthode, vous souhaiterez peut-être accepter des accessoires supplémentaires pour vos propres besoins qui ne sont pas compris par la classe parent. Pour ce faire, sous-classez le type d'accessoire approprié et ajoutez les nouveaux attributs.

// 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"
});

Lorsque vous appelez l'initialiseur ou la méthode remplacée de la classe parent, vous pouvez généralement transmettre les accessoires que vous avez reçus. Le nouveau type est compatible avec son parent et les accessoires supplémentaires que vous avez ajoutés sont ignorés.

Une future version du AWS CDK pourrait par hasard ajouter une nouvelle propriété avec un nom que vous avez utilisé pour votre propre propriété. Cela ne posera aucun problème technique lors de l'utilisation de votre construction ou de votre méthode (étant donné que votre propriété n'est pas transmise « en haut de la chaîne », la classe parent ou la méthode remplacée utilisera simplement une valeur par défaut) mais cela peut être source de confusion pour les utilisateurs de votre construction. Vous pouvez éviter ce problème potentiel en nommant vos propriétés de manière à ce qu'elles appartiennent clairement à votre construction. S'il existe de nombreuses nouvelles propriétés, regroupez-les dans une classe portant le nom approprié et transmettez-les en tant que propriété unique.

Structures génériques

Dans certains casAPIs, ils AWS CDK utilisent des JavaScript tableaux ou des objets non typés comme entrée dans une méthode. (Voir, par exemple, AWS CodeBuild la BuildSpec.fromObject()méthode.) En C#, ces objets sont représentés par. System.Collections.Generic.Dictionary<String, Object> Dans les cas où les valeurs sont toutes des chaînes, vous pouvez utiliserDictionary<String, String>. JavaScript les tableaux sont représentés sous forme object[] de types de string[] tableaux en C#.

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

Valeurs manquantes

En C#, les valeurs manquantes dans les AWS CDK objets tels que les accessoires sont représentées par. null L'opérateur d'accès conditionnel nul aux membres ?. et l'opérateur de coalescence nul ?? sont pratiques pour travailler avec ces valeurs.

// 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";

Créez et exécutez des CDK applications

Compile AWS CDK automatiquement votre application avant de l'exécuter. Cependant, il peut être utile de créer votre application manuellement pour vérifier les erreurs et exécuter des tests. Vous pouvez le faire en appuyant sur F6 dans Visual Studio ou en dotnet build src indiquant à partir de la ligne de commande le répertoire de votre projet contenant le fichier Visual Studio Solution (.sln). src