A DSC composite resource relies on a set of folders and files that have to be in their exact correct places in order to work successfully.

A DSC composite resource can be described as a PowerShell module inside a root PowerShell module. The root PowerShell module is required to declare this as a DSC composite resource to the DSC engine; it itself does not usually contain any code, nor does it actually contain any DSC configuration blocks. Inside the root module is a subfolder called DSCResources. The folder must be named exactly this for the DSC composite resource to be parsed correctly. Inside the DSCResources folder is one or more PowerShell module folders. Each module represents an actual DSC composite resource.

For the most part, all the normal PowerShell module files are present, with the exception of the file that actually contains the DSC configuration blocks. This file must have a schema.psm1 extension instead of just a .psm1 extension.

In the following code block is an example folder structure for a DSC composite resource. In this example, we have two DSC composite resources packaged together:

$env:PSModulePath
 |- <RootModuleName>
 |- <RootModuleName>.psd1 (PowerShell Module Manifest file, Required)
 |- <RootModuleName>.psm1 (PowerShell Module file, Optional)
 |- DSCResources
 |- <DSCCompsiteResource1>
 |- <DSCCompsiteResourceName1>.psd1 (DSC Composite Resource manifest file, Required)
 |- <DSCCompsiteResourceName1>.schema.psm1 (DSC Composite Resource PowerShell module, Required)
 |- <DSCCompsiteResource2>
 |- <DSCCompsiteResourceName2>.psd1 (DSC Composite Resource manifest file, Required)
 |- <DSCCompsiteResourceName2>.schema.psm1 (DSC Composite Resource PowerShell module, Required)

If this still isn't clear to you, then you are not alone. Let's try this again and apply the preceding example to the ExampleSoftware and TheRealSoftwareStuff software we are trying to install:

$env:PSModulePath
 |- <KickingCompanyResources>
 |- KickingCompanyResources.psd1
 |- KickingCompanyResources.psm1
 |- DSCResources
 |- ExampleSoftwareDscResource
 |- ExampleSoftwareDscResource.psd1
 |- ExampleSoftwareDscResource.schema.psm1
 |- RealStuffDscResource
 |- RealStuffDscResource.psd1
 |- RealStuffDscResource.schema.psm1

So, we start out at the root module, KickingCompanyResources. We named our root module after our company, but there really are no official rules here. Microsoft initially recommended that the community prefix their DSC resources and DSC composite resources with a c and that Microsoft prefix their experimental ones with an x. Since this wasn't a requirement in DSC, the actual implementation of these suggested that naming schemes have had spotty adoption. When Microsoft moved their DSC resource kit to GitHub (this is covered later in the book), it highlighted how all DSC resources with an x are prefixed but are released to the PSGallery with the x still there. There is also a ticket explaining that Microsoft will eventually move away from suggesting prefixes (https://github.com/PowerShell/DscResources/issues/27). It is clear that the naming conventions are still being worked out.

Generally speaking, it's prudent to name your root module something sensible that also makes sense in the context of the operations you are performing. Here, we are packaging two resources that operate on software written by the KickingCompany, so it makes sense to be so bold as to name them with the company name.

Inside the root module folder, we see the PowerShell manifest file and the PowerShell module file. The module file can be left blank; it's not required and not used for a DSC composite resource. The manifest file must contain the normal module manifest data to help identify it. This is easily created using the New-ModuleManifest cmdlet, or you can do it by hand:

[PS]> New-ModuleManifest -Path .ExampleSoftwareDscResource.psd1
[PS]> Get-Content .ExampleSoftwareDscResource.psd1
#
# Module manifest for module 'ExampleSoftware'
#
# Generated by: James Pogran
#
# Generated on: 1/1/2015
#
@{
# Script module or binary module file associated with this manifest.
# RootModule = ''

# Version number of this module.
ModuleVersion = '1.0'

# ID used to uniquely identify this module
GUID = 'a80febb6-39d1-4129-88ae-7572561e43c8'

# Author of this module
Author = 'James Pogran'
<#
...
#>
}

Next, we have the DSCResources folder, which contains the two folders, ExampleSoftwareDscResource and RealStuffDscResource. Here is where we start deviating from the normal PowerShell module structure. Each has a normal PowerShell manifest file, in which the most important field is the RootModule entry. However, it has to point to the schema.psm1 file, not just to a file with a .psm1 extension. The schema.psm1 file contains the DSC configuration block and nothing else.

Still not super clear? You're still not alone. It was confusing enough to remember each time I used DSC composite resources that I created a short PowerShell function to encapsulate the above steps into a simple command-line execution. The function itself is a little too long to include in this chapter, but it can be found in https://powershell.org/ GitHub repo here: https://github.com/PowerShellOrg/DSC/blob/master/Tooling/DscDevelopment/New-DscCompositeResource.ps1.