I got the following request from a customer.

Hello,

I am attempting to use the built-in DSC Group Resource but I am finding that the documentation does not fully explain how to use the resource, and needs to be updated.

I am referring to the following page: https://msdn.microsoft.com/en-us/powershell/dsc/groupresource

https://github.com/PowerShell/PowerShell-Docs/blob/master/dsc/groupResource.md

I would like to use the Group resource to define the desired list of members for the Administrators group on my server. Unfortunately the documentation provides no syntax on how to define the values for Members, MembersToExclude or MembersToInclude. It also took me a few minutes to understand the difference between Members and MembersToInclude, so I feel more detail could be added here on why you would use one over the other. The documentation needs to show how to define a domain user, or a domain group, or a local user, or a local group and should show the proper syntax to use when defining multiple users and/or groups, as this would be a typical example.

I have brought up instances in the past where DSC documentation could be improved, and some feedback that I got from the content developers was agreement that it would make a lot of sense to ensure that example sections show syntax for how to use all of the available properties for a resource, but it doesn’t seem like much has changed yet on that front. In the case of the Group Resource, the example is not really helpful as it shows how to use the resource to ensure that a group is absent, which is not really the best first example to be showing the power of this resource to our customers.

If I can help in any way to expand this documentation out further, please let me know as I would be happy to help! :)

Thank you,

Ralph Kyttle
Microsoft ...

https://msdn.microsoft.com/en-us/powershell/dsc/metaconfig - this a top level item with content, that also has content underneath it. if you click Configuring the Local Configuration Manager (LCM) in the TOC, you will go to that page

in contrast, if you try clicking The DSC pull model in the TOC, it will only expand the topic.

Other TOC items that are clickable without content:
DSC on Linux
DSC MOF Reference
More Resources

semi-related to #21

Example self-sign certificate generation that works:

    $cert = New-SelfSignedCertificate -Type DocumentEncryptionCert -DnsName 'DscEncryptionCert' -Provider "Microsoft RSA SChannel Cryptographic Provider"

does not work:

    $cert = New-SelfSignedCertificate -Type DocumentEncryptionCert -DnsName 'DscEncryptionCert' 

Debugging DSC resources topic on MSDN ( https://msdn.microsoft.com/en-us/powershell/dsc/debugresource ) should also mention how to disable debugging (by running Disable-DSCDebug cmdlet). Once in the debugging mode, any subsequent Start-DSCConfiguration requests will break into the debugger. LCM breaks into debugger after machine reboot as well. So this is important note to capture in this topic.

At the moment there is no recommended design pattern for authoring DSC Resources where only a single instance can be used on a node. A method has been documented (here)[http://blogs.msdn.com/b/powershell/archive/2015/06/23/want-to-write-a-dsc-resource-where-only-a-single-instance-can-be-configured.aspx]

Could I suggest a new document is created /dsc/AuthoringResourceSingleInstance.md that contains the information @TravisEz13 provided in his blog article?

https://msdn.microsoft.com/en-us/powershell/dsc/pullclientconfigid4

The configuration suggests:
RefreshFrequencyMins = 15;

But using that with the latest cmdlets and resources gives you an out of range error. Minimum is 30.

Right now, putting a code snippet inside of a numbered list breaks the numbering. Potential options include:

• Scope listed instructions to end with code snippets (i.e. don't do that)
• Use HTML tags?
• Hardcode something like "Step 1" in the front of items.

Currently occurring in (at least) pullServer.md.

Hi,
I was going through the documentation on this page:
https://github.com/PowerShell/PowerShell-Docs/blob/live/dsc/secureMOF.md

I found out that the very first script to generate the certificate does not work unless you use windows 10 or server 2016.

According to this page:
https://technet.microsoft.com/en-us/library/hh848633(v=wps.640).aspx
The -Type parameter is not valid when using the command in WIN2012R2.
I also had to specify the -CertStoreLocation parameter to make the command work.
This is what I have so far:

function CreateDscCertificate
{
    param(
        $pwd,
        $folder
    )

    if(!(Test-Path $folder))
    {
        New-Item -Path $folder -ItemType Directory
    }

    # note: These steps need to be performed in an Administrator PowerShell session
    $cert = New-SelfSignedCertificate -DnsName 'DscEncryptionCert' -CertStoreLocation cert:\LocalMachine\My

    # export the private key certificate
    $securePwd = ConvertTo-SecureString -String $pwd -Force -AsPlainText
    Export-PfxCertificate -Cert $cert -FilePath "$folder\DscPrivateKey.pfx" -Password $securePwd -Force

    # remove the private key certificate from the node but keep the public key certificate
    Export-Certificate -Cert $cert -FilePath "$folder\DscPublicKey.cer" -Force
    Remove-Item "$folder\DscPrivateKey.pfx" -Force

    Import-Certificate -FilePath "$folder\DscPublicKey.cer" -CertStoreLocation Cert:\LocalMachine\My
}

I wonder if the certificate will be valid without specifing the -type parameter...

document: https://github.com/PowerShell/PowerShell-Docs/blob/live/dsc/lnxGettingStarted.md

at the bottom of the page it says a couple of log files are in:

/opt/omi/var/log/

but /opt/omi/var doesn't exist on a Ubuntu system with the extension installed.

We've documented this new WMF 5.0 behavior in the release notes but not yet in the official DSC documentation.

Maybe the latter becomes "securing a MOF in PowerShell 4.0" and we add another article to describe the 5.0 behavior?

This isn't supported and metaConfig.md is totally broken at this point because of it.

Hi Team,
Archive DSC resource seems to be very slow and impact is huge when you are deflating lots of files. Example- I was using it to deflate sitecore zip file which has around 10.5k files (that's not good either but that's a third party) and it took around 3-4 hours to unpack it.
Is there a way to speed this up? I can imagine this resource is doing a lot more than just unzipping hence more time.

This topic includes paragraphs regarding PSHostProcess at the top that appear to have been copied from another article template.

Right now, guidance in pullServer.md is to manually download xPSDesiredStateConfiguration. This should be rewritten to suggest PackageManagement for 3.0/4.0.

It also should not give the impression that the zip can be downloaded from the Gallery.

The conformance endpoint documentation doesn't talk about the reporting database, except to mention that it exists, and the web service reads / writes data to it.

• Where the database runs
• What alternative database services are supported
• What the database schema looks like
• How to connect to the database directly and query it

#40

Cheers,
Trevor Sullivan
Microsoft MVP: PowerShell

The instructions for creating a self signed certificate for the pull server do not work. The example references a -Subject parameter which does not exist.

feedback_fileinfo.md mentions Production Preview. Also, version numbers in output should be updated to WMF 5.0 RTM.

Code samples do not display correctly on the production web site.

"The following example uses File Explorer to copy three files:", but there is no example.

https://github.com/PowerShell/PowerShell-Docs/blob/master/dsc/pullServer.md

Conversely, the presents of a ConfigurationID means that the V1 version of the pull server protocol is used and there is no registration processing.

Should read:

Conversely, the presence of a ConfigurationID means that the V1 version of the pull server protocol is used and there is no registration processing.

The folder structure currently employed is unorganized and will not scale to another order of magnitude of topics. We should look into low-hanging fruit for abstracting some of the topics into subfolders (e.g. built-in resources should go in a single folder).

See new content pull request linked under configData.md with a new file configDataCredentials.md.

1. as reported by MVPs, DSC extension should not be a relevant example for pull mode.
2. I need to tweak the graphics a bit to be more inline with what we use for presentations.

Please remove ‘s’ from module folder name ‘MyDscResources’
Resource will not be discovered by DSC if user follows exactly what is written in the document.

$env: psmodulepath (folder)
|- MyDscResources (folder)
|- MyDscResource.psm1
MyDscResource.psd1

Right now, pullClientConfigID.md and pullClientConfigID4.md are the same content. The former should be rewritten to target 5.0

In a title, attempting to use the name of the C# programming language renders as only "C"...parser appears to treat the '#' as the end of a heading.

On this page:
https://github.com/PowerShell/PowerShell-Docs/blob/staging/dsc/reportServer.md

This code doesn't work as expected:
$reportsByStartTime = $reports | Sort-Object -Property StartTime -Descending

The property StartTime is of type string, not a datetime, so the sorting will not work as expected.

There's currently some inconsistencies in the way Markdown is authored in this repository, but we should coalesce on a single style guide, including guidance for:

• indentation
• • vs _
• extra carriage returns (e.g. underneath headers, when a line gets too long, etc.)
• when to use bold, italic, code highlighting, etc.

The command

New-SelfSignedCertificate -CertStoreLocation 'CERT:\LocalMachine\MY' -Subject 'CN=PSDSCPullServerCert'.

only runs on Windows 10 and Windows Server 2016!

On older OS there is no parameter "Subject"!

Error message:
New-SelfSignedCertificate : A parameter cannot be found that matches parameter name 'Subject'.

https://msdn.microsoft.com/en-us/powershell/dsc/pullServer

You use this:
configuration Sample_xDscWebService

But in the next section you tell the user to call this:
Sample_xDSCService

Might suggest adding in the option to use "AllowUnencryptedTraffic". Although not recommended, it is a valid configuration.

You also don't specify to run a Start-DscConfiguration command after creating the MOF. Someone creating a pull server for the first time might get confused with the lack of that step.

Current documentation around v5 pull server uses the example of a report server separate from the pull server. Given the changes from v4 it would be beneficial to have an example of how to configure a pull server to also be the report server and resource server.

Also, if the pull server URI is the same for the report server, then I suppose there should be something documented for the reporting code. i.e. if you're using a single server you use http://pullserver:8080/PSDSCPullServer.svc, if you're using 2 servers use http://reportserver:8080/PSDSCReportServer.svc.

Where

CodeSample

@(1,2,3).Where{$_ -gt 1}

Output

2
3

ForEach

Code Sample

@(1,2,3).Foreach{$_ + 1}

output

2
3
4

I'm running WMF 5.0 Production Preview.
If i use

        LocalConfigurationManager 
        { 
            DebugMode = $true
        } 

You get unsupported value error message:

PSDesiredStateConfiguration\LocalConfigurationManager : 
At least one of the values 'True' is not supported or valid for property 'DebugMode' on class 'LocalConfigurationManager'. 
Please specify only supported values:
None, ForceModuleImport, All.

DebugMode is no longer Bool value, it is string with possible 3 options: None, ForceModuleImport, All

This should be updated to match current version.

In New language features in PowerShell 5.0
https://msdn.microsoft.com/en-us/powershell/wmf/class_newtype

It states:
Four new attributes, DscResource, DscResourceKey, DscResourceMandatory, and DscResourceOut have been added.

In Class-based DSC Resources
https://msdn.microsoft.com/en-us/powershell/wmf/dsc_classbasedresource

The example shows usage of
DscProperty(Key), DscProperty(Mandatory) and I assume there would have been a
DSCProperty(Out) but its not implemented in the example.

On the same subject, the example also shows usage of DscProperty(NotConfigurable) but theres no mention of it on the first link.

This was raised by @TravisEz13 in this DSCResources issue.

I have completed the document as suggested by @TravisEz13 based on his blog post.

It should complete task 1:

"We should create a doc on best practices for securing the environment. The first version could be based on the blog and should be put in PowerShell-Docs/Dsc (this is the proper location because this is a general DSC best practice) documentation (e.g. https://github.com/PowerShell/PowerShell-Docs/blob/master/dsc/configDataCredentials.md)"

I will submit the PR for this shortly.

troubleshooting.md is missing a bunch of images (represented for now with TODO statements).
xDscDiagnostics module contains 4 functions. Only two functions are mentioned in the article.

Currently I see 'master' branch and 'live' branch.
It's worth to know branch strategy: where send PRs, when something goes live, etc.

This is in SecureMOF:

Note: If your target node is a Nano Server, you should use the CertOC.exe application to import the private key certificate because the Import-PfxCertificate cmdlet is not available.

It should be removed because TP5 now supports these cmdlets so CertOC.exe doesn't need to be used.

I will submit a PR

https://github.com/PowerShell/PowerShell-Docs/blob/staging/dsc/directCallResource.md

See:
http://stackoverflow.com/questions/37056408/invoke-dscresource-on-windowsfeatureset-fails

The code needs to be updated to match the most recent xTimezone code.

I will submit a PR.

I searched the repository for "conformance" and came up empty-handed. The Conformance Endpoint should be documented, as well its database schema, so that developers can create tooling surrounding this feature.

Cheers,
Trevor Sullivan
Microsoft MVP: PowerShell
http://trevorsullivan.net
http://twitter.com/pcgeek86

@joeyaiello ... It should go to "master" branch instead.
For example: Clicking contribute on https://msdn.microsoft.com/en-us/powershell/wmf/releasenotes takes to https://github.com/PowerShell/PowerShell-Docs/blob/live/wmf/releasenotes.md .. it should take the contributor to https://github.com/PowerShell/PowerShell-Docs/blob/master/wmf/releasenotes.md

It states you can use Nested Modules to host DSCResource classes. You cannot.

Topics throughout the entire WMF 5.0 release notes have text conversion issues like: < > #

https://msdn.microsoft.com/en-us/powershell/wmf/dsc_classbasedresource

Line 48 of the main example has an extra ' that breaks the code

@jianyunt In oneget_cmdlets.md (which is available at https://msdn.microsoft.com/en-us/powershell/wmf/oneget_cmdlets) it would be great to cross reference them with cmdlet help links from
https://technet.microsoft.com/en-us/library/mt422622.aspx

The pull server creation example code is neither complete nor correct nor current. Customers need a working example.
https://github.com/PowerShell/PowerShell-Docs/blob/master/dsc/pullServer.md

New-SelfSignedCertificate -Type DocumentEncryptionCertLegacyCsp -DnsName 'DscEncryptionCert' -HashAlgorithm SHA256

The change is required to be FIPS compliant, not for compatibility with DSC

In Contributing.md it is suggested that new issues are tagged with "In Progress":

• Open a new issue tagged as "in progress" to tell others what you're working on

However, only members of the organization that owns the repository can tag (label) issues. So, only members of the PowerShell org can tag (label) new issues or PR's. This suggestion should be clarified to prevent confusion.

Also, "tagged" should be changed to "labeled" to match what GitHub calls tags.

I didn't tag this issue as "In Progress", because I can't, but it is "In Progress". 😄