Currently ArmDslProviderScriptProducer generates a large string of several function definitions (e.g. function keywordName { }) and dot sources it.

If it instead produced a Dictionary<string, ScriptBlock> (where string is the keyword/function name and ScriptBlock is the body) it could be passed to ScriptBlock.InvokeWithContext. That method will start a new scope and then define the functions to avoid overriding keywords from the current scope when a naming conflict occurs.

The most magical part of PSArm at the moment is the way ARM parameters and variables are created. We should also allow users to create these objects easily (perhaps with New-PSArmVariable and New-PSArmParameter -- these could even create the variables as PowerShell variables themselves). There are some problems to solve here around not needing to respecify the variable name and knowing when we create the template which variables were used, but I think they should be solvable.

In particular, an Import-ArmTemplate command would be useful to get users started from ARM templates, moving toward a PSArm setup.

Whilst this is a far out request, I would love to see PSARM have an integration point to DSC (or better yet the Azure Policy/Guest Configuration engines - one for @mgreenegit to ponder I think) so that I can deploy an environmen, in an apply and monitor state and get updates on whether the environment has diverged from the intended state or not.

I could do this with reoccurring scheduled builds and running the -WhatIf flag on the New-AzDeployment cmdlets, however that seems less optimal than it being native in the platform anyway

PSArm should check templates for validity at generation time, for example attempting to validate that all elements supplied to Concat can be concatted...

Template elements and functions should ideally have a general purpose type checking override/visitor for this

There's no strong reason to require that all resources be named, since PSArm can take a resource definition and pass it around as a variable reference. With that in mind, PSArm should support anonymous resources where users can simply define an unnamed resource and pass it by variable reference rather than by name.

Related to #32: when does a variable resolve to a name reference vs the full template value?

• CI tasks
• Signing
• Compliance tasks
• Publication as GH release
• Publication to PSGallery

From #10:

So based on my current understanding, ARM templates can have an API profile, which is essentially a set of default API versions for resources (but which can be clever when deploying to particular instances of Azure).

This is conceptually simple, although probably some work to implement:

• Have a list of API profiles to complete on
• When resources are passed up to the template level with no API version, we search through the given profile to get the appropriate version and set it
• We need some way of recording and searching API profiles -- this is the labour-intensive part. In particular we need to be able to minimise the amount of servicing we need to do to keep these up to date

The small DSL schemas we have currently have been written by hand. This will not scale in terms of maintenance and instead we should be generating these schemas with autorest. We should develop a prototype of such a tool and add it to this repository to allow the generation of new DSL schemas as needed.

Provide a way to reference existing resources by ID and have the details of that resource brought in from Azure for the purposes of dependency handling. This would be really difficult to handle via intellisense so maybe instead a similar script that would get the ARM JSON for an existing resource and convert it similar to an arm automation file in #55

PowerShell has function definition as a natural concept for code reuse. ARM also has functions, but they are evaluated at deployment. We should investigate to what extent we can use PowerShell functions as ARM functions, where the line must be drawn, and what behaviour makes the most sense from users' perspective

Since I set up signing in October, it's changed on us. In order to release we'll need to move to the new compliance and signing setup

Currently keywords that contribute to array values still use plural names. We should use something like Pluralize.NET to depluralise these keywords

The prototypes we've written may be useful later on and are good history for the codebase, but shouldn't confuse newcomers to the codebase. We should find somewhere to put them, either in the file structure or in the git branch structure, that will preserve them appropriately without them getting in the way

It should be possible to declare multiple templates in PSArm and relate them by a depends-on relationship, so that templates can compose and be built/deployed in the correct order.

This should be available in both an explicit and implicit form, so that a template can explicitly depend on another, or have a dependency inferred automatically at build time through some other reference mechanism.

PSArm currently uses a number of cmdlets and objects to represent ARM templates as it builds. These should be presented publicly as a sort of get-your-hands-dirty way to craft the raw components of an ARM template with no DSL magic

PSArm needs tests to ensure that it works and undergoes no regressions.

Some test ideas:

• Tests should evaluate JSON structural equivalence
• Pester tests
  • A simple template conversion using schema keywords
  • Template generation using non-schema template function primitives
  • Specific tests for template elements or specific scenarios:
    • Output
    • Parameter validation/metadata attributes
• xUnit tests
  • Internal APIs and layer contracts

Currently PSArm exposes "strongly typed" template generation, where templates are generated from functions defined from schemas. However, sometimes the user needs to bypass the guard rails in the tool because they know better or otherwise want to implement a not-yet-implemented scenario.

PSArm actually currently uses this method itself for template generation with these commands and exposes them for reuse, but we should formalise usage to make this a supported scenario.

• Templates should all be merged into one
• Output template should be a nested template

Currently PSArm makes it simple to define, for example, a resource:

Resource ... {
}

By just defining it inline in the script, the result is emitted, captured by the enclosing context and turned into a template element.

However, in many cases it's desirable to define something like a resource and reuse it like:

$r = Resource ... {
}

In these cases, the value will be saved in the variable and will be reusable in other expressions, but will not be emitted.

Ideally we could have our cake and eat it too in some way; we need to make the scenario of passing template elements around as variables or other references more ergonomic. In particular:

• What's the best/most explicit way to emit a template element stored in a variable? Should it be as simple as stating the variable like $r or should we provide an explicit command to make it more obvious/readable and possible perform checks, like Resource $r?
• To what extent can or should we try to be clever with template variables being used and passed around in PSArm declarations? Should we just copy the value in, or try to cleverly calculate things like template references for deduplication?

Currently when execution fails with templates it can be very difficult to work out what's gone wrong. We need to invest effort into improving specificity and debugability of error messages so that they look and behave as close to a standard PowerShell execution error as possible. Users shouldn't need to be looking at internal DSL function definitions.

The idea would that in the same way Invoke-Pester is able to process either an object passed to the Script Parameter, or recurse a directory for *.Tests.ps1 files and process them, Publish-ArmTemplate should accept both Template objects on the Template Parameter, and also a directory.

It would then hopefully recurse the directory for say *.Arm.ps1 files, and process them as if they had been individually imported and passed to the cmdlet.

This would enable bulk processing of multiple ARM templates with ease.

Invoke-Pester Docs

Currently, ARM variables are added to templates with a flawed runtime variable inference logic. Rather than this, we should use explicit variable declarations in parameter blocks that allow for a maximum of metadata while also working as expected at runtime

Example:

"[variables('environmentSettings')[parameters('environmentName')].instanceSize]"

While the typescript plugin works somewhat today, a C# version would make code reuse and maintenance easier

Although having generated ARM templates as an IR can help shed light on the functioning of PSArm features, integrating with ARM's WhatIf functionality would make this nicer to use

Currently we generate ARM schemas ahead of time and ship them as part of the module.

This forces a blowout in module size and forces users to bear the cost of the whole platform area.

However, there are some large hurdles here:

• Can we do this without shipping autorest and relying on it internally? Needing to ship autorest and run it on platforms would probably rule runtime generation out
• Alternatively we generate things ahead of time but download them on demand, but where? What if users don't want the module making network calls?
• How do we make intellisense work for schemas before they exist, since in some cases it would currently provide completions for all available resource providers? If we interpret the rest of a completion as a *, then a prefixless completion would try to generate everything (or nothing), which wouldn't work

In order to show that PSArm is a worthwhile investment, and to help us better understand where to make investments in PSArm itself, we need some way to register that an ARM template was created with PSArm.

To do this, we need to reuse Bicep's concept from Azure/bicep#800.

Users will be able to opt out simply by deleting the added metadata fields.

Currently we only have example schemas for Microsoft.Network and Microsoft.Storage. We should add several more schemas for the DSL to be of use to those wishing to try it out

It can be convenient in some cases to provide a hashtable as a body rather than a scriptblock-drived keyword block. We should make this possible in RawEntry and in keyword definitions

That way, ARM objects that we define will format nicely in the terminal, making interactive use easier.

The README is currently all the documentation we have and it's out of date.

We need to:

• Come up with new motivating scenarios and create them as tests/executable examples
• Rewrite the README with better info
• Record a new authoring GIF around template writing

A number of keywords use common subkeys like name, id, tags, etc. We should elevate those to parameters when possible.

DSL commands, particularly ARM expression commands, should be namespaced -- ideally in the form of PowerShell modules

Currently null entries seem to appear in ARM objects in a random way when they should probably not be included when null. However we should also ensure that there are no valid cases for sending up a null value.

https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/copy-resources

We used to support ValidateSet attributes on ARM parameters. Currently we have most of that work done, but just need to implement a check in New-PSArmTemplate

PSArm should strive to provide static feedback on templates as the user writes them, rather than just at generation time. This would be best achieved by it shipping its own PSScriptAnalyzer rules. Related to #36

Key questions:

• Should the Arm keyword simply define a declaration, or should it emit a template to a file? Should we need to assign it to a variable to use or should we lean on convention to make it just do the right thing?
• Is there value in something like an .arm.ps1 file extension?
• What other user-facing (i.e. non-DSL) cmdlets do we need to supply?
  • A "watch"-style command to get JSON on the fly?
  • A "deploy" command? Currently served by reusing New-AzResourceGroupDeployment

Currently we just treat the API version parameters as settable data, even though these fields hugely affect the shape of APIs.

We need a mechanism to sort APIs by version and allow cataloguing and completing on API versions for resources, as well as having a reasonable scheme for setting the template-wide API version.

As the ARM team made Bicep Public it would make sense to make this repo public soon as well or do you want to wait until a more featured v0.1 release

Ideally an ARM template with limited expressions such as what is output from the Azure Portal "download a template for automation" would be supported to be converted to the PSArm equivalent.

• Compile/build module
• Validate layout
• Validate documentation
• Run Pester tests
• Run xUnit tests
• Validate documentation
• Platforms
  • WinPS on Windows
  • PS 7 on Windows
  • PS 7 on macOS
  • PS 7 on Ubuntu