Creating Professional DSC Resources - Part 3
The purpose of this series of articles is to try and document a few of the lessons I learned while releasing new DSC resources as well as contributing to the existing Microsoft Community DSC resources. These articles are not intended to tell you how to write DSC resources from a programming perspective, but to give you some ideas on what might be expected of a DSC resource you’re releasing to the public. For example, unit and integration tests (don’t worry if you aren’t familiar with those terms).
These articles are also not intended to tell you what you must do to release your resource, but more document what will help your resource be easier to use and extend by other people. Some of these these things are obvious for people who have come from the development community, but may be quite new to operations people.
If you missed any previous articles you can find them here:
Everyone has there own preferences of how they like their code to look. Just take a look at all the PowerShell repositories on GitHub and you’d see a lot of different coding styles.
When I refer to coding style, this covers a many different things, for example:
- Variable name format
- Tab format (spaces or tabs?)
- Function name format
- Maximum line length
- Comments
- Curly braces allowed at the end of a line
- Allow more than one blank line in a row
If you’re writing code that only you will look at and maintain, it doesn’t much matter what your coding style is - as long as you can understand it 6 months later. However, if you would like other people to use and possibly contribute and maintain your code or if you are contributing to community project, you’ll want to adopt a standard coding style.
The best reason for adopting a standard coding style is to ensure consistency in your code - especially across DSC resources within the same module. This makes it much easier for people to become familiar with your coding style and therefore easier for them to read and understand.
If you don’t have a particular coding style you have adopted, Microsoft has released a simple style guidelines document for DSC Resources that you can adopt quite easily.
Tip: Using the Microsoft style guidelines document is a requirement for contributing code to the Microsoft Community DSC Resources. So if you’re planning on contributing code or even entire resource modules to this project, I’d recommend you adopt the Microsoft style guidelines.
Adding support for language localization to your DSC Resources is trivial, but it is often over looked. Supporting data localization is much easier to add when you are creating your DSC Resource rather than adding it later on. This doesn’t mean you have to provide the language files of course, just provide support so that someone else could contribute them should they want to.
To ensure language support, create a new file in the same folder as your DSC Resource with the same name as the DSC Resource but with a psd1 extension. In that file create a Data section named LocalizedData containing the messages for your default culture. For example:
Each line contains a localized message - in this case for the culture en-us. You could of course use a different default culture if you wanted to.
At the beginning of your DSC Resource you would the following command to ensure the appropriate localization strings are imported:
Alternately, if you want to support Message Localization but don’t want to have to supply your default messages in a separate file, you can place the LocalizedData section for your default culture at the top of your DSC Resource and exclude the Import-LocalizedData command.
Once you’ve got the messages in, using them is extremely easy:
You can of course consume the messages anyway you like, but all of your localized messages are just properties of the LocalizedData object.
You put LocalizedData for other languages in separate PowerShell files in sub-folders named after the culture the file contains. For example, you might create a sub-folder called en-uk and place a file called BMD_cMyNewResource**.psd1** containing the en-uk messages.
Another element of any easy to use DSC Resource are example DSC Configuration files. These can usually be found in the Examples folder in the root of the DSC Module:
There should usually be a number of different DSC Configuration files in this folder, showing common scenarios for using your DSC Resources:
The file name of any example files should be prefixed with Sample or Example so that they can be easily identified and differentiated from types of DSC Module files. The summary of the purpose of the configuration should also be included in the file name. This is fairly obvious I realize, but I have seen public DSC Resources named Example_1, Example_2, Example_3 etc - which reduces usability of the examples.
Each example should contain a DSC Configuration in a form that it could be used without any modification to actually test the resource. This might include installing prerequisite Windows Features or starting services etc. This allows a potential user to test drive the resource without investing a whole lot of work trying to figure out how to use it.
For example:
The above DSC Resource example will ensure the MSiSCSI service is running before configuring an iSCSI Initiator.
Tip: Make the name of the configuration the same as the sample configuration file (without the extension of course).
It is also a great idea to copy the content of any example DSC Configuration files into the Examples section of the Readme.md of your DSC Resource Module along with a brief description of what the configuration will produce. You’ll find that all Microsoft Community DSC Resources do this.
I intended on covering creating unit and integration tests in this article, but as that is by far the most involved part of creating a community DSC resource I’ve decided I’ll dedicate an entire part to each. So, rest assured the next ones will contain this very important component of any public DSC Resource. Thank you for reading this far and I hope you’re finding it useful.
Further parts in this series: