{"id":1991,"date":"2013-11-05T11:28:23","date_gmt":"2013-11-05T11:28:23","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/powershell\/2013\/11\/05\/understanding-configuration-keyword-in-desired-state-configuration\/"},"modified":"2019-02-18T13:05:29","modified_gmt":"2019-02-18T20:05:29","slug":"understanding-configuration-keyword-in-desired-state-configuration","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/understanding-configuration-keyword-in-desired-state-configuration\/","title":{"rendered":"Understanding CONFIGURATION keyword in Desired State Configuration"},"content":{"rendered":"
\n

Desired State Configuration<\/a> is a new management platform in Windows Powershell that enables devOps scenarios on Windows. It enables system administrators and devOps to configure a system declaratively, enforce the configuration and reuse configuration. One core aspect of it is the language extension for Configuration keyword in Powershell.<\/p>\n

You can express configurations of your machine using configuration keyword as shown below which is taken from the MSDN documentation<\/a><\/p>\n

Configuration<\/span> MyWebConfig<\/span>
{
   # A Configuration block can have zero or more Node blocks<\/span>
   Node “Server001”<\/span>
   {
      # Next, specify one or more resource blocks<\/span><\/p>\n

      # WindowsFeature is one of the built-in resources you can use in a Node block<\/span>
      # This example ensures the Web Server (IIS) role is installed<\/span>
      WindowsFeature MyRoleExample<\/span>
      {
   # To uninstall the role, set Ensure to “Absent”<\/span>
          Ensure =<\/span> “Present”<\/span>
          Name   =<\/span> “Web-Server”<\/span> 
      }<\/p>\n

      # File is a built-in resource you can use to manage files and directories<\/span>
      # This example ensures files from the source directory are present<\/span>
      File MyFileExample<\/span>
      {
   # You can also set Ensure to “Absent”<\/span>
         Ensure =<\/span> “Present”<\/span> 
   # Default is “File”<\/span>
         Type =<\/span> “Directory”<\/span>
         Recurse =<\/span> $true<\/span>
         SourcePath =<\/span> $WebsiteFilePath<\/span>
         DestinationPath =<\/span> “C:\\inetpub\\wwwroot”<\/span>
  #This ensures that MyRoleExample completes successfully before<\/span>
         DependsOn =<\/span> “[WindowsFeature]MyRoleExample”<\/span>       
}
   }
}
 <\/span><\/p>\n

From the sample you can see that we added one keyword, configuration,<\/strong> that can be used to declaratively define configurations and there is one dynamic keyword Node you can use inside configuration and a set of resources which are also act like keywords. You can find the list of resources and their properties by using Get-DscResource cmdlet. Here is the output I have when using it on a Windows Server 2012 R2 machine.<\/p>\n

ImplementedAs   Name                      Module                         Proper
                                                                         ties 
————-   —-                      ——                         ——
Binary          File                                                     {De…
PowerShell      Archive                   PSDesiredStateConfiguration    {De…
PowerShell      Environment               PSDesiredStateConfiguration    {Na…
PowerShell      Group                     PSDesiredStateConfiguration    {Gr…
Binary          Log                       PSDesiredStateConfiguration    {Me…
PowerShell      Package                   PSDesiredStateConfiguration    {Na…
PowerShell      Registry                  PSDesiredStateConfiguration    {Ke…
PowerShell      Script                    PSDesiredStateConfiguration    {Ge…
PowerShell      Service                   PSDesiredStateConfiguration    {Na…
PowerShell      User                      PSDesiredStateConfiguration    {Us…
PowerShell      WindowsFeature            PSDesiredStateConfiguration    {Na…
PowerShell      WindowsProcess            PSDesiredStateConfiguration    {Ar…<\/p>\n

<\/span><\/p>\n

Configuration is a keyword with simple name, which means it can have constant string or variables as its name. It is the only new keyword added by default for desired state configuration. The syntax of it looks like function which means it can be followed by a scriptblock with some restriction. You can only have parameter block and default process block. Overall configuration definition syntax looks like function definition. Indeed it creates a command with the name you just specified and you can invoke it with some additional parameters such as output directory and configuration data. However since it has different semantics with functions we created a new command type called Configuration. If you save above sample as sample.psm1 and invoke import-module .\\sample.psm1, you will see new configuration command listed in the output of get-command<\/p>\n

PS D:\\dsctest> <\/span>Get-Command<\/span>-CommandType<\/span>Configuration
<\/span>CommandType     Name                                               ModuleName                                                                                                                                                                                   
———–     —-                                               ———-                                                                                                                                                                                    Configuration   MyWebConfig                                        sample                                                                                                                                                                                       
PS D:\\dsctest> Get-Help MyWebConfig
NAME
    MyWebConfig
   
SYNTAX
    MyWebConfig [[-InstanceName] <string>] [[-OutputPath] <string>]
    [[-ConfigurationData] <hashtable>] 
    <\/p>\n

ALIASES
    None
   
REMARKS
    None
<\/span> <\/p>\n

After that, you can invoke MyWebConfig as other command by typing MyWebConfig. This command will generate a MOF file that can be send to the targeting machine to configure it. MOF is a Distributed management task force standard for Common Information Model(CIM)<\/a><\/p>\n

PS D:\\dsctest> MyWebConfig<\/p>\n

    Directory: D:\\dsctest\\MyWebConfig<\/p>\n

Mode                LastWriteTime     Length Name                                                                                                                                                                                                                
—-                ————-     —— —-                                                                                                                                                                                                                
-a—        10\/14\/2013   3:27 PM       2020 Server001.mof                                                                                                                                                                                                       <\/p>\n

 <\/p>\n

<\/span><\/p>\n

Now we know this new Configuration keyword let’s dig into the configuration body to know what we can specify inside. Powershell will add two dynamic keywords, Node and Import-DscResource, by default once inside the configuration block. Node conceptually represents a machine you want to configure. You can specify a set of resources inside each Node block. Each resource specification starts with the resource name and contains a hashtable body that represent concrete configuration settings as shown in the example at the very beginning. You can find more information about DSC resources from technet site<\/a>.
We can discover the set of resources that are available on the machine using Get-DscResource cmdlet. These resources are the resources you can use inside node block. However there is a little caveat here user needs to be aware. PowerShell will automatically load the resource as keyword If the resource’s parentPath is under system path such as $pshome\\modules or $env:systemRoot\\system32\\configuration. If it is under $env:PSModulePath other than system path,  we will need to use Import-DscResource to load the resource so powershell parser can understand it. We can see the detailed information of a resource using below commands.<\/p>\n

PS D:\\dsctest> Get-DscResource -name file | fl<\/p>\n

ResourceType  : MSFT_FileDirectoryConfiguration
Name          : File
FriendlyName  : File
Module        :
Path          :
ParentPath    : C:\\WINDOWS\\system32\\Configuration\\Schema\\MSFT_FileDirectoryConf
                iguration
ImplementedAs : Binary
CompanyName   :
Properties    : {DestinationPath, Attributes, Checksum, Contents…}<\/p>\n

<\/span> <\/p>\n

All these resources are loaded as dynamic keywords which we will not have enough time to discuss this time. Hopefully we can get to them in the next post.<\/p>\n

In addition to resources provided by the Desired State Configuration, user can build their own resources and there is a good TechNet documentation<\/a> for it. That document mainly talked about powershell module based resources. User can actually add a resource using configuration itself as well. Here is an example:<\/p>\n

configuration<\/span>  scriptdsc<\/span>
{
    param<\/span> ($one<\/span>,<\/span> $two<\/span>)<\/p>\n

    Log scriptDscLogResource<\/span>
    {
        Message =<\/span> “This is the message from the embedded log resource: one=<\/span>$one<\/span> two=<\/span>$two<\/span> three=<\/span>$three<\/span>“<\/span>
    }<\/p>\n

      File MyFileExample<\/span>
      {
         Ensure =<\/span> “Present”<\/span> 
         Type =<\/span> “Directory“<\/span> # Default is “File”<\/span>
         Recurse =<\/span> $true<\/span>
         SourcePath =<\/span> $one<\/span> # This is a path that has web files<\/span>
         DestinationPath =<\/span> $two<\/span> # The path where we want to ensure the web files are present<\/span>
      }
}<\/p>\n

Export-ModuleMember<\/span> -Function<\/span> scriptdsc<\/span>
 
<\/span>This file has to be named resourceName.Schema.psm1 and have a companion resourceName.psd1 file. After that, you can deploy it as any other Powershell resources. This capability enable the user to compose configurations and leverage existing configurations created by others like below.<\/p>\n

Configuration<\/span> MyConfig<\/span>
{
   Node “Server001”<\/span>
   {
      scriptdsc MyExample<\/span>
      {
          One =<\/span> “\\\\share\\file.txt”<\/span>
          Two =<\/span> “d:\\file.txt”<\/span> 
      }
   }
}
<\/span>
In this post we gave a quick introduction to the configuration keyword in powershell. I will talk more about customizing configuration using configurationData, specify embedded objects in configuration and $using variables in the future blog. We will also dig into the implementation of dynamic keywords if that is interesting to more people.<\/p>\n

 <\/p>\n

Joe Zhou
SDE<\/p>\n

 <\/p>\n<\/div>\n","protected":false},"excerpt":{"rendered":"

Desired State Configuration is a new management platform in Windows Powershell that enables devOps scenarios on Windows. It enables system administrators and devOps to configure a system declaratively, enforce the configuration and reuse configuration. One core aspect of it is the language extension for Configuration keyword in Powershell. You can express configurations of your machine […]<\/p>\n","protected":false},"author":600,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[142,150,248,251,345,348],"class_list":["post-1991","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-desired-state-configuration","tag-dsc","tag-powershell","tag-powershell-4-0","tag-windows-powershell-4-0","tag-windows-powershell-desired-state-configuration"],"acf":[],"blog_post_summary":"

Desired State Configuration is a new management platform in Windows Powershell that enables devOps scenarios on Windows. It enables system administrators and devOps to configure a system declaratively, enforce the configuration and reuse configuration. One core aspect of it is the language extension for Configuration keyword in Powershell. You can express configurations of your machine […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/1991","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/600"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=1991"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/1991\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=1991"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=1991"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=1991"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}