< Back
Write-DSCResource
Post
NAME Write-DSCResource
SYNOPSIS
Automatically generates the tedious code required to implement a DSC resource
SYNTAX
Write-DSCResource [-ResourceName] <String> [[-ModuleRoot] <String>] [-Property] <Hashtable> [-KeyProperty]
<String[]> [-ReadOnlyProperty <String[]>] [-MandatoryProperty <String[]>] [-PropertyValueMap <Hashtable>]
[-ValueMap <Hashtable>] [-Get <ScriptBlock>] [-Set <ScriptBlock>] [-Test <ScriptBlock>] [-Version <Version>]
[<CommonParameters>]
Write-DSCResource [-ResourceName] <String> [[-ModuleRoot] <String>] [-KeyProperty] <String[]> [-ReadOnlyProperty
<String[]>] [-MandatoryProperty <String[]>] [-PropertyValueMap <Hashtable>] [-ValueMap <Hashtable>] [-Get
<ScriptBlock>] [-Set <ScriptBlock>] [-Test <ScriptBlock>] [-Version <Version>] -SetCommand <CommandInfo>
[-GetCommand <CommandInfo>] [-TestCommand <CommandInfo>] [-SetDefaultParameter <Hashtable>] [-GetDefaultParameter
<Hashtable>] [-TestDefaultParameter <Hashtable>] [-SetParameterBlacklist <String[]>] [-TestParameterBlackList
<String[]>] [-GetParameterBlackList <String[]>] [-SetParameterNameMap <Hashtable>] [-ProcessTestCommandResult
<ScriptBlock>] [<CommonParameters>]
DESCRIPTION
Automatically generates the source code for a DSC resource.
The DSC resource can be generated with a simple hashtable and a set of scriptblocks, or it can be implemented by
wrapping one or more commands.
PARAMETERS
-ResourceName <String>
The name of the resource
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ModuleRoot <String>
The root directory of the module in which the DSC resource will be contained.
Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Property <Hashtable>
A hashtable describing the properties of the DSC resource. The keys are the names of the properties, and the
values are a description, with an optional type
Required? true
Position? 4
Default value
Accept pipeline input? false
Accept wildcard characters? false
-KeyProperty <String[]>
The names of the key properties.
Required? true
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ReadOnlyProperty <String[]>
A list of read only properties
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-MandatoryProperty <String[]>
A List of mandatory properties. These properties, while not used as a key, will be required for the
get/test/set functions in the DSC resource.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PropertyValueMap <Hashtable>
A hashtable containing the names of properties and their potential values
Required? false
Position? named
Default value @{}
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-ValueMap <Hashtable>
A hashtable of containing valid values or enumerations for a particular property. The key is the name of the
property. If the value is a list, the list will be the acceptable values for that property. If the value is
a hashtable, the keys will be friendly values, and the values will be the underlying system value.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-Get <ScriptBlock>
The underlying implementation of Get-TargetResource. By default, this returns an empty hashtable.
Required? false
Position? named
Default value {@{}}
Accept pipeline input? false
Accept wildcard characters? false
-Set <ScriptBlock>
The underlying implementation of Set-TargetResource. By default, this does nothing.
Required? false
Position? named
Default value {}
Accept pipeline input? false
Accept wildcard characters? false
-Test <ScriptBlock>
The underlying implementation of Test-TargetResource. By default, this returns $false.
Required? false
Position? named
Default value {return $false}
Accept pipeline input? false
Accept wildcard characters? false
-Version <Version>
The version of the DSC resource. By default, 1.0.
Required? false
Position? named
Default value 1.0
Accept pipeline input? false
Accept wildcard characters? false
-SetCommand <CommandInfo>
The Command that will be called when the resource is set. The Set Command is the only command required to
wrap a DSC resource. The Test Command must use the same parameter names
Required? true
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-GetCommand <CommandInfo>
The Command that will be called when the resource is requested. Output from this command will be converted
into PowerShell hashtables.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TestCommand <CommandInfo>
The Test Command. A non-null or empty output from this command will be considered a pass
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SetDefaultParameter <Hashtable>
Default parameters that will be passed to the set command
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-GetDefaultParameter <Hashtable>
Default parameters that will be passed to the get command.
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-TestDefaultParameter <Hashtable>
Default parameters that will be passed to the test command.
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-SetParameterBlacklist <String[]>
A list of parameters to be excluded from the Set command.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TestParameterBlackList <String[]>
A list of parameters to be excluded from the Test command. If the parameter is not in the Set blacklist, it
will exist as a DSC resource setting but will be ignored when the underlying Test command is called.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-GetParameterBlackList <String[]>
A list of parameters to be excluded from the Get command. If the parameter is not in the Set blacklist, it
will exist as a DSC resource setting but will be ignored when the underlying Get command is called.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SetParameterNameMap <Hashtable>
A map of DSC resource setting names to the underlying parameters in the Set function
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-ProcessTestCommandResult <ScriptBlock>
A ScriptBlock used to interpret the results of the test command. The variable $testResult will contain the
results of the test command. If no script block is provided, any output from the Test command will be
converted to a boolean. No output, or an explicit output of false, will fail the test.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
System.Nullable
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Write-DSCResource -Property @{
OutputPath = "The output path"
Base64Content = "The file contents, in base64"
} -Test {
if (-not [IO.File]::Exists($OutputPath)) {
return $false
}
$b64 = [Convert]::FromBase64String($Base64Content)
$md5 = [Security.Cryptography.MD5]::Create()
$hash1 = [BitConverter]::ToString($md5.ComputeHash($b64))
$hash2 = [BitConverter]::ToString($md5.ComputeHash([IO.File]::ReadAllBytes($OutputPath)))
$hash1 -eq $hash2
} -Get {
@{
OutputPath = $outputPath
Base64Content = try {
[Convert]::ToBase64String([IO.File]::ReadAllBytes($outputPath))
} catch {
$null
}
}
} -Set {
if (-not (Test-Path $outputPath)) {
$nf = New-Item -Path $outputPath -Force -ItemType File
}
[IO.File]::WriteAllBytes($outputPath, [Convert]::FromBase64String($base64Content))
} -KeyProperty OutputPath
RELATED LINKS
Initialize-DSCResource
Reset-DSCResource
SYNOPSIS
Automatically generates the tedious code required to implement a DSC resource
SYNTAX
Write-DSCResource [-ResourceName] <String> [[-ModuleRoot] <String>] [-Property] <Hashtable> [-KeyProperty]
<String[]> [-ReadOnlyProperty <String[]>] [-MandatoryProperty <String[]>] [-PropertyValueMap <Hashtable>]
[-ValueMap <Hashtable>] [-Get <ScriptBlock>] [-Set <ScriptBlock>] [-Test <ScriptBlock>] [-Version <Version>]
[<CommonParameters>]
Write-DSCResource [-ResourceName] <String> [[-ModuleRoot] <String>] [-KeyProperty] <String[]> [-ReadOnlyProperty
<String[]>] [-MandatoryProperty <String[]>] [-PropertyValueMap <Hashtable>] [-ValueMap <Hashtable>] [-Get
<ScriptBlock>] [-Set <ScriptBlock>] [-Test <ScriptBlock>] [-Version <Version>] -SetCommand <CommandInfo>
[-GetCommand <CommandInfo>] [-TestCommand <CommandInfo>] [-SetDefaultParameter <Hashtable>] [-GetDefaultParameter
<Hashtable>] [-TestDefaultParameter <Hashtable>] [-SetParameterBlacklist <String[]>] [-TestParameterBlackList
<String[]>] [-GetParameterBlackList <String[]>] [-SetParameterNameMap <Hashtable>] [-ProcessTestCommandResult
<ScriptBlock>] [<CommonParameters>]
DESCRIPTION
Automatically generates the source code for a DSC resource.
The DSC resource can be generated with a simple hashtable and a set of scriptblocks, or it can be implemented by
wrapping one or more commands.
PARAMETERS
-ResourceName <String>
The name of the resource
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ModuleRoot <String>
The root directory of the module in which the DSC resource will be contained.
Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Property <Hashtable>
A hashtable describing the properties of the DSC resource. The keys are the names of the properties, and the
values are a description, with an optional type
Required? true
Position? 4
Default value
Accept pipeline input? false
Accept wildcard characters? false
-KeyProperty <String[]>
The names of the key properties.
Required? true
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ReadOnlyProperty <String[]>
A list of read only properties
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-MandatoryProperty <String[]>
A List of mandatory properties. These properties, while not used as a key, will be required for the
get/test/set functions in the DSC resource.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PropertyValueMap <Hashtable>
A hashtable containing the names of properties and their potential values
Required? false
Position? named
Default value @{}
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-ValueMap <Hashtable>
A hashtable of containing valid values or enumerations for a particular property. The key is the name of the
property. If the value is a list, the list will be the acceptable values for that property. If the value is
a hashtable, the keys will be friendly values, and the values will be the underlying system value.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
-Get <ScriptBlock>
The underlying implementation of Get-TargetResource. By default, this returns an empty hashtable.
Required? false
Position? named
Default value {@{}}
Accept pipeline input? false
Accept wildcard characters? false
-Set <ScriptBlock>
The underlying implementation of Set-TargetResource. By default, this does nothing.
Required? false
Position? named
Default value {}
Accept pipeline input? false
Accept wildcard characters? false
-Test <ScriptBlock>
The underlying implementation of Test-TargetResource. By default, this returns $false.
Required? false
Position? named
Default value {return $false}
Accept pipeline input? false
Accept wildcard characters? false
-Version <Version>
The version of the DSC resource. By default, 1.0.
Required? false
Position? named
Default value 1.0
Accept pipeline input? false
Accept wildcard characters? false
-SetCommand <CommandInfo>
The Command that will be called when the resource is set. The Set Command is the only command required to
wrap a DSC resource. The Test Command must use the same parameter names
Required? true
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-GetCommand <CommandInfo>
The Command that will be called when the resource is requested. Output from this command will be converted
into PowerShell hashtables.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TestCommand <CommandInfo>
The Test Command. A non-null or empty output from this command will be considered a pass
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SetDefaultParameter <Hashtable>
Default parameters that will be passed to the set command
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-GetDefaultParameter <Hashtable>
Default parameters that will be passed to the get command.
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-TestDefaultParameter <Hashtable>
Default parameters that will be passed to the test command.
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-SetParameterBlacklist <String[]>
A list of parameters to be excluded from the Set command.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TestParameterBlackList <String[]>
A list of parameters to be excluded from the Test command. If the parameter is not in the Set blacklist, it
will exist as a DSC resource setting but will be ignored when the underlying Test command is called.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-GetParameterBlackList <String[]>
A list of parameters to be excluded from the Get command. If the parameter is not in the Set blacklist, it
will exist as a DSC resource setting but will be ignored when the underlying Get command is called.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-SetParameterNameMap <Hashtable>
A map of DSC resource setting names to the underlying parameters in the Set function
Required? false
Position? named
Default value @{}
Accept pipeline input? false
Accept wildcard characters? false
-ProcessTestCommandResult <ScriptBlock>
A ScriptBlock used to interpret the results of the test command. The variable $testResult will contain the
results of the test command. If no script block is provided, any output from the Test command will be
converted to a boolean. No output, or an explicit output of false, will fail the test.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
System.Nullable
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Write-DSCResource -Property @{
OutputPath = "The output path"
Base64Content = "The file contents, in base64"
} -Test {
if (-not [IO.File]::Exists($OutputPath)) {
return $false
}
$b64 = [Convert]::FromBase64String($Base64Content)
$md5 = [Security.Cryptography.MD5]::Create()
$hash1 = [BitConverter]::ToString($md5.ComputeHash($b64))
$hash2 = [BitConverter]::ToString($md5.ComputeHash([IO.File]::ReadAllBytes($OutputPath)))
$hash1 -eq $hash2
} -Get {
@{
OutputPath = $outputPath
Base64Content = try {
[Convert]::ToBase64String([IO.File]::ReadAllBytes($outputPath))
} catch {
$null
}
}
} -Set {
if (-not (Test-Path $outputPath)) {
$nf = New-Item -Path $outputPath -Force -ItemType File
}
[IO.File]::WriteAllBytes($outputPath, [Convert]::FromBase64String($base64Content))
} -KeyProperty OutputPath
RELATED LINKS
Initialize-DSCResource
Reset-DSCResource