Authoring DSCv3 config docs with PowerShell

[SteveL-MSFT]

There's at least 3 aspects to this:

1. the config doc itself
2. resources w/ intellisense
3. expressions

It might be easiest to not have cmdlets, but leverage .NET types created by a PS module because PS7 supports intellisense for type properties:

$config = [Microsoft.DSC.Configuration]@{
  parameters = {
    params(
      [stirng]$myParam = 'hello'
    )
  }
  directives = [Micorosft.DSC.Directives]@{
    securityContext = 'Elevated'
  }
  resources = @(
    [Microsoft.DSC.Resource]@{
      name = 'install PS7'
      properties = ...
  }
}

An open question, is there a way for dependsOn to have intellisense to show all the defined resources? Since the config type hasn't been constructed yet, there's a chicken-and-egg problem.

Ideally, we could use AST parsing to convert PS params() into parameters, but need to explore if the mapping works completely.

For resource properties, I think it would be easier if this module runs dsc resource list and dsc resource list --adapter '*' to get all of them and generate .NET types under a DSC namespace such as DSC.<typeNamespace>.<typeName>. There IS a risk of name collision here if a DSC resource type has a <typeName> that is also part of a <typeNamespace>, but I'd expect that to be rare and something we wouldn't recommend. With this model, PS7 already has intellisense for properties using type conversion with a hashtable:

$config = [Microsoft.DSC.Configuration]@{
  resources = @(
    [Microsoft.DSC.Resource]@{
      name = 'SSHD service'
      properties = [DSC.Microsoft.Windows.Service]@{
        name = 'sshd'
        status = 'Running'
      }
  }
}

Expressions ideally would be a type conversion from a PS scriptblock into an expression string:

$config = [Microsoft.DSC.Configuration]@{
  resources = @(
    [Microsoft.DSC.Resource]@{
      name = 'SSHD service'
      properties = [DSC.Microsoft.DSC.Debug.Echo]@{
        output = [Microsoft.DSC.Expression]{
          (Invoke-DscFunction -Name systemRoot) + '\Windows\System32'
        }
      }
  }
}

This should result in the expression: [concat(systemRoot(), '\Windows\System32')]. During type conversion of the script block, the Microsoft.DSC.Expression type would validate that any used PS syntax is supported and can be transpiled to a DSC expression.

[michaeltlombardi]

I think it's important to note that even if we eventually decide to present a set of low-level commands for constructing and operating on DSC configuration documents we'll still need the data types defined. I think an initial release that defines the data types is perfectly valid and would already provide a lot of value.

I think there's still value in providing commands to operate on these types, like:

$config = [Microsoft.DSC.Configuration]@{
  resources = @(
    [Microsoft.DSC.Resource]@{
      name = 'SSHD service'
      properties = [DSC.Microsoft.Windows.Service]@{
        name = 'sshd'
        status = 'Running'
      }
  }
}

foreach ($resource in $resources) {
  if ($resource.tags -notcontains 'bastion') { continue }
  
  $config | Add-DscResourceInstance -instance $resource.Instance)
}

$config | Export-DscConfigurationDocument -Path ./example.dsc.config.yaml

But since defining the types is a prerequisite for any useful commands, I think focusing on those types and their ergonomics makes a lot of sense.

I also think that it's okay if the eventual module is PowerShell 7+ only - authoring a configuration document is a very different concern from supporting Windows PowerShell for a resource.

[SteveL-MSFT]

I think PS7 only is a given :)

[adityapatwardhan]

How about a DSL like Pester?

1. DSC ships with a generated metadata for "built-in" resources, which get converted to PowerShell functions (pester like It, Describe etc.)
2. The module ships with few keywords like Microsoft.DSC.Configuration, some cmdlets like Import-DSCResource which performs discovery and creates types (PowerShell functions) for the resources from the schema. Once the resource metadata is loaded, intelli-sense should work.
3. If we don't / can't load resources, in future the schemas of resources could be available at a well know location, which the module can load from (ACR / CDN etc.)
4. We can use standard PowerShell constructs like loops, arrays, hash sets etc.
5. Additional advantage of having a module is that we can load all dependencies in an ALC.

Sample authoring experience

Import-DSCResource 

if ($IsWindows) {
  $serviceState = @( 
      @{ Name = 'sshd'; Status = 'Running' }
      @{ Name = 'winrm'; Status = 'Running' }
  )
  
  $serviceConfig = $serviceState | ForEach-Object { 
        Microsoft.Windows.Service {
            Name = $_.Name
            Status = $_.State
       } 
  }
}

## Other option where the type expands the input

$serviceConfig = $serviceState | Microsoft.Windows.Service  ## This will bind by PropertyName 

$psResource = PSResource { 
   Name = 'Pester'
   Version = '5.1.0' 
}

$resources = @($serviceConfig, $psResource)

Microsoft.DSC.Configuration -Resources $resources | Export-DSCConfigurationDocument -Path ./deploy.config.yml

## Or by pipeline binding 

$serviceConfig, $psresource | Microsoft.DSC.Configuration | Export-DSCConfigurationDocument -Path ./deploy.config.yml

[SteveL-MSFT]

I don't think it's one or the other. In addition to generating .NET types, the module could also generate Functions for resources like in your example. The functions just need to emit the actual .NET type and the user could mix-match both in their script. However, with Functions you would get a cmdlet experience where the properties become parameters.