Now that we are merging all PRs into the master, I assume that each merge should also update the README.md file?

Since it is the first info a visitor/user sees, it would be handy to list at least all the available DSC resources.

And a related question, is README.md intended for the git administrators, or can all users contribute?

Currently the Wiki pages on this repo are not open sourced.
Is it the intention to open up these pages to the community?

Since we are not supposed to commit the 2 VMware.vSphereDSC module files (.psm1 & .psd1), can we add the 2 files to .gitignore?

It is a bit confusing when the master and the dev branch have different version of documentation intended for contributors.
I'm especially thinking of .md files in the repo root.

A common best practice for Pester tests seems to be to encapsulate Pester tests in a Try-Finally construct.
Since a Finally block is always run, this allows for a cleanup of the environment, independent of the Try block outcome.

As a reference, have a look at the Pester Unit and Integration test templates that MSFT provides in their DSCResources repo.

The general layout:

function Invoke-TestSetup
{
    # Init code
}

function Invoke-TestCleanup
{
    # Cleanup code
}

Try
{
    Invoke-TestSetup
    # Tests
}
Finally
{
    Invoke-TestCleanup
}

Since you are looking at a build pipeline, what would be the targeted code coverage percent for the Pester Unit tests?
Currently there are no clear directives on what Pester Unit tests should cover.
With a potential risk of phantom, or even worse malicious, code in the contributions from the community.

Btw, Pester code coverage for DSC resource classes is an open issue.
See the Pester issue#731

Resource implementation already started #51 by @lucdekens.

Please provide formatting guidelines for the different types of files in the repo.

This commit added .vscode into the project directory to provide a settings.json file. While I understand the reason would be to help ensure consistency with linting, the .vscode directory is typically considered to be locally specific.

I can see issues with getting PRs which include changes to .vscode requiring changes etc and overall increasing overhead.

VSCode settings are already included in the formatting guidelines document.

I got stuck on writing the unit tests for PR #5 as the tests failing with:

Executing script C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPolicySetting
Tests.ps1

  Describing VMHostPowerPolicySettings

    Describing VMHostPowerPolicySettings\Get

      Context Invoking with default resource properties
        [-] Should call the Connect-VIServer mock with the passed server and credentials once 263ms
          RuntimeException: Unable to find type [VMware.Vim.PowerSystemInfo].
          at ExecuteBlock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 1123
          at Invoke-Mock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 966
          at <ScriptBlock><Process>, <No file>: line 64
          at GetVMHost, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line
          at Get, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line 191
          at <ScriptBlock>, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPo
tings.Unit.Tests.ps1: line 105
        [-] Should call Get-VMHost mock with the passed server and name once 34ms
          RuntimeException: Unable to find type [VMware.Vim.PowerSystemInfo].
          at ExecuteBlock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 1123
          at Invoke-Mock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 966
          at <ScriptBlock><Process>, <No file>: line 64
          at GetVMHost, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line
          at Get, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line 191
          at <ScriptBlock>, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPo
tings.Unit.Tests.ps1: line 115
        [-] Should return the resource with the properties passed from the server 49ms
          RuntimeException: Unable to find type [VMware.Vim.PowerSystemInfo].
          at ExecuteBlock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 1123
          at Invoke-Mock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 966
          at <ScriptBlock><Process>, <No file>: line 64
          at GetVMHost, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line
          at Get, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line 191
          at <ScriptBlock>, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPo
tings.Unit.Tests.ps1: line 125

It seams as Tests\Unit\TestHelpers\VMware.VimAutomation.Core is missing classes? How can we add the missing ones?

We currently plan to move all content from the dev branch to the master branch and then continue only with the master branch as contributions will be made via pull request. So update of the documentation and build procedures to work with master branch is needed.

When we start to tackle more complex resources in a vSphere environment, there will be more and more separate resources that logically belong together.

This proposal suggests to organise these resources in separate subfolders under the DSCResources folder. These subfolders will help in visualising the relations between resources.

As an example, the standard Virtual Switch (VSS) would consist of the following separate, but related, resources:

• VMHostVSS
• VMHostVSSSecurity
• VMHostVSSShaping
• VMHostVSSTeaming
• VMHostVSSAutoBridge
• VMHostVSSBondBridge
• VMHostVSSSimpleBridge

Under this proposal the files for these resources could be organised something like this.

The build script only needs a minor change to support this afaik.

The same concept could eventually be adopted for other folders in the repository (Documentation, Configurations...)

When we store the C# definitions in a separate .cs file, and use Add-Type -Path, we will have better control over the C# code (syntax, lint...).

While the repo is growing it might become difficult for contributors to discover what was added, removed or changed at what point in time.

To be able to easily see such changes, I propose to create a CHANGELOG document in the repo.

A PR should contain a standardised description of the changes, additions... it contains.
The build pipeline can insert that text into the CHANGELOG when the PR is merged.

The alternative is that the repo admins maintain the CHANGELOG document manually.

Or a mix of both.

I hadn't noticed this till now, but the Ensure DSCProperty only seems to be defined in the VMHostSatpClaimRule resource.
Isn't this a property that all DSC resources should have?
And hence belongs on the BaseDSC class?

I would like to add a resource for a Standard Switch (VSS).

Until #11 is completed, the placement in a Network folder will be left out.

When setting the LCM parameter DebugMode to ForceModuleImport, a configuration based on VMware.vSphereDsc resources fails with the errors

The specified mount name 'vis' is already in use.
    + CategoryInfo          : InvalidOperation: (:) [], CimException
    + FullyQualifiedErrorId : NewDriveProviderException,Microsoft.PowerShell.Commands.ImportModuleCommand
    + PSComputerName        : localhost

The specified mount name 'vmstores' is already in use.
    + CategoryInfo          : InvalidOperation: (:) [], CimException
    + FullyQualifiedErrorId : NewDriveProviderException,Microsoft.PowerShell.Commands.ImportModuleCommand
    + PSComputerName        : localhost

This DebugMode setting is useful when writing new DSC resources.
Other PS modules that provide PSDrives do not show this behaviour.

Can these errors be avoided?
Can the mounts be made more intelligent in order to not get these errors?

Can you please add a git-template to the project?
In the template I would like to have the line

Signed-off-by: Your Name [email protected]

Then with a one-time command, contributors can make sure that each commit is automatically signed.
The command

git config commit.template ~/dscr-for-vmware/git-template

The current pipeline doesn't change the module version.

I propose to align with Powershell RFC0004, which is SemVer based, and implement this in the build pipeline.

Wouldn't it be better to separate the DSCResource classes like VMHostNtpSettings in their own folder and files? Something like Resources\VMHostNtpSettings.ps1 instead of directly in .psm1.

Currently it isn't clearly documented how to install the module. Also you currently you need to clone the github repo to somewhere as the resource configurations files aren't included in the module folder.

You can read it between the lines and screenshots in the https://blogs.vmware.com/PowerCLI/2018/12/getting-started-dsc-for-vmware.html blogpost.

We have a large environment (300+ clusters) and a large number of engineers that can make changes (30+) but who may not be fully aware of the requirements for every cluster. We would like to do some enforcement of the settings on the cluster objects. These often get changed (whether inadvertently or on purpose but then not set back to the desired config).

1. HA state
2. Failure response settings
3. Admission Control settings
4. DRS state
5. DRS automation level
6. DRS thresholds
7. DRS dristribution, memory load balancing, and CPU over-commit settings
8. DRS and HA Advanced Settings

When attempting to perform a Test-DSCConfiguration I am getting errors during the process of connecting to vCenter.

Cannot establish connection to server vcsa.sdbrett.lab.
    + CategoryInfo          : NotSpecified: (:) [], CimException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException
    + PSComputerName        : localhost

Connection with PowerCLI outside of DSC works ok.

Windows 10
PS version: 5.1
PowerCLI 11.0

VCSA 6.7U1

When applying configurations or when running Unit and Integration tests on fresh environments, we hit issues.
For example, PowerCLI by default is not configured to ignore invalid certificates.
Not as critical, but equally annoying, the CEIP prompt and the deprecated warnings are there by default.

How should the DSCR handle this?
By default set this options via Set-PowerCLIConfiguration?
Or make that a separate DSC resource?

It is not entirely clear to me what type of code goes in the member functions (besides Test, Set and Get) of a DSC class, and what goes into the VMware.vSphereDSC.Helper module.

I see PowerCLI cmdlets and vSphere API methods/objects being used in both.
And I see resource specific functions in the VMware.vSphereDSC.Helper module as well.

Create base resource for inventory objects. It should provide key properties to uniquely identify inventory objects.

The current definition of the Get-View cmdlet in the TestHelper module VMware.VimAutomation.Core, is as follows:

function Get-View {
param(
[PSObject] $Server,
[PSObject] $VIObject
)

return $null

}

This doesn't allow using the same definition for other formats of the Get-View cmdlet.
I propose to implement the actual parametersets, present on the actual Get-View cmdlet.

For example (note that this is not complete)

function Get-View {
param(
[PSObject] $Server,
[Parameter(ParameterSetName = 'GetViewByVIObject')]
[PSObject] $VIObject,
[Parameter(ParameterSetName = 'GetView')]
[VMware.Vim.ManagedObjectReference] $Id,
[Parameter(ParameterSetName = 'GetView')]
[string[]] $Property
)

return $null

}

The same remark goes for other PowerCLI cmdlets present in the TestHelpder module(s)

Create HostInventoryBaseDSC class that resolves the path to a folder in the Host folder of a Datacenter.

Many vSphere components can be accessed via multiple paths.
For example a VM has a path in HostandCluster but also in VM.
The combination of these paths provide the unique location for an object.

How do we specify these different paths?
Shall these paths be keys, but perhaps not mandatory?
Do these paths belong in the BaseDsc class?

Please clarify before users start contributing, and each come up with their own solution.

I would like to contribute the host power policy setting.

The build procedure should be updated - the section that iterates over all folders and files should be modified as right now there is a problem on Ubuntu when listing them(They are listed alphabetically and not by folder structure which breaks the build in some special cases).

When writing resources, some features might be version dependent.
How shall we handle this?
Or shall we always code a resource/feature assuming it is supported?
Do we cover the complete compatibility matrix in the resources, knowing that this will change over time?

The same question for coding features, which might depend on the PowerShell/PowerCLI version?
Do we use #requires directives for that?

Can we make the actual version numbers a property of the base classes?
I'm thinking of

• vSphere API

• vCenter

• ESXi

• PowerCLI

• PowerShell

In the testhelper module VMware.VimAutomation.Core properties that should be of type ManagedObjectReference, are defined as the actual object.
For example:

public class HostConfigManager
{
public HostDateTimeSystem DateTimeSystem { get; set; }
public ManagedObjectReference NetworkSystem { get; set; }
public HostServiceSystem ServiceSystem { get; set; }
}

Where I would expect

public class HostConfigManager
{
public ManagedObjectReference DateTimeSystem { get; set; }
public ManagedObjectReference NetworkSystem { get; set; }
public ManagedObjectReference ServiceSystem { get; set; }
}

with a new object
public class ManagedObjectReference : System.IEquatable
{
public string Type { get; set; }
public string Value { get; set; }
...

This has impact on how the Mocks are set up.

Am I missing something?

Isn't it possible to generate the C# code for the Add-Type in the TestHelpers module(s)?
I assume that the object definitions are available, and that a tool (swagger-like) should be able to generate that code?

How shall we integrate enums in the Integration tests?
In the current setup/layout, the enums created for the DSC resources, are not known in the integration test environment.
As an example, the VMHostService resource uses the [ServicePolicy] enum.
How can we use these enum values in the integration tests?

Create separate resource for configuring PowerCLI Settings on the LCM. Expose all PowerCLI Settings properties in the resource.

In the Unit Helper Modules we also define vSphere objects.
It would be handy to have the names of these classes correspond with the name of the corresponding object in the API Reference.

For example, the VMHost ExtensionData property should be a HostSystem object.

In the Coding Guidelines it is proposed to have the following layout

 Describe 'MyResource' {
     Describe 'MyResource\Set' {
         ...
     }

     Describe 'MyResource\Test' {
         ...   
     }

     Describe 'MyResource\Get' {
         ...
     }
 }

But since Pester currently only checks Tags (see issue #770) on the top level Describe, we always have to run the complete test file. Which can be annoying when developing the tests.
PS: the TestName parameter does the same

Would the following be an acceptable layout?

Since the MyResource is already present in the nested Describe blocks, I don't think we would miss anything.

   Describe 'MyResource\Set' -Tag 'Set' {
         ...
   }

   Describe 'MyResource\Test' -Tag 'Test' {
         ...   
   }

   Describe 'MyResource\Get' -Tag 'Get' {
         ...
   }
 }

And this will allow us to run a specific Describe block with

Invoke-Pester .\Unit\MyResource.Unit.Tests.ps1 -Tag 'Set'

Here contributors can propose new content and sections to the Tips & Tricks page and to the Style Guidelines.

MSFT has published extensive guidelines for contributing to their DSCResources repo.

Instead of reinventing the wheel, consider adopting these guidelines, where applicable.

For example, the DSC Resource Style Guidelines & Best Practices document has a very extensive list of guidelines and best practices.

vSphere uses defaults for most of the optional properties.
How do we assign these defaults in a DSC resource?

Some options:

• make each DSC property required
• on the DSCProperty itself when it is not required
• in the Test and Set methods
• in a kind of Init method on each resource
• via an external (JSON ?) file (different files when different API/vSphere versions change the defaults)

Each of these has pros and cons, but I feel we should define how it shall be done, before more resources are introduced.

Somewhat related, how do we handle property dependencies?
When property A, for example has value 1, property B can only have values 1 and 2 but not 3.
Do we bury that in the code, or do we use a kind of definition language to document such restrictions?

It is considered good practice to provide WhatIf support on resources.

I would like to contribute a Host Services resource to control those. Should be pretty easy i think as it's currently already included in PowerCLI. I just have to get in how DSCResources are implemented.

When we have resources depending on other resources being present:

• shall we do any tests for the DependsOn parameter?
• shall these tests go under Unit and/or Integration testing?

Although my commits seem to contain

Signed-off-by: Luc Dekens <[email protected]>

I keep getting an email from the VMware CLA Bot, telling me that

Am I missing something?

To avoid that every contributor to this repo makes the same mistakes and falls into the same pitfalls, it would be nice to have a kind of FAQ.
This FAQ should contain guidelines, but also workarounds for known issues.

Create DatastoreInventoryBaseDSC class that resolves the path to a folder in the Datastore folder of a Datacenter.

Since this is an open source project, many contributors can participate.
While this is a great principle, this would also require some basic guidelines/conventions.

Some questions such guidelines might address:

• Must each proposed new resource be announced via an Issue?
• Who will review these new, proposed resources?
• What will be the status/label of a new, proposed resource that is approved for development? Up for grabs?
• Will participants be allowed to volunteer for such a new, proposed resource?
• Is that a FIFO concept? Or will volunteers be reviewed and chosen by the owners of the repo?
• When such a new resource is assigned, how does the assignee report on progress? Interval? Format?
• Can the development of a new resource be assigned to multiple assignees?
• When an assignee doesn't provide feedback for a longer, well defined period, will the Issue be opened up for a new Assignee?

In the master and dev branch all Integration tests stop and prompt for parameters.
All Integration test scripts seem to have Mandatory parameters, hence the prompt.
The IntegrationTests.ps1 script doesn't provide any parameters when starting the Integration test scripts.

There are many builds of vSphere (ESXi and VCSA) out there that are still supported.
What would be the approach for running Integration Tests?

• against the latest builds

• against the oldest builds

• against all supported builds

• against all possible combinations of builds (including mixed environments)

We don't, at least most of us don't, have the test environments available that I would assume the PowerCLI Dev Team has.

Would creating and verifying correctness of said Integration Tests once, be sufficient for submitters of PRs?
And would the PowerCLI Dev Team run the same Integration Tests than against their battery of available/possible environments for final validation?

That sounds costly, more so since we are dealing with Open Source code.