Egyéni DSC-erőforrás írása PowerShell-osztályokkal
A következőkre vonatkozik: Windows PowerShell 5.0
A PowerShell-osztályok Windows PowerShell 5.0-s verziójának bevezetésével mostantól definiálhat egy DSC-erőforrást egy osztály létrehozásával. Az osztály meghatározza az erőforrás sémáját és implementációját is, így nincs szükség külön MOF-fájl létrehozására. Az osztályalapú erőforrások mappastruktúrája is egyszerűbb, mivel a DSCResources mappa nem szükséges.
Egy osztályalapú DSC-erőforrásban a séma az osztály tulajdonságaiként van definiálva, amely attribútumokkal módosítható a tulajdonságtípus megadásához. Az erőforrást Get()
, Set()
és Test()
metódusok implementálják (egyenértékű a szkripterőforrás Get-TargetResource
, Set-TargetResource
és Test-TargetResource
függvényeivel).
Ebben a cikkben létrehozunk egy NewFile nevű egyszerű erőforrást, amely egy megadott elérési úton kezeli a fájlokat.
További információ a DSC-erőforrásokról: Egyéni Windows PowerShell kívánt állapotkonfigurációs erőforrások létrehozása
Jegyzet
Az általános gyűjtemények nem támogatottak az osztályalapú erőforrásokban.
Osztályerőforrás mappastruktúrája
Ha egyéni DSC-erőforrást szeretne implementálni egy PowerShell-osztálysal, hozza létre a következő mappastruktúrát.
Az osztály MyDscResource.psm1
van definiálva, a moduljegyzék pedig a MyDscResource.psd1
.
$env:ProgramFiles\WindowsPowerShell\Modules (folder)
|- MyDscResource (folder)
MyDscResource.psm1
MyDscResource.psd1
Az osztály létrehozása
Az osztály kulcsszóval hozhat létre Egy PowerShell-osztályt. Az osztály DSC-erőforrásként való megadásához használja a DscResource()
attribútumot. Az osztály neve a DSC-erőforrás neve.
[DscResource()]
class NewFile {
}
Tulajdonságok deklarálása
A DSC-erőforrásséma az osztály tulajdonságaiként van definiálva. Három tulajdonságot deklarálunk az alábbiak szerint.
[DscProperty(Key)]
[string] $path
[DscProperty(Mandatory)]
[ensure] $ensure
[DscProperty()]
[string] $content
[DscProperty(NotConfigurable)]
[MyDscResourceReason[]] $Reasons
Figyelje meg, hogy a tulajdonságokat attribútumok módosítják. Az attribútumok jelentése a következő:
- DscProperty(Key): A tulajdonság megadása kötelező. A tulajdonság egy kulcs. A kulcsként megjelölt összes tulajdonság értékeinek egyesíteniük kell az erőforráspéldány egyedi azonosításához egy konfiguráción belül.
- DscProperty(Kötelező): A tulajdonság megadása kötelező.
-
DscProperty(NotConfigurable): A tulajdonság írásvédett. Az ezzel az attribútummal megjelölt tulajdonságokat nem lehet konfigurációval beállítani, de a
Get()
metódus tölti fel, ha jelen van. - DscProperty(): A tulajdonság konfigurálható, de nem kötelező.
A $Path
és a $SourcePath
tulajdonságok egyaránt sztringek. A $CreationTime
egy DateTime tulajdonság. A $Ensure
tulajdonság egy enumerálási típus, amely az alábbiak szerint van definiálva.
enum Ensure
{
Absent
Present
}
Osztályok beágyazása
Ha olyan új típust szeretne felvenni, amely definiált tulajdonságokkal rendelkezik, amelyeket az erőforráson belül használhat, csak hozzon létre egy, a fent ismertetett tulajdonságtípusokkal rendelkező osztályt.
class MyDscResourceReason {
[DscProperty()]
[string] $Code
[DscProperty()]
[string] $Phrase
}
Jegyzet
A MyDscResourceReason
osztály itt deklarálva van a modul nevével előtagként. Bár bármilyen nevet adhat a beágyazott osztályoknak, ha két vagy több modul azonos nevű osztályt határoz meg, és mindkettőt egy konfigurációban használják, a PowerShell kivételt okoz.
A DSC-ben a névütközések által okozott kivételek elkerülése érdekében a beágyazott osztályok nevét a modul nevével kell előtaggal előtaggal elnevezni. Ha a beágyazott osztály neve már nem valószínű, hogy ütközik, előtag nélkül is használhatja.
Ha a DSC-erőforrást az Azure Automanage gépkonfigurációs funkciójával való használatra tervezték, mindig előtagként adja meg a Okok tulajdonsághoz létrehozott beágyazott osztály nevét.
Nyilvános és privát függvények
PowerShell-függvényeket ugyanabban a modulfájlban hozhat létre, és használhatja őket a DSC-osztályerőforrás metódusai között. A függvényeket nyilvánosként kell deklarálni, a nyilvános függvények szkriptblokkja azonban meghívhat privát függvényeket. Az egyetlen különbség az, hogy szerepelnek-e a moduljegyzék FunctionsToExport
tulajdonságában.
<#
Public Functions
#>
function Get-File {
param(
[ensure]$ensure,
[parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[String]$path,
[String]$content
)
$fileContent = [MyDscResourceReason]::new()
$fileContent.code = 'file:file:content'
$filePresent = [MyDscResourceReason]::new()
$filePresent.code = 'file:file:path'
$ensureReturn = 'Absent'
$fileExists = Test-path $path -ErrorAction SilentlyContinue
if ($true -eq $fileExists) {
$filePresent.phrase = "The file was expected to be: $ensure`nThe file exists at path: $path"
$existingFileContent = Get-Content $path -Raw
if ([string]::IsNullOrEmpty($existingFileContent)) {
$existingFileContent = ''
}
if ($false -eq ([string]::IsNullOrEmpty($content))) {
$content = $content | ConvertTo-SpecialChars
}
$fileContent.phrase = "The file was expected to contain: $content`nThe file contained: $existingFileContent"
if ($content -eq $existingFileContent) {
$ensureReturn = 'Present'
}
}
else {
$filePresent.phrase = "The file was expected to be: $ensure`nThe file does not exist at path: $path"
$path = 'file not found'
}
return @{
ensure = $ensureReturn
path = $path
content = $existingFileContent
Reasons = @($filePresent,$fileContent)
}
}
function Set-File {
param(
[ensure]$ensure = "Present",
[parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[String]$path,
[String]$content
)
Remove-Item $path -Force -ErrorAction SilentlyContinue
if ($ensure -eq "Present") {
New-Item $path -ItemType File -Force
if ([ValidateNotNullOrEmpty()]$content) {
$content | ConvertTo-SpecialChars | Set-Content $path -NoNewline -Force
}
}
}
function Test-File {
param(
[ensure]$ensure = "Present",
[parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[String]$path,
[String]$content
)
$test = $false
$get = Get-File @PSBoundParameters
if ($get.ensure -eq $ensure) {
$test = $true
}
return $test
}
<#
Private Functions
#>
function ConvertTo-SpecialChars {
param(
[parameter(Mandatory = $true,ValueFromPipeline)]
[ValidateNotNullOrEmpty()]
[string]$string
)
$specialChars = @{
'`n' = "`n"
'\\n' = "`n"
'`r' = "`r"
'\\r' = "`r"
'`t' = "`t"
'\\t' = "`t"
}
foreach ($char in $specialChars.Keys) {
$string = $string -replace ($char,$specialChars[$char])
}
return $string
}
A módszerek implementálása
A Get()
, Set()
és Test()
metódusok hasonlóak a szkripterőforrás Get-TargetResource
, Set-TargetResource
és Test-TargetResource
függvényéhez.
Ajánlott eljárásként minimalizálja a kód mennyiségét az osztály implementálásán belül. Ehelyett helyezze át a kód nagy részét a modul nyilvános függvényeibe, amelyek ezután egymástól függetlenül tesztelhetők.
<#
This method is equivalent of the Get-TargetResource script function.
The implementation should use the keys to find appropriate
resources. This method returns an instance of this class with the
updated key properties.
#>
[NewFile] Get() {
$get = Get-File -ensure $this.ensure -path $this.path -content $this.content
return $get
}
<#
This method is equivalent of the Set-TargetResource script function.
It sets the resource to the desired state.
#>
[void] Set() {
$set = Set-File -ensure $this.ensure -path $this.path -content $this.content
}
<#
This method is equivalent of the Test-TargetResource script
function. It should return True or False, showing whether the
resource is in a desired state.
#>
[bool] Test() {
$test = Test-File -ensure $this.ensure -path $this.path -content $this.content
return $test
}
A teljes fájl
A teljes osztályfájl a következő.
enum ensure {
Absent
Present
}
<#
This class is used within the DSC Resource to standardize how data
is returned about the compliance details of the machine. Note that
the class name is prefixed with the module name - this helps prevent
errors raised when multiple modules with DSC Resources define the
Reasons property for reporting when they're out-of-state.
#>
class MyDscResourceReason {
[DscProperty()]
[string] $Code
[DscProperty()]
[string] $Phrase
}
<#
Public Functions
#>
function Get-File {
param(
[ensure]$ensure,
[parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[String]$path,
[String]$content
)
$fileContent = [MyDscResourceReason]::new()
$fileContent.code = 'file:file:content'
$filePresent = [MyDscResourceReason]::new()
$filePresent.code = 'file:file:path'
$ensureReturn = 'Absent'
$fileExists = Test-path $path -ErrorAction SilentlyContinue
if ($true -eq $fileExists) {
$filePresent.phrase = "The file was expected to be: $ensure`nThe file exists at path: $path"
$existingFileContent = Get-Content $path -Raw
if ([string]::IsNullOrEmpty($existingFileContent)) {
$existingFileContent = ''
}
if ($false -eq ([string]::IsNullOrEmpty($content))) {
$content = $content | ConvertTo-SpecialChars
}
$fileContent.phrase = "The file was expected to contain: $content`nThe file contained: $existingFileContent"
if ($content -eq $existingFileContent) {
$ensureReturn = 'Present'
}
}
else {
$filePresent.phrase = "The file was expected to be: $ensure`nThe file does not exist at path: $path"
$path = 'file not found'
}
return @{
ensure = $ensureReturn
path = $path
content = $existingFileContent
Reasons = @($filePresent,$fileContent)
}
}
function Set-File {
param(
[ensure]$ensure = "Present",
[parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[String]$path,
[String]$content
)
Remove-Item $path -Force -ErrorAction SilentlyContinue
if ($ensure -eq "Present") {
New-Item $path -ItemType File -Force
if ([ValidateNotNullOrEmpty()]$content) {
$content | ConvertTo-SpecialChars | Set-Content $path -NoNewline -Force
}
}
}
function Test-File {
param(
[ensure]$ensure = "Present",
[parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[String]$path,
[String]$content
)
$test = $false
$get = Get-File @PSBoundParameters
if ($get.ensure -eq $ensure) {
$test = $true
}
return $test
}
<#
Private Functions
#>
function ConvertTo-SpecialChars {
param(
[parameter(Mandatory = $true,ValueFromPipeline)]
[ValidateNotNullOrEmpty()]
[string]$string
)
$specialChars = @{
'`n' = "`n"
'\\n' = "`n"
'`r' = "`r"
'\\r' = "`r"
'`t' = "`t"
'\\t' = "`t"
}
foreach ($char in $specialChars.Keys) {
$string = $string -replace ($char,$specialChars[$char])
}
return $string
}
<#
This resource manages the file in a specific path.
[DscResource()] indicates the class is a DSC resource
#>
[DscResource()]
class NewFile {
<#
This property is the fully qualified path to the file that is
expected to be present or absent.
The [DscProperty(Key)] attribute indicates the property is a
key and its value uniquely identifies a resource instance.
Defining this attribute also means the property is required
and DSC will ensure a value is set before calling the resource.
A DSC resource must define at least one key property.
#>
[DscProperty(Key)]
[string] $path
<#
This property indicates if the settings should be present or absent
on the system. For present, the resource ensures the file pointed
to by $Path exists. For absent, it ensures the file point to by
$Path does not exist.
The [DscProperty(Mandatory)] attribute indicates the property is
required and DSC will guarantee it is set.
If Mandatory is not specified or if it is defined as
Mandatory=$false, the value is not guaranteed to be set when DSC
calls the resource. This is appropriate for optional properties.
#>
[DscProperty(Mandatory)]
[ensure] $ensure
<#
This property is optional. When provided, the content of the file
will be overwridden by this value.
#>
[DscProperty()]
[string] $content
<#
This property reports the reasons the machine is or is not compliant.
[DscProperty(NotConfigurable)] attribute indicates the property is
not configurable in DSC configuration. Properties marked this way
are populated by the Get() method to report additional details
about the resource when it is present.
#>
[DscProperty(NotConfigurable)]
[MyDscResourceReason[]] $Reasons
<#
This method is equivalent of the Get-TargetResource script function.
The implementation should use the keys to find appropriate
resources. This method returns an instance of this class with the
updated key properties.
#>
[NewFile] Get() {
$get = Get-File -ensure $this.ensure -path $this.path -content $this.content
return $get
}
<#
This method is equivalent of the Set-TargetResource script function.
It sets the resource to the desired state.
#>
[void] Set() {
$set = Set-File -ensure $this.ensure -path $this.path -content $this.content
}
<#
This method is equivalent of the Test-TargetResource script
function. It should return True or False, showing whether the
resource is in a desired state.
#>
[bool] Test() {
$test = Test-File -ensure $this.ensure -path $this.path -content $this.content
return $test
}
}
Jegyzék létrehozása
Ha elérhetővé szeretne tenni egy osztályalapú erőforrást a DSC-motor számára, tartalmaznia kell egy DscResourcesToExport
utasítást a jegyzékfájlban, amely arra utasítja a modult, hogy exportálja az erőforrást. A jegyzék a következőképpen néz ki:
@{
# Script module or binary module file associated with this manifest.
RootModule = 'NewFile.psm1'
# Version number of this module.
ModuleVersion = '1.0.0'
# ID used to uniquely identify this module
GUID = 'fad0d04e-65d9-4e87-aa17-39de1d008ee4'
# Author of this module
Author = 'Microsoft Corporation'
# Company or vendor of this module
CompanyName = 'Microsoft Corporation'
# Copyright statement for this module
Copyright = ''
# Description of the functionality provided by this module
Description = 'Create and set content of a file'
# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '5.0'
# Functions to export from this module
FunctionsToExport = @('Get-File','Set-File','Test-File')
# DSC resources to export from this module
DscResourcesToExport = @('NewFile')
# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{
PSData = @{
# Tags applied to this module. These help with module discovery in online galleries.
# Tags = @(Power Plan, Energy, Battery)
# A URL to the license for this module.
# LicenseUri = ''
# A URL to the main website for this project.
# ProjectUri = ''
# A URL to an icon representing this module.
# IconUri = ''
# ReleaseNotes of this module
# ReleaseNotes = ''
} # End of PSData hashtable
}
}
Az erőforrás tesztelése
Miután mentette az osztály- és jegyzékfájlokat a mappastruktúrában a korábban ismertetett módon, létrehozhat egy konfigurációt, amely az új erőforrást használja. A DSC-konfigurációk futtatásával kapcsolatos információkért lásd konfigurációk. Az alábbi konfiguráció ellenőrzi, hogy létezik-e a fájl /tmp/test.txt
, és hogy a tartalom megegyezik-e a "Content" tulajdonság által megadott sztringgel. Ha nem, a teljes fájl meg van írva.
Configuration MyConfig
{
Import-DSCResource -ModuleName NewFile
NewFile testFile
{
Path = "/tmp/test.txt"
Content = "DSC Rocks!"
Ensure = "Present"
}
}
MyConfig
PsDscRunAsCredential támogatása
[Megjegyzés] a PsDscRunAsCredential
a PowerShell 5.0-s és újabb verziói támogatják.
A PsDscRunAsCredential tulajdonság használható DSC-konfigurációkban erőforrásblokkban annak megadásához, hogy az erőforrást egy megadott hitelesítőadat-készlet alatt kell futtatni. További információ: DSC futtatása felhasználói hitelesítő adatokkal.
PsDscRunAsCredential megkövetelése vagy letiltása az erőforráshoz
A DscResource()
attribútum egy választható paramétert RunAsCredential. Ez a paraméter a következő három érték egyikét veszi fel:
-
Optional
PsDscRunAsCredential nem kötelező az erőforrást meghívó konfigurációk esetében. Ez az alapértelmezett érték. -
Mandatory
PsDscRunAsCredential kell használni minden olyan konfigurációhoz, amely meghívja ezt az erőforrást. -
NotSupported
Az erőforrást meghívó konfigurációk nem használhatják PsDscRunAsCredential. -
Default
ugyanaz, mintOptional
.
Az alábbi attribútum használatával például megadhatja, hogy az egyéni erőforrás nem támogatja-e PsDscRunAsCredentialhasználatát:
[DscResource(RunAsCredential=NotSupported)]
class NewFile {
}
Több osztályerőforrás deklarálása egy modulban
Egy modul több osztályalapú DSC-erőforrást is definiálhat. Csak deklarálnia kell az összes osztályt ugyanabban a .psm1
fájlban, és minden nevet fel kell vennie a .psd1
jegyzékbe.
$env:ProgramFiles\WindowsPowerShell\Modules (folder)
|- MyDscResource (folder)
|- MyDscResource.psm1
MyDscResource.psd1
Hozzáférés a felhasználói környezethez
Ha egyéni erőforráson belülről szeretné elérni a felhasználói környezetet, használhatja az automatikus változót $global:PsDscContext
.
Az alábbi kód például azt a felhasználói környezetet írja meg, amely alatt az erőforrás fut a részletes kimeneti adatfolyamon:
if (PsDscContext.RunAsUser) {
Write-Verbose "User: $global:PsDscContext.RunAsUser";
}
Lásd még:
Egyéni Windows PowerShell kívánt állapotkonfigurációs erőforrások létrehozása