Bicep-generated files should include an autogenerated header

[snarkywolverine]

When a resource file is created in visual studio, a programming language-specific file is autogenerated for resource access. At the top is a comment that looks something like this:

//------------------------------------------------------------------------------
//
// This code was generated by a tool.
// Runtime Version:4.0.30319.42000
//
// Changes to this file may cause incorrect behavior and will be lost if
// the code is regenerated.
//
//------------------------------------------------------------------------------

We should have something similar for bicep - a comment that says the file was autogenerated and the bicep version.

This discourages users from modifying the bicep file directly; it also (as @alex-frankel pointed out) allows the service to potentially collect telemetry on the # of deployments using compiled templates.

[majastrz]

Discussed it at the team meeting today. The consensus appears to have template code generators use the top-level metadata property to store this information. This is the proposed schema:

"metadata": {
  "_generator": {
    "name": "<name of the code generator>",
    "version": "<version of the code generator>",
    "templateHash": "<template hash>"
  }
}

Considerations:

• Discussed using a comment instead of a JSON property. We're not in favor of using meaningful comments due to their fragility and uneven support in JSON libraries across all the relevant platforms.
• Template hash logic should reuse the existing template hash calculation logic that we already have in ARM telemetry and exposed in the API at https://github.com/Azure/azure-rest-api-specs/blob/8cef8014762a839e98f0aeaa57a0bbdb8982d3d4/specification/resources/resource-manager/Microsoft.Resources/stable/2020-10-01/resources.json#L4236
• Template hash calculation should run on the entire content of the template except for the metadata._generator.templateHash property. This is technically a breaking change in ARM, but impact should be extremely low.
• Also discussed adding a top-level multi-line comment with text similar to "This file is generated. Do not modify." This should be deferred until we fix bugs in line number handling in the runtime.

[rjmholt]

One thing that would be nice in the case of other generators is a way to add metadata around that generator's use, like a kind of user-agent string — for example with a PowerShell-based generator, the PowerShell version used. That would help us understand where to make investments/who to optimise our generator for.

Whether that is just the _generator.name or some other field(s)/object under _generator is something I'm certainly very flexible on.