dsccommunity / dsccommunity/CommonTasks

Composite best practices: InstanceName

Open
#162 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PowerShell
Stars
45
Forks
27
PR merge metrics
No merged PRs in 30d

Description

After I lost 2 or 3 days on a stupid oversight and wasted @raandree time I'd like to propose something like a best practices page (if there isn't something already) on composite creation and save someone else a lot of time.

I made a composite where i mixed Get-DscSplattedResource and the conventional Resource definition syntax.

configuration SharePointFarm
{
    param
    (
        # Shortend
    )
    Import-DscResource -ModuleName SharePointDSC
    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    $PSBoundParameters.Remove('InstanceName')
    # Make the Setup Account a local Administrator
    xGroup 'LocalAdministrators' {
        Ensure           = 'Present'
        GroupName        = 'Administrators'
        MembersToInclude =  $SetupAccount.UserName
    }

    $ExecutionProperties = $PSBoundParameters
    $ExecutionProperties.Add('Ensure', 'Present')
    $ExecutionProperties.Add('IsSingleInstance', 'Yes')
    $ExecutionProperties.Add('PsDscRunAsCredential', $SetupAccount)
    if ($ExecutionProperties.ContainsKey('DependsOn'))
    {
        $ExecutionProperties.DependsOn = '[xGroup]LocalAdministrators'
    }
    else
    {
        $ExecutionProperties.Add('DependsOn', '[xGroup]LocalAdministrators')
    }

    $ExecutionProperties.Remove('SetupAccount')
    (Get-DscSplattedResource -ResourceName SPFarm -ExecutionName 'SPFarm' -Properties $ExecutionProperties -NoInvoke).Invoke($ExecutionProperties)


    # Setup Wizzard
    SPConfigWizard RunConfigWizard
    {
        IsSingleInstance     = "Yes"
        PsDscRunAsCredential = $SetupAccount
        DependsOn            = '[SPFarm]SPFarm'
    }
}

This code ends up make Composites with the Resouce ID [SharePointFarm] instead of [SharePointFarm]SharePointFarm
What i didn't know is that while Get-DscSplattedResource needs to have the InstanceNameremoved the conventional Resource definition needs it to create the ResourceID correctly.

After moving the .Remove('InstanceName') to the Get-DscSplattedResource Hashtable it works as expected.

configuration SharePointFarm
{
    param
    (
        # Shortend
    )
    Import-DscResource -ModuleName SharePointDSC
    Import-DscResource -ModuleName xPSDesiredStateConfiguration
    #
    # Make the Setup Account a local Administrator
    xGroup 'LocalAdministrators' {
        Ensure           = 'Present'
        GroupName        = 'Administrators'
        MembersToInclude =  $SetupAccount.UserName
    }

    # Create or Join Farm with SPFarm
    $spFarmValidParameters = @('AdminContentDatabaseName', 'ApplicationCredentialKey', 'CentralAdministrationAuth', 'CentralAdministrationPort', 'CentralAdministrationUrl', 'DatabaseCredentials', 'DatabaseServer', 'DeveloperDashboard', 'Ensure', 'FarmAccount', 'FarmConfigDatabaseName', 'Passphrase', 'RunCentralAdmin', 'ServerRole', 'SkipRegisterAsDistributedCacheHost',
        'UseSQLAuthentication')

    $spFarm = @{
        IsSingleInstance     = 'Yes'
        PsDscRunAsCredential = $SetupAccount
        DependsOn            = '[xGroup]LocalAdministrators'
    }
    foreach ($parameter in $spFarmValidParameters)
    {
        if ($PSBoundParameters.ContainsKey($parameter))
        {
            $spFarm.Add($parameter, $PSBoundParameters.Item($parameter))
        }
    }
    (Get-DscSplattedResource -ResourceName SPFarm -ExecutionName 'SPFarm' -Properties $spFarm -NoInvoke).Invoke($spFarm)


    # Setup Wizzard
    SPConfigWizard RunConfigWizard
    {
        IsSingleInstance     = "Yes"
        PsDscRunAsCredential = $SetupAccount
        DependsOn            = '[SPFarm]SPFarm'
    }
}

For discussion: Could it be a good habit to never remove a Key from the $PSBoundParameters and always call Get-DscSplattedResource with a dedicated Hashtable so you won't stab yourself in the back later if you add a resource.
Alternatively don't mix Get-DscSplattedResource with the conventional definition.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the composite configuration examples in the issue, focusing on how InstanceName is handled with Get-DscSplattedResource and conventional resource syntax. Determine whether the documentation should recommend a dedicated hashtable or avoiding mixed syntax, then document the agreed best practice and include the ResourceID outcome as a clear completion check.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.