Creating Professional DSC Resources -Part 1
Writing desired state configuration (DSC) resources can be a little bit tricky at first if you’ve not come from a programming background. But once you’ve written one or two, you’ll quickly find yourself churning them out like Disney releases Star Wars branded rubbish. That is how it went for me.
However, I quickly found that there is a big difference between writing a simple resource for your own consumption and releasing a community DSC resource that may be used and abused by tens, hundreds or even thousands of people. After I decided to release my first resource (this one) to the public, I quickly found that it really wasn’t measuring up to what was being released by Microsoft and other folk in the community. So I spent about 6 months releasing and re-releasing my resources as I got to know the best practices.
So that gets us to the purpose of this post: to try and document the lessons I learned over the last year creating my own DSC resources and contributing to the Microsoft Community DSC resources. Hopefully by doing this it might save someone else a bit of time and avoid the joys or re-writing your resources.
Tip: The best practices for creating DSC resources change quite often as better ways of doing things are discovered it is useful to keep and eye on some of the more active DSC resources (like this one) in the Microsoft Community DSC resources. Even since I started contributing the processes and best practices have changed quite a lot.
If have no idea what Desired State Configuration (DSC) is, then this is a good place to start.
If you’ve not created a custom DSC resource before, then you should first get to know the basic process before reading this guide. There are many really great tutorials on creating DSC resources.
If you have written a resource or two or are familiar with the process, but you want to know how to go about releasing your custom DSC resource to the community then this post might interest you. So read on!
Before even getting started writing a custom DSC Resource it is a good idea to see if it already exists. It might not be included in the standard DS resources or in the Microsoft Community DSC Resources, but someone else may have already created one that will work for you. So why re-invent the wheel?
The best places to look for DSC resources is to search on PowerShell Gallery (you’ll find the Microsoft Community DSC Resources here as well). If you can’t find anything that looks like it’ll work for you, then you could also do a search on GitHub.
If you have WMF 5.0 installed (or have installed the PowerShell Package Modules installed) then you can search the PowerShell Gallery for DSC resources using PowerShell cmdlets:
Note: this will only find modules tagged with DSC. Some resources may not be tagged with this so they will not appear in this search. Therefore you may need to tweak the search.
If you find a resource you want to examine, you can install it using:
Or if you’re not sure you want to trust it you can use the save-module cmdlet to save a copy to a folder so you can open and examine the resource code:
If you find the DSC resource module else where you’ll need to download and install it manually - the same way install any other module.
If you find something that is close to what you need, but is missing some parameter or functionality, rather than starting a whole new resource you could ask the maintainer if they would be able to add the feature for you. Or even better, you could ask the maintainer if they’d object to you making the change and submitting it back to them via a Pull Request. Even if they’re not interested including your change, at least you can modify their resource adding the functionality you need - which will save you a lot of time**.** But in my experience, most maintainers are grateful for the assistance and welcome new features (as long as they go along with the resources overall design).
In fact, I’ve learned more from helping out on the community resources than from writing my own. If you have some spare time and want to help the community out, I’d strongly recommend helping out on the Microsoft Community DSC Resources. Just head over there, take a look at a resource you’re interested in then have a look at the issues for the resource and you’re bound to find a request or two for additional features. If you don’t find a request for a new feature but you see that one is missing that you’d like to see implemented, raise an issue yourself and offer to create it.
At the time I wrote this post there were some big holes in the functionality of most of the existing DSC community resources. The xDNSServer resource is a prime example.
Tip: one of the best ways to learn how to write professional quality resources is to look at some of the Microsoft Community DSC Resources. I’d strongly recommend the xNetworking resource (no, not because I contributed to it a bit) because it is very active and when best practices are updated this tends to be one of the first resources to get updated.
So you’ve decided you’re going to write a new DSC resource (or modify an existing one). First thing you’ll need to be a little bit familiar with is Source Control. This used to be mainly the realm of developers, but it should now be a key tool in the Operations toolbox. I’m going to assume that you are a little bit familiar with Git and GitHub for this series.
If you’re not familiar with using Git and GitHub, this is the article you should read. It is written by the DSC Community and covers the basics, all from a DSC perspective. Even if you are familiar with Git and GitHub but haven’t used it for DSC resources, this document is worth a read.
Here is a summary of the Source Control things you should already know/have done:
- You should have a GitHub account (it’s free). This is the most likely place you’ll be storing your DSC Resources, and you’ll find the other community ones here too.
- You should have downloaded and installed the Git client, GitHub Desktop client or be using a tool like Microsoft Code that has a Git client built in.
- Ideally you should be familiar with what Forks, Branches and a Pull Requests are. There are some pretty amazing guides out there that will tell you everything you need to know in about 10 minutes.
- Decided if you’re going to create a new resource or fork someone elses and modify it.
Something I didn’t find out till many months after I started to contribute was that there is a Gitter chat channel where you can chat directly with some of the many of the people who contribute to the Microsoft Community DSC Resources. It is a great place to lurk and just see what is going on. If you want to contribute to a resource but you’re not sure what, if you ask, I’m sure you’ll receive lots of suggestions as to what needs some work. You’ll learn a lot just watching the discussion and if you need some help it’s a great place to ask.
Tip: If you have a GitHub account, you can sign in to Gitter with it.
So, that is pretty the introduction over with. In the next article in this series I’m going to cover what you should do when you’re going to start a DSC Resource from scratch - one that you intend on releasing to the community. The final part of the series I’ll cover adding features to an existing Microsoft Community DSC Resource.
Hopefully this is of interest to a few out there and it doesn’t scare off any potential DSC contributors. It really is a great feeling to contribute back to the community.
Further parts in this series: