Lavorare con il AWS CDK in C#

.NET è un linguaggio client completamente supportato per AWS CDK ed è considerato stabile. C# è il principale linguaggio.NET per il quale forniamo esempi e supporto. È possibile scegliere di scrivere AWS CDK applicazioni in altri linguaggi.NET, come Visual Basic o F#, ma AWS offre un supporto limitato per l'utilizzo di questi linguaggi con CDK.

È possibile sviluppare AWS CDK applicazioni in C# utilizzando strumenti familiari tra cui Visual Studio, Visual Studio Code, il dotnet comando e il NuGet gestore di pacchetti. I moduli che compongono la AWS Construct Library sono distribuiti tramite nuget.org.

Ti consigliamo di utilizzare Visual Studio 2019 (qualsiasi edizione) su Windows per sviluppare app in C#. AWS CDK

Inizia con C#

Per utilizzare AWS CDK, è necessario disporre di un AWS account e delle credenziali e aver installato Node.js e il AWS CDK Toolkit. Per informazioni, consulta Guida introduttiva al AWS CDK.

AWS CDK Le applicazioni C# richiedono .NET Core v3.1 o versione successiva, disponibile qui.

La toolchain .NET include dotnet uno strumento da riga di comando per la creazione e l'esecuzione di applicazioni.NET e la gestione dei pacchetti. NuGet Anche se lavori principalmente in Visual Studio, questo comando può essere utile per le operazioni in batch e per l'installazione dei pacchetti AWS Construct Library.

Creare un progetto

È possibile creare un nuovo AWS CDK progetto invocandolo cdk init in una directory vuota. Utilizzate l'--languageopzione e specificatecsharp:

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

cdk initutilizza il nome della cartella del progetto per denominare vari elementi del progetto, tra cui classi, sottocartelle e file. I trattini nel nome della cartella vengono convertiti in caratteri di sottolineatura. Tuttavia, il nome dovrebbe altrimenti assumere la forma di un identificatore C#; ad esempio, non dovrebbe iniziare con un numero o contenere spazi.

Il progetto risultante include un riferimento al Amazon.CDK.Lib NuGet pacchetto. Esso e le sue dipendenze vengono installati automaticamente da NuGet.

Gestione dei moduli di AWS Construct Library

L'ecosistema.NET utilizza il gestore di NuGet pacchetti. Il pacchetto CDK principale, che contiene le classi principali e tutti i costrutti di servizio stabili, è. Amazon.CDK.Lib I moduli sperimentali, in cui le nuove funzionalità sono in fase di sviluppo attivoAmazon.CDK.AWS.SERVICE-NAME.Alpha, hanno nomi simili, dove il nome del servizio è un nome breve senza prefisso AWS o Amazon. Ad esempio, il nome NuGet del pacchetto per il AWS IoT modulo èAmazon.CDK.AWS.IoT.Alpha. Se non riesci a trovare il pacchetto che desideri, cerca su NuGet.org.

Il supporto di AWS Construct Library di alcuni servizi è disponibile in più di un modulo. Ad esempio, AWS IoT ha un secondo modulo denominato. Amazon.CDK.AWS.IoT.Actions.Alpha

Il AWS CDK modulo principale, necessario nella maggior parte delle AWS CDK app, viene importato nel codice C# comeAmazon.CDK. I moduli per i vari servizi della AWS Construct Library sono disponibili in. Amazon.CDK.AWS Ad esempio, lo spazio dei nomi del modulo Amazon S3 è. Amazon.CDK.AWS.S3

Ti consigliamo di scrivere using direttive C# per i costrutti principali di CDK e per ogni AWS servizio che usi in ciascuno dei tuoi file sorgente C#. Potrebbe essere utile utilizzare un alias per un namespace o un tipo per risolvere i conflitti tra nomi. Puoi sempre utilizzare il nome completo di un tipo (incluso lo spazio dei nomi) senza una dichiarazione. using

Gestione delle dipendenze in C#

Nelle AWS CDK app C#, gestisci le dipendenze utilizzando. NuGet NuGet ha quattro interfacce standard, per lo più equivalenti. Usa quella più adatta alle tue esigenze e al tuo stile di lavoro. Puoi anche utilizzare strumenti compatibili, come Paket MyGeto persino modificare direttamente il .csproj file.

NuGet non consente di specificare intervalli di versioni per le dipendenze. Ogni dipendenza è associata a una versione specifica.

Dopo aver aggiornato le dipendenze, Visual Studio le utilizzerà NuGet per recuperare le versioni specificate di ogni pacchetto alla successiva compilazione. Se non usi Visual Studio, usa il dotnet restore comando per aggiornare le dipendenze.

Modifica diretta del file di progetto

Il .csproj file del progetto contiene un <ItemGroup> contenitore che elenca le dipendenze come <PackageReference elementi.

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

La GUI di Visual Studio NuGet

NuGet Gli strumenti di Visual Studio sono accessibili da Tools > NuGet Package Manager > Manage NuGet Packages for Solution. Utilizza la scheda Sfoglia per trovare i pacchetti AWS Construct Library che desideri installare. Potete scegliere la versione desiderata, comprese le versioni non definitive dei moduli, e aggiungerla a qualsiasi progetto aperto.

Consultate la pagina Aggiornamenti per installare nuove versioni dei pacchetti.

La NuGet console

La NuGet console è un'interfaccia PowerShell basata su di NuGet essa che funziona nel contesto di un progetto di Visual Studio. Puoi aprirlo in Visual Studio scegliendo Strumenti > NuGet Package Manager > Package Manager Console. Per ulteriori informazioni sull'utilizzo di questo strumento, vedi Installare e gestire i pacchetti con la console Package Manager in Visual Studio.

Il dotnet comando

Il dotnet comando è lo strumento da riga di comando principale per lavorare con i progetti di Visual Studio C#. È possibile richiamarlo da qualsiasi prompt dei comandi di Windows. Tra le sue numerose funzionalità, dotnet può aggiungere NuGet dipendenze a un progetto di Visual Studio.

Supponendo che ti trovi nella stessa directory del file di progetto di Visual Studio (.csproj), esegui un comando come il seguente per installare un pacchetto. Poiché la libreria CDK principale è inclusa quando crei un progetto, devi solo installare esplicitamente i moduli sperimentali. I moduli sperimentali richiedono di specificare un numero di versione esplicito.

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

È possibile eseguire il comando da un'altra directory. A tale scopo, includi il percorso del file di progetto o della directory che lo contiene dopo la add parola chiave. L'esempio seguente presuppone che vi troviate nella directory principale del AWS CDK progetto.

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

Per installare una versione specifica di un pacchetto, includi il -v flag e la versione desiderata.

Per aggiornare un pacchetto, esegui lo stesso dotnet add comando che hai usato per installarlo. Per i moduli sperimentali, ancora una volta, è necessario specificare un numero di versione esplicito.

Per ulteriori informazioni sulla gestione dei pacchetti tramite il dotnet comando, consulta Installare e gestire i pacchetti utilizzando la CLI dotnet.

Il comando nuget

Lo strumento da riga di nuget comando può installare e aggiornare NuGet i pacchetti. Tuttavia, richiede che il progetto di Visual Studio sia configurato in modo diverso dal modo in cui cdk init vengono configurati i progetti. (Dettagli tecnici: nuget funziona con i Packages.config progetti, mentre cdk init crea un PackageReference progetto di nuovo stile.)

Si sconsiglia l'uso dello nuget strumento con AWS CDK progetti creati da. cdk init Se stai utilizzando un altro tipo di progetto e desideri utilizzarlonuget, consulta la NuGet CLI Reference.

AWS CDK idiomi in C#

Oggetti di scena

Tutte le classi di AWS Construct Library vengono istanziate utilizzando tre argomenti: l'ambito in cui viene definito il costrutto (l'elemento principale nell'albero dei costrutti), un id e props, un insieme di coppie chiave/valore che il costrutto utilizza per configurare le risorse che crea. Anche altre classi e metodi utilizzano il modello «bundle of attributes» per gli argomenti.

In C#, gli oggetti di scena vengono espressi utilizzando un tipo di oggetti di scena. In stile C# idiomatico, possiamo usare un inizializzatore di oggetti per impostare le varie proprietà. Qui stiamo creando un bucket Amazon S3 usando il Bucket costrutto; il tipo di oggetto corrispondente è. BucketProps

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

Quando estendi una classe o sovrascrivi un metodo, potresti voler accettare oggetti di scena aggiuntivi per i tuoi scopi che non sono compresi dalla classe principale. Per fare ciò, aggiungete una sottoclasse agli oggetti di scena appropriati e aggiungete i nuovi attributi.

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

Quando chiamate l'inizializzatore o il metodo sovrascritto della classe principale, in genere potete passare gli oggetti di scena che avete ricevuto. Il nuovo tipo è compatibile con il suo genitore e gli oggetti di scena aggiuntivi aggiunti vengono ignorati.

Le future versioni di AWS CDK potrebbero aggiungere casualmente una nuova proprietà con un nome che hai usato per la tua proprietà. Ciò non causerà alcun problema tecnico nell'utilizzo del costrutto o del metodo (poiché la proprietà non viene trasmessa «all'inizio della catena», la classe principale o il metodo sovrascritto utilizzeranno semplicemente un valore predefinito) ma potrebbe creare confusione tra gli utenti del costrutto. Puoi evitare questo potenziale problema denominando le tue proprietà in modo che appartengano chiaramente al tuo costrutto. Se sono presenti molte nuove proprietà, raggruppatele in una classe dal nome appropriato e passatele come un'unica proprietà.

Strutture generiche

In alcuni APIs, AWS CDK utilizza JavaScript matrici o oggetti non tipizzati come input per un metodo. (Vedi, ad esempio, AWS CodeBuild il metodo.) BuildSpec.fromObject() In C#, questi oggetti sono rappresentati comeSystem.Collections.Generic.Dictionary<String, Object>. Nei casi in cui i valori sono tutte stringhe, puoi usare. Dictionary<String, String> JavaScript gli array sono rappresentati come object[] o tipi di string[] array in C#.

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

Valori mancanti

In C#, i valori mancanti in AWS CDK oggetti come props sono rappresentati da. null L'operatore null-conditional member access ?. e l'operatore null coalescente sono utili per lavorare con questi valori. ??

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

Crea ed esegui applicazioni CDK

Compila AWS CDK automaticamente la tua app prima di eseguirla. Tuttavia, può essere utile creare l'app manualmente per verificare la presenza di errori ed eseguire test. Puoi farlo premendo F6 in Visual Studio o eseguendo dotnet build src dalla riga di comando, dove si src trova la directory nella directory del progetto che contiene il file Visual Studio Solution (.sln).