Support for Parameter Aliasing?

[StartAutomating]

In a quick look at the schemas, I don't think I've seen anything to support resource / parameter aliasing.

In my opinion, aliasing support is a big part of what can make PowerShell more usable.

I think this is especially potent when PowerShell connects to other ecosystems, as naming in PowerShell tends to be more "natural" than the underlying native name.

Would it be possible to slightly extend the schemas and commands to support aliasing, so that these resources can be used more flexibly?

[SteveL-MSFT]

The current design aligns more with the PowerShell best practice of module qualified cmdlet naming. Aliases are very useful when used interactively, but for a configuration (like a script), the desire is to be fully qualified such that you get exactly what you expect. If you can provide a clear user scenario where aliases would be used and recommended, we can consider it.

[StartAutomating]

There are a couple of clear scenarios, in my opinion:

Increased Clarity

Much of the technical world believes brevity to be the soul of wit. If we are mapping directly to an underlying resource with an obscure parameter name, carrying on that parameter name will make the resulting resource as unclear as it's source. Thus for usability, most resource parameters will already effectively be an alias.

Of course, this presents an obvious problem:

Decreased Error Routes

If I were to know the underlying subsystem first, and be learning PowerShell, I'd be more likely to presume a configuration value that directly maps to the obscure switch. And I would then be wrong and have a bad user experience around DSC.

I'd argue every time someone puts a name in for a parameter that they believe should be obvious, and it is not supported in favor of a slightly different variant, they have a bad customer experience. (e.g. it wasn't -FunctionName, it was -Function).

This is why I've come to adopt the user-friendly maxim of "don't worry, be alias happy".

Aliases make people happy

At present this is the only part of PowerShell that is not capable of being alias happy. Aliases have long proven their value within the ecosystem. For many people, this might be their first time using PowerShell. Why not show it the good side?

Also, pipeline by name binding

If using ValueFromPipelineByPropertyName, the more aliases I have, the more objects I can work with.

Being able to cleanly pipe N different objects into similar resources would be quite powerful.

Conclusion & Rebuttal

This covers several arguments for aliasing. I hope it has made the benefits clear. To rebut one point: if the desire is to be "fully qualified", aliases do not prevent that in the least. Since they all map to the same parameter, it is still "fully qualified".

Hope this Helps!

[michaeltlombardi]

For context, my response is grounded in the following points:

• DSC is a tool for infrastructure as code first, interactive use second.
• You will read key-value pairs in DSC configuration documents (or the equivalent in higher order tools leveraging DSC) more often than you will write them, over the operational life of any given configuration document or snippet.
• DSC is a standalone executable, written in Rust, that returns JSON output, and is interoperable with higher order tools like Machine Configuration, WinGet, Ansible, etc.

Given those points of context, I want to address yours:

• Increased clarity: The properties of a DSC Resource are defined by a JSON Schema. The canonical property names are defined by the resource author for their users. If the property names are obscure or difficult to understand, that's a bug in the resource implementation. Adding aliases, especially user-defined aliases, would not make this problem go away - when serializing the data to JSON, the canonical property name has to be used for interoperability.

• Decreased error routes: In this point you're discussing decreasing the number of errors users make when authoring configuration documents. I don't think aliases address this issue, because instead of referencing the JSON Schema to understand what properties control what component behavior, you need to dereference the alias to the property schema - and even then, you're hoping that the schema is sufficiently implemented and documented.

  Further, there's increased error routes for integrating tooling - they also need to support dereferencing aliases to the appropriate schema property. This complicates the logic and adds new edge cases both to DSC itself and to integration code for other tools.

• Aliases make people happy: One of the most common uses I hear (and leverage myself) for aliases is to reduce typing and reuse a semantic that I learned earlier. Long standing community guidance for infrastructure as code scripts has been not to use aliases for commands or parameters, because explicit definition supercedes convenience when you're authoring infrastructure code. When I worked at a configuration management vendor, I spent a lot of time explaining to people (and having my explanation painfully reinforced in many cases) that ambiguity in your infrastructure code only leads to errors, debugging difficulties, and confusion in the long run. It's arguably more work to be explicit up front, but it saves you time, attention, and pain over the lifecycle of your infrastructure code.

• Pipeline by name binding: As mentioned in the first point, the data emitted from DSC is always compressed JSON that maps to the canonical schemas for interoperability and validation. Aliases for the output from DSC aren't just complex to implement, they're going to introduce a host of interoperability complexity and errors.

[StartAutomating]

@michaeltlombardi Thanks for the detailed response.... Let's keep this feedback channel going :-)

In Order....

• DSC is a tool for infrastructure as code first, interactive use second.

So interactive use is a scenario.

• You will read key-value pairs in DSC configuration documents (or the equivalent in higher order tools leveraging DSC) more often than you will write them, over the operational life of any given configuration document or snippet.

All the more reason to support user-friendly names, since it will be far faster to parse what format means than fmt

• DSC is a standalone executable, written in Rust, that returns JSON output, and is interoperable with higher order tools like Machine Configuration, WinGet, Ansible, etc.

Yes, and I think DSC is trying to create an ecosystem here (where other tools could replace DSC itself, or where resources would be used without all of DSC). We're discussing how to make the standard as inclusive as possible to a broad ecosystem.

• Increased clarity: The properties of a DSC Resource are defined by a JSON Schema. The canonical property names are defined by the resource author for their users. If the property names are obscure or difficult to understand, that's a bug in the resource implementation. Adding aliases, especially user-defined aliases, would not make this problem go away - when serializing the data to JSON, the canonical property name has to be used for interoperability.

Sure, obviously we need a primary property name, and that will likely map to as close to implementation as possible.

To do anything else, without support of aliases, is a horrible choice for a developer to make. So if tool X calls it fmt, I'll call it fmt, to make it more likely to match external documentation. And I'll create a bad user experience by doing so, because most users will scratch their heads at fmt. Having the alias "format" be allowed is quite important to creating a good user experience.

• Decreased error routes: In this point you're discussing decreasing the number of errors users make when authoring configuration documents. I don't think aliases address this issue, because instead of referencing the JSON Schema to understand what properties control what component behavior, you need to dereference the alias to the property schema - and even then, you're hoping that the schema is sufficiently implemented and documented.

Again, there would need to be a primary key. Any other forms of fmt should be dereferenced as the input is converted into JSON. If there were no aliases, there is no change. If there were aliases, only the de-aliased form should be passed to the DSC resource.

• Long standing community guidance for infrastructure as code scripts has been not to use aliases for commands or parameters, because explicit definition supercedes convenience when you're authoring infrastructure code. When I worked at a configuration management vendor, I spent a lot of time explaining to people (and having my explanation painfully reinforced in many cases) that ambiguity in your infrastructure code only leads to errors, debugging difficulties, and confusion in the long run. It's arguably more work to be explicit up front, but it saves you time, attention, and pain over the lifecycle of your infrastructure code.

I respect your experience here, please also respect mine.

1. Here I am talking about parameter aliases, which are a much more straightforward value proposition. Parameter Aliases Help Binding First and Foremost (especially with ValueFromPipelineByPropertyName). The feedback you have given addresses command aliases, not parameter aliases ( I updated the title appropriately)
2. The advice is also incorrect when it comes to use of "smart aliases" (functions that operate differently based off of the alias used to call them). Given the thousands of smart aliases that have been created over the years (by myself and others), this advice should probably be generally retired.

Pipeline by name binding: As mentioned in the first point, the data emitted from DSC is always compressed JSON that maps to the canonical schemas for interoperability and validation. Aliases for the output from DSC aren't just complex to implement, they're going to introduce a host of interoperability complexity and errors.

I am primarily talking about input to DSC resource commands here, though you raise an interesting point.

At the risk of creating another discussion / issue, I wonder...

"Are DSC Resource Outputs Decorated"? (do they assign one or more .pstypenames properties on each object)?

Applying a simple pair of typenames to each output would allow them to be extended and could be incredibly useful.

Conclusion

I think this round has clarified we are talking about different aliases. I am asking for parameter aliasing.

I also believe I have made a stronger case why parameter aliasing should exist, and, ideally, should be of a low impact to the design:

• Dereferencing would only occur once, as the resource function creates the JSON.
• The primary parameter name would be the system name, and thus cleanly carry thru to the underlying ecosystem.

I would like to pleasantly remind the team that I am aiming to metaprogram the development of resources, and thus I am likely to be creating hundreds or thousands or resources over the coming months. This is something I can see as a barrier to entry now, and I would like it resolved before I start massive resource development. Given the obscure parameter names of most non-PowerShell ecosystems, it's also something I expect to be a pretty big usability roadblock.

Thus my choice as a developer is:

• Write lots of resources knowing that users will have difficulties with the implementation, and hope that the blowback comes to DSC and not me.
• Wait and hope for alignment.

Please help me make the right choice here, so that the ecosystem may grow and flourish.