Skip to content

Commit 482309b

Browse files
dan-hughesdan-hughes
authored
Add documentation (#31)
1 parent 083c602 commit 482309b

File tree

3 files changed

+317
-1
lines changed

3 files changed

+317
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
55

66
## [Unreleased]
77

8+
### Added
9+
10+
- Wiki
11+
- How to use this base class. Fixes [#5](https://github.com/dsccommunity/DscResource.Base/issues/5)
12+
and [#19](https://github.com/dsccommunity/DscResource.Base/issues/19).
13+
814
## [1.3.0] - 2025-03-15
915

1016
### Added

‎source/WikiSource/Getting-started.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
---
2+
Category: Documentation
3+
---
4+
5+
# Getting started
6+
7+
This module provides a base class for creating DSC resources.
8+
9+
Assuming you are using the DscCommunity Sampler template, add `DscResource.Base` to your `RequiredModules.psd1`.
10+
11+
Ensure that your `prefix.ps1` contains `using module .\Modules\DscResource.Base` to import the module.
12+
13+
Add the following into a new file (typical location `source\Classes`):
14+
15+
```powershell
16+
[DscResource()]
17+
class MyDscResource : ResourceBase
18+
{
19+
<#
20+
PROPERTIES
21+
#>
22+
23+
MyDscResource () : base ($PSScriptRoot)
24+
{
25+
$this.ExcludeDscProperties = @()
26+
$this.FeatureOptionalEnums = $false
27+
}
28+
29+
# Required DSC Methods, these call the method in the base class.
30+
[MyDscResource] Get()
31+
{
32+
# Call the base method to return the properties.
33+
return ([ResourceBase] $this).Get()
34+
}
35+
36+
[void] Set()
37+
{
38+
# Call the base method to enforce the properties.
39+
([ResourceBase] $this).Set()
40+
}
41+
42+
[System.Boolean] Test()
43+
{
44+
# Call the base method to test all of the properties that should be enforced.
45+
return ([ResourceBase] $this).Test()
46+
}
47+
48+
<#
49+
Base method Get() call this method to get the current state as a Hashtable.
50+
The parameter properties contains any DSC properties defined as 'Key'.
51+
#>
52+
[System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
53+
{
54+
}
55+
56+
<#
57+
Base method Set() call this method with the properties that should be
58+
enforced and that are not in desired state.
59+
#>
60+
hidden [void] Modify([System.Collections.Hashtable] $properties)
61+
{
62+
}
63+
64+
# OPTIONAL
65+
<#
66+
This method can be overridden if resource specific property asserts are
67+
needed. The parameter properties will contain the properties that are
68+
assigned a value.
69+
#>
70+
hidden [void] AssertProperties([System.Collections.Hashtable] $properties)
71+
{
72+
}
73+
74+
<#
75+
This method can be overridden if resource specific property normalization
76+
is needed. The parameter properties will contain the properties that are
77+
assigned a value.
78+
#>
79+
hidden [void] NormalizeProperties([System.Collections.Hashtable] $properties)
80+
{
81+
}
82+
}
83+
```
84+
85+
## Properties
86+
87+
Value type properties like `Boolean`, `Int`, `UInt` must have their type made
88+
nullable e.g. `[Nullable[System.Boolean]]`.
89+
90+
Reference type properties like `String` are already nullable.
91+
92+
Enums may be used, by default only for properties marked `Key` or `Mandatory`.
93+
There is an optional feature flag available that allows use of Enums for `Optional`
94+
properties without a default value configured.
95+
See [Constructor Properties](#constructor-properties).
96+
97+
### Ensure
98+
99+
The base class ships with an `Ensure` Enum which you may use. This is typically
100+
a mandatory property. If optional it must be set to a default value
101+
e.g. `$Ensure = [Ensure]:Present`.
102+
103+
```powershell
104+
[DscProperty(Mandatory)]
105+
[Ensure]
106+
$Ensure
107+
```
108+
109+
### Reasons
110+
111+
The base class will populate the `Reasons` property if the actual state does not
112+
match the current state. If a `Reasons` property is not provided then this is omitted.
113+
114+
To utilize `Reasons` this you must create your own `Reason` class for the module.
115+
This needs to be unique among all the loaded classes (e.g resources) used on the
116+
same target computer.
117+
118+
This is typically is prefixed with the module name. The example below is what is
119+
used in `SqlServerDsc`.
120+
121+
```powershell
122+
<#
123+
.SYNOPSIS
124+
The reason a property of a DSC resource is not in desired state.
125+
126+
.DESCRIPTION
127+
A DSC resource can have a read-only property `Reasons` that the compliance
128+
part of Azure AutoManage Machine Configuration uses.
129+
The property Reasons holds an array of SqlReason. Each SqlReason
130+
explains why a property of a DSC resource is not in desired state.
131+
#>
132+
133+
class SqlReason
134+
{
135+
[DscProperty()]
136+
[System.String]
137+
$Code
138+
139+
[DscProperty()]
140+
[System.String]
141+
$Phrase
142+
}
143+
```
144+
145+
This is how you would declare the property.
146+
147+
```powershell
148+
[DscProperty(NotConfigurable)]
149+
[SqlReason[]]
150+
$Reasons
151+
```
152+
153+
## Constructor
154+
155+
The constructor above shows the minimum implementation required.
156+
`$PSScriptRoot` is passed down to the base class to update the location of the
157+
localization files. Without this you may see an error when using the resource of
158+
not being able to find localization data. How to use [String Localization](#localization).
159+
160+
### Constructor Properties
161+
162+
The following properties can be set in the constructor.
163+
164+
#### ExcludeDscProperties
165+
166+
By default all `Key`, `Mandatory` and `Optional` DSC properties are enforced in
167+
the base class.
168+
`ExcludeDscProperties` is used to prevent the provided properties from being enforced.
169+
This is in the format of a list of strings.
170+
171+
```powershell
172+
MyDscResource () : base ($PSScriptRoot)
173+
{
174+
$this.ExcludeDscProperties = @(
175+
'PropertyOne',
176+
'PropertyTwo'
177+
)
178+
179+
$this.FeatureOptionalEnums = $false
180+
}
181+
```
182+
183+
#### FeatureOptionalEnums
184+
185+
`FeatureOptionalEnums` when enabled will allow the use of Enums for optional
186+
properties where a default value is not set.
187+
188+
These do require special consideration when a default value is not provided,
189+
the Enum must be created with a starting value of 1. Leaving 0 for uninitialized.
190+
This is due to not being able to declare the type as `Nullable` in PowerShell DSC.
191+
192+
```powershell
193+
enum MyEnum
194+
{
195+
Square = 1
196+
Circle
197+
}
198+
199+
[DscResource()]
200+
class MyDscResource : ResourceBase
201+
{
202+
203+
[DscProperty()]
204+
[MyEnum]
205+
$MyProperty
206+
207+
MyDscResource () : base ($PSScriptRoot)
208+
{
209+
$this.ExcludeDscProperties = @(
210+
'PropertyOne',
211+
'PropertyTwo'
212+
)
213+
214+
$this.FeatureOptionalEnums = $true
215+
}
216+
}
217+
```
218+
219+
## Methods
220+
221+
The two methods you must implement which are `GetCurrentState()` and `Modify()`.
222+
There are two optional methods which you may use these are `AssertProperties()` and
223+
`NormalizeProperties()`.
224+
225+
### GetCurrentState
226+
227+
This method is used to get the current state of the resource based on the passed
228+
key properties. This is called by `Get()`.
229+
230+
The `$properties` argument passed into this method is a hashtable of any
231+
properties marked `Key`.
232+
233+
These properties should normally be used for any arguments on commands called
234+
within this method `$properties.PropertyName` and not using `$this.PropertyName`.
235+
236+
The hashable only needs to return the values that are not `$null`. Any that are
237+
`$null` can be omitted as these are added to the hashtable from the calling
238+
method.
239+
240+
### Modify
241+
242+
This method is used to change the state of the resource being controlled.
243+
This is called by `Set()`.
244+
245+
The `$properties` passed into this method are the ones that need to be enforced and
246+
are not in the desired state.
247+
248+
This function can either be used for any `Set/Add/Remove` behavior, but if this
249+
needs breaking up then additional methods can be created within your class
250+
and called from here.
251+
252+
### AssertProperties
253+
254+
This method is called before getting any state or resources and is used to assert
255+
or validate properties or property sets as this is not available in class-based
256+
DSC resources.
257+
258+
Example uses:
259+
260+
- Checking use of mutually exclusive properties.
261+
- Validating values are correct e.g. StartTime < EndTime.
262+
263+
### NormalizeProperties
264+
265+
This method is used to Normalize any property values that may have been provided
266+
by the user but can be standardized.
267+
268+
Example uses:
269+
270+
- Formatting a file path
271+
- Formatting a URL
272+
273+
## Localization
274+
275+
String localization is supported in the base class. This allows the use
276+
of a localization variable in the format `$this.localizedData.MyLocalizedStringKey`
277+
in code and then this be referenced in a `.psd1` file for each language translation.
278+
279+
By default the `en-US` culture must be populated (location `source\en-US`).
280+
The filename must be in the format `ClassName.strings.psd1`. If no strings are
281+
declared then an empty file must be configured.
282+
283+
Example empty strings file.
284+
285+
```powershell
286+
<#
287+
.SYNOPSIS
288+
The localized resource strings in English (en-US) for the
289+
class {ClassName}.
290+
#>
291+
292+
ConvertFrom-StringData @'
293+
'@
294+
```
295+
296+
Example populated strings file.
297+
298+
```powershell
299+
<#
300+
.SYNOPSIS
301+
The localized resource strings in English (en-US) for the
302+
class {ClassName}.
303+
#>
304+
305+
ConvertFrom-StringData @'
306+
MyLocalizedStringKey = This is a localized string with a passed in value '{0}'. (MD0001)
307+
'@
308+
```

‎source/WikiSource/Home.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@ Please leave comments, feature requests, and bug reports for this module in
99
the [issues section](https://github.com/dsccommunity/DscResource.Base/issues)
1010
for this repository.
1111

12-
## Getting started
12+
## Getting Started
13+
14+
Find out how to use this base class in [getting started](https://github.com/dsccommunity/DscResource.Base/wiki/Getting-started).
1315

1416
## Prerequisites
1517

0 commit comments

Comments
 (0)