Provide tips and tricks for includes

[Gijsreyn]

Summary of the new feature / enhancement

As a user, I don't want to think too much about how the input should be specified whenever using the configurationContent and parameterContent on the Microsoft.DSC/Include resource type.

After experimenting using the new rc.1 version, the only examples available are the ones in the Pester tests. I think most users predominantly will execute dsc.exe through a PowerShell session. Instead of relying on escaping characters, having some tips and tricks available using PowerShell hashtables or using powershell-yaml, will provide benefits for users to see how it should be input correctly.

Here are a few examples of what I mean:

# Example 1 - Using full PowerShell hashtable
$include = [ordered]@{
  "`$schema" = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json"
  resources  = @(
    @{
      name       = "DotNet tool"
      type       = "Microsoft.DSC/Include"
      properties = @{
        configurationContent = [ordered]@{
          "`$schema" = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json"
          parameters = [ordered]@{
            PackageId = @{
              type         = "string"
              defaultValue = "powershell"
            }
          }
        
          resources  = @(
            [ordered]@{
              name       = "Use Dotnet tool package"
              type       = "Microsoft.DSC/PowerShell"
              properties = @{
                resources = @(
                  [ordered]@{
                    name       = "Install package by package ID"
                    type       = "Microsoft.DotNet.Dsc/DotNetToolPackage"
                    properties = @{
                      PackageId = "[parameters('PackageId')]"
                    }
                  }
                )
              }
            }
          )
        }
      }
    }
  )
}

dsc config get --input ($include | ConvertTo-Json -Depth 10 -Compress)
# Fails with ERROR Parser: Parameter 'PackageId' not found in context

# Example 2 - Split hashtable to get the '\"'
$configDocument = [ordered]@{
  "`$schema" = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json"
  parameters = [ordered]@{
    PackageId = @{
      type         = "string"
      defaultValue = "powershell"
    }
  }

  resources  = @(
    [ordered]@{
      name       = "Use Dotnet tool package"
      type       = "Microsoft.DSC/PowerShell"
      properties = @{
        resources = @(
          [ordered]@{
            name       = "Install package by package ID"
            type       = "Microsoft.DotNet.Dsc/DotNetToolPackage"
            properties = @{
              PackageId = "[parameters('PackageId')]"
            }
          }
        )
      }
    }
  )
}
$resourceInput = $configDocument | ConvertTo-Json -Depth 10 -Compress # <-- Convert it to JSON input

$include = [ordered]@{
  "`$schema" = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json"
  resources  = @(
    @{
      name       = "DotNet tool"
      type       = "Microsoft.DSC/Include"
      properties = @{
        configurationContent = $resourceInput
      }
    }
  )
}

dsc config get --input ($include | ConvertTo-Json -Depth 10 -Compress)
# Succeeds

The sample would imply using the example with ConvertTo-Yaml.

Advanced users who are fans of JSON will know that you have to escape the characters. For YAML, it would be the >- multi-string indicator or |.

Proposed technical implementation details (optional)

A tips and tricks article.

[Gijsreyn]

As always, if it's desired to have it in the documentation, I'm always up to write an article on it if I know were you want me to place it.