Rationale for Resource Designer Script

[juvtib]

Please update the Best practice: Resource folder contains resource designer script for generating schema section to explain why the resource designer script would be useful.

For example, the very next section begins, "If your resource is performing 'dangerous' operations, it's a good practice to implement -WhatIf functionality," which makes sense to me.

When I later read Using the Resource Designer tool, it occurred to me that the resource designer script might be useful when updating the resource. But, I can't be sure what experience the author had in mind.

If anything, the schema appears to be the easiest part of the resource to write. So, I'm not sure why this section would rely on a particular tool or call out the MOF as particularly difficult when the rest of the document reads like a specification.

It might also be worth mentioning that there are side effects. My understanding is that "The New-xDscResource cmdlet creates the MOF schema, a skeleton resource script, the required directory structure for your new resource, and a manifest for the module that exposes the new resource."

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 145a9d64-61a6-b07a-658c-b7ccc3bc9f5a
• Version Independent ID: 151f1dfa-4098-9c02-b092-5ddd0cf1ef88
• Content: Resource authoring checklist - PowerShell
• Content Source: reference/docs-conceptual/dsc/resources/resourceAuthoringChecklist.md
• Product: powershell
• Technology: powershell-conceptual
• GitHub Login: @joeyaiello
• Microsoft Alias: jaiello

[sdwheeler]

@gaelcolas Can you comment on this? Is the generation script really a best practice?

[gaelcolas]

I would not call that a best practice, and is not used much by maintainers in DSC Community.
It's a useful tool for those not used to write schemas, because MOF has its own rules and no Intellisense or syntax validation.
Also MOF can be more complex than this example.
I know we have some work to do to make better "best practices" and guidelines over at DSC community, but we need to update our tooling first.

Class based DSC Resource should be a best practice (because the metadata is in the PowerShell code with the class definition), but we can't make it our guidelines until our tooling supports it (PS Script Analyzer Rules and other checks).
We've started the exploration to find what works best with JeaDsc, but we're still discussing the details.

In your case, I would remove the "Best practice: Resource folder contains resource designer script for generating schema" as the page on "Using the Resource Designer tool" should be enough.

[sdwheeler]

Thanks @gaelcolas. That's the feedback we needed.

Feel free to submit updates to the DSC docs here. And link to docs on dsccommunity.org where appropriate.