diff --git a/README.md b/README.md index cf8b00c..d538e19 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,7 @@ Run this with the following command: ```powershell # Run the template and publish it to a JSON file. By default this is ./template.json -Publish-PSArmTemplate -Path ./network-interface.psarm.ps1 -Parameters @{ rgLocation = 'WestUS2' } +Build-PSArmTemplate -Path ./network-interface.psarm.ps1 -Parameters @{ rgLocation = 'WestUS2' } # Deploy the template to a resource group using the Az.Resources command New-AzResourceGroupDeployment -ResourceGroupName MyResourceGroup -TemplateFile ./template.json @@ -216,9 +216,9 @@ This will create the following template: For more in-depth examples, see the [examples](examples) directory. -## `Publish-PSArmTemplate` +## `Build-PSArmTemplate` -The `Publish-PSArmTemplate` command is the key cmdlet for executing PSArm templates. +The `Build-PSArmTemplate` command is the key cmdlet for executing PSArm templates. It performs the following tasks: - Collects PSArm template files from the `-Path` parameter, supporting either file paths or directory paths @@ -233,9 +233,9 @@ It performs the following tasks: - If the file already exists this will fail unless `-Force` is used. - `-PassThru` can be specified to also get the full template object from the command - `-NoWriteFile` can be specified to prevent the file being written -- `-Verbose` will give a good account of what `Publish-PSArmTemplate` is doing +- `-Verbose` will give a good account of what `Build-PSArmTemplate` is doing -`Publish-PSArmTemplate` will write a JSON file to disk only, +`Build-PSArmTemplate` will write a JSON file to disk only, and is not intended to deploy the resulting ARM template. Deployment functionality is already provided and maintained in Azure PowerShell commands and the `az` CLI. @@ -281,30 +281,30 @@ within which PSArm offers its DSL functionality, complete with contextual comple The `Arm` keyword then constructs an object representation of an ARM template, which is output when the script is executed. -So when `Publish-PSArmTemplate` is run on these scripts, +So when `Build-PSArmTemplate` is run on these scripts, it simply executes them and collects all the ARM objects they emit. -`Publish-PSArmTemplate` only looks for scripts that end with the `.psarm.ps1` extension +`Build-PSArmTemplate` only looks for scripts that end with the `.psarm.ps1` extension so that it can support being given directory paths. This means you can mix ordinary scripts and PSArm scripts in the same directory -without `Publish-PSArmTemplate` accidentally executing those ordinary scripts. +without `Build-PSArmTemplate` accidentally executing those ordinary scripts. -`Publish-PSArmTemplate` aggregates all the templates it collects into a nested template +`Build-PSArmTemplate` aggregates all the templates it collects into a nested template and writes that out as an ARM JSON file, ready for deployment. ### Variables and parameters PSArm scripts are ordinary PowerShell scripts, -so when they are run (by `Publish-PSArmTemplate` for example) they are simply invoked like any other script. +so when they are run (by `Build-PSArmTemplate` for example) they are simply invoked like any other script. That means you can freely add a `param` block to your PSArm scripts to parameterize them, -and then provide those parameters to `Publish-PSArmTemplate` through its `-Parameters` parameter. +and then provide those parameters to `Build-PSArmTemplate` through its `-Parameters` parameter. Note that the `-Parameters` parameter accepts a hashtable, but will also accept a PSObject, meaning you can do the following: ```powershell $parameters = Get-Content ./parameters.json | ConvertFrom-Json -Publish-PSArmTemplate ... -Parameters $parameters +Build-PSArmTemplate ... -Parameters $parameters ``` Using ordinary PowerShell variables to create ARM scripts will work in many scenarios, @@ -320,7 +320,7 @@ ARM parameters and variables are specified by type; Those parameters and variables then use their PowerShell variable name in their template. They also support PowerShell features like default values and the `ValidateSet` attribute. -When `Publish-PSArmTemplate` instantiates an ARM template, it will try to use any of the values from the `-Parameters` parameter +When `Build-PSArmTemplate` instantiates an ARM template, it will try to use any of the values from the `-Parameters` parameter to also instantiate parameters to the `Arm` block (in addition to the `.psarm.ps1` script). Any parameters it doesn't have a value for will be left in the template and published as part of it, to be provided at deployment. @@ -371,7 +371,7 @@ Arm { Published like this: ```powershell -Publish-PSArmTemplate -TemplatePath ./storageAccount.psarm.ps1 -Parameters @{ +Build-PSArmTemplate -TemplatePath ./storageAccount.psarm.ps1 -Parameters @{ StorageAccountName = 'MyStorageAccount' allowPublicAccess = 1 } diff --git a/docs/Publish-PSArmTemplate.md b/docs/Publish-PSArmTemplate.md index 96d2e4f..87b6eac 100644 --- a/docs/Publish-PSArmTemplate.md +++ b/docs/Publish-PSArmTemplate.md @@ -5,7 +5,7 @@ online version: schema: 2.0.0 --- -# Publish-PSArmTemplate +# Build-PSArmTemplate ## SYNOPSIS Execute PSArm templates and write them as an ARM JSON template file. @@ -13,17 +13,17 @@ Execute PSArm templates and write them as an ARM JSON template file. ## SYNTAX ``` -Publish-PSArmTemplate -TemplatePath [-AzureToken ] [-Parameters ] +Build-PSArmTemplate -TemplatePath [-AzureToken ] [-Parameters ] [-OutFile ] [-PassThru] [-Force] [-NoWriteFile] [-NoHashTemplate] [] ``` ## DESCRIPTION -`Publish-PSArmTemplate` is the primary cmdlet in the PSArm module, +`Build-PSArmTemplate` is the primary cmdlet in the PSArm module, used to execute PSArm template files. It works similarly to `Invoke-Pester` or `Invoke-Build`, where files with a given prefix are found and executed. -`Publish-PSArmTemplate` will execute PSArm scripts given to it, +`Build-PSArmTemplate` will execute PSArm scripts given to it, aggregate them into a nested ARM template, add a hash value to that template, and then write the template out to a JSON file. @@ -35,7 +35,7 @@ such as `New-AzResourceGroupDeployment`. ### Example 1 ```powershell -PS C:\> Publish-PSArmTemplate -TemplatePath ./examples/linux-vm -Parameters @{ +PS C:\> Build-PSArmTemplate -TemplatePath ./examples/linux-vm -Parameters @{ AdminUsername = 'admin' AdminPasswordOrKey = 'verystrongpassword' AuthenticationType = 'password' @@ -49,7 +49,7 @@ If the file already exists, this will fail. ### Example 1 ```powershell PS C:\> $parameters = Get-Content -Raw -Path ./examples/windows-vm/parameters.json | ConvertFrom-Json -PS C:\> Publish-PSArmTemplate -TemplatePath ./examples/windows-vm/windows-vm.psarm.ps1 -Parameters $parameters -OutFile windows-vm.json -Force +PS C:\> Build-PSArmTemplate -TemplatePath ./examples/windows-vm/windows-vm.psarm.ps1 -Parameters $parameters -OutFile windows-vm.json -Force ``` Execute the PSArm template at `./examples/windows-vm/windows-vm.psarm.ps1` @@ -61,9 +61,9 @@ If the file already exists, this will overwrite it. ### -AzureToken An Azure token used to hash the generated template. -By default, `Publish-PSArmTemplate` will try to use `Get-AzAccessToken` and `az accounts get-access-token`, +By default, `Build-PSArmTemplate` will try to use `Get-AzAccessToken` and `az accounts get-access-token`, but supplying a value for this parameter will override that. -If `Publish-PSArmTemplate` is unable to hash the template +If `Build-PSArmTemplate` is unable to hash the template (because it can't get a token or because the token is invalid) and `-NoHashTemplate` isn't specified, the command will fail. diff --git a/src/Commands/PublishPSArmTemplateCommand.cs b/src/Commands/BuildPSArmTemplateCommand.cs similarity index 98% rename from src/Commands/PublishPSArmTemplateCommand.cs rename to src/Commands/BuildPSArmTemplateCommand.cs index 1599521..850d959 100644 --- a/src/Commands/PublishPSArmTemplateCommand.cs +++ b/src/Commands/BuildPSArmTemplateCommand.cs @@ -27,8 +27,12 @@ namespace PSArm.Commands { [OutputType(typeof(ArmNestedTemplate))] - [Cmdlet(VerbsData.Publish, ModuleConstants.ModulePrefix + "Template")] - public class PublishPSArmTemplateCommand : PSCmdlet +#if CoreCLR + [Cmdlet(VerbsLifecycle.Build, ModuleConstants.ModulePrefix + "Template")] +#else + [Cmdlet("Build", ModuleConstants.ModulePrefix + "Template")] +#endif + public class BuildPSArmTemplateCommand : PSCmdlet { private const string DefaultTemplateName = "template.json"; @@ -38,7 +42,7 @@ public class PublishPSArmTemplateCommand : PSCmdlet private readonly CancellationTokenSource _cancellationSource; - public PublishPSArmTemplateCommand() + public BuildPSArmTemplateCommand() { _templateExecutorBuilder = new PSArmTemplateExecutor.Builder(); _cancellationSource = new CancellationTokenSource(); diff --git a/src/PSArm.csproj b/src/PSArm.csproj index 46c0298..c4b9a56 100644 --- a/src/PSArm.csproj +++ b/src/PSArm.csproj @@ -5,7 +5,7 @@ Microsoft Corporation (c) Microsoft Corporation - net471;netcoreapp3.1 + netcoreapp3.1;net471 latest diff --git a/src/PSArm.psd1 b/src/PSArm.psd1 index c50718d..bbcf7e6 100644 --- a/src/PSArm.psd1 +++ b/src/PSArm.psd1 @@ -79,7 +79,7 @@ CmdletsToExport = @( # Commandline cmdlets 'ConvertTo-PSArm' 'ConvertFrom-ArmTemplate' - 'Publish-PSArmTemplate' + 'Build-PSArmTemplate' # DSL cmdlets 'New-PSArmTemplate' diff --git a/test/pester/Conversion.Tests.ps1 b/test/pester/Conversion.Tests.ps1 index 75f2b0b..3f469b5 100644 --- a/test/pester/Conversion.Tests.ps1 +++ b/test/pester/Conversion.Tests.ps1 @@ -11,7 +11,7 @@ Describe "ARM conversion cmdlets" { $psarmScriptPath = Join-Path $TestDrive 'test-template.psarm.ps1' ConvertFrom-ArmTemplate -Path $templatePath | ConvertTo-PSArm -OutFile $psarmScriptPath -Force - $armObject = Publish-PSArmTemplate -TemplatePath $psarmScriptPath -NoWriteFile -NoHashTemplate -PassThru + $armObject = Build-PSArmTemplate -TemplatePath $psarmScriptPath -NoWriteFile -NoHashTemplate -PassThru $armTemplate = $armObject.Resources[0]['properties']['template'] diff --git a/test/pester/Example.Tests.ps1 b/test/pester/Example.Tests.ps1 index 58deaf4..db36d48 100644 --- a/test/pester/Example.Tests.ps1 +++ b/test/pester/Example.Tests.ps1 @@ -35,7 +35,7 @@ Describe "Full ARM template conversions using examples" { $parameters = Get-Content -Raw $parameterPath | ConvertFrom-Json @jsonParams } - $armObject = Publish-PSArmTemplate -TemplatePath $ExamplePath -Parameters $parameters -NoWriteFile -NoHashTemplate -PassThru + $armObject = Build-PSArmTemplate -TemplatePath $ExamplePath -Parameters $parameters -NoWriteFile -NoHashTemplate -PassThru # Deal with PSVersion separately since otherwise tests run across powershell versions will fail $metadataPSVersion = $armObject.Metadata.GeneratorMetadata['psarm-psversion'].Value