# AWS CDK in PowerShell

## What is CDK?

The [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/) is an open-source software development framework to define your cloud application resources using familiar programming languages.

## Why write AWS CDK in PowerShell?

Writing AWS CDK in PowerShell allows PowerShell users to leverage their existing PowerShell development skills to deploy AWS resources.

## Prerequisites

- [AWS CDK Toolkit](https://docs.aws.amazon.com/cdk/v2/guide/cli.html)
- PowerShell 7.0 or later
- .NET Core v3.1 or later
- [Nuget cli](https://learn.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference)
- AWS credentials
- Internet connectivity to the Nuget package source

## How to Use

### Creating a Package

1. Import Amazon.PowerShell.CDK module
2. Run `New-CdkPackage -Path <PATH> -Template <TEMPLATE_NAME>` # Specify an empty directory

### Write a CDK app in PowerShell

The previous steps create a CDK directory. Under the root of the package, there are cdk.json and `<template>-app.ps1`. You can update `<template>-app.ps1` to define what goes into a CloudFormation stack CDK deploys.

### Deploy the CDK App

- `cdk synth`
- `cdk bootstrap` # Optional if you have not deployed a CDK app before
- `cdk deploy`  

## Advanced

### Under the hood

The `Amazon.PowerShell.CDK` PowerShell module provides functionalities similar to `cdk init` by creating a new CDK package and installing dependencies. Dependencies are defined in the packages.ps1 file under the root of this package. The dependencies are required to import `AWS.CDK.Lib` for AWS CDK v2 in C#.

When `Install-CdkPackage` is invoked within `New-CdkPackage`, it downloads a NuGet package for each dependency under `packages` directory. `Import-CdkPackages` should be invoked at the beginning of the main CDK app PowerShell file in order to load dependencies. If you invoke `Import-CdkPackages` to import CDK packages on PowerShell session, you do not need to invoke `Import-CdkPackages` within CDK scripts. Also, ensure to update the `app` value in cdk.json to point to the main PowerShell file if you use a custom file name.

### Writing unit tests

All the templates generated by AWS.CDK.PowerShell module include unit tests. Those unit tests use [Pester](https://pester.dev/) as a test and mock framework. Pester is the ubiquitous test and mock framework for PowerShell For CDK constructs, For assertions, [Amazon.CDK.Assertions](https://docs.aws.amazon.com/cdk/api/v2/dotnet/api/Amazon.CDK.Assertions.html) is used to assert. Amazon.CDK.Assertions has functions for writing test asserting against CDK applications, with focus on CloudFormation templates.

```powershell
cd <CDK package directory>
Invoke-Pester .\
```

### Updating AWS.CDK.Lib version

If you need a newer version of AWS.CDK.Lib in order to use new constructs or benefit from updates, you can update `packages.ps1` file under `Config` directory. The `packages.ps1` file includes a list of packages required to use `Amazon.CDK.Lib`. You will need to update the version of `Amazon.CDK.Lib` and dependencies. This change may require an update of CDK toolkit and .NET core version.

## Troubleshooting

> The specified module 'AWS.CDK.PowerShell' was not loaded because no valid module file was found in any module directory.

Make sure to add the AWS.CDK.PowerShell module path to $ENV:PSModulePath or move AWS.CDK.PowerShell module to one of the existing paths for $ENV:PSModulePath.

> Exception calling ".ctor" with "3" argument(s): "Child process exited unexpectedly!"

While instantiating objects or calling CDK functions, you may receive the error. Reload your PowerShell session.

> New-Object: The value supplied is not valid, or the property is read-only. Change the value, and then try again.

You may be using a wrong object type for one or more of the property values.

> Fails to load a module with an error with `RuntimeException: Unable to load C:\Users\test\AppData\Local\Temp\blank-template\packages\Amazon.CDK.Lib.2.37.1\lib\netcoreapp3.1\Amazon.CDK.Lib.dll`

Make sure that CDK packages are installed under the CDK package directory.

## References

- [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/)
- [AWS CDK Toolkit](https://docs.aws.amazon.com/cdk/v2/guide/cli.html)
- [CDK .NET Reference](https://docs.aws.amazon.com/cdk/api/v2/dotnet/api/index.html)
- [Pester](https://pester.dev/)

## License

This project is licensed under the Apache-2.0 License.