Escrever um recurso DSC personalizado com classes do PowerShell
Aplica-se a: Windows PowerShell 5.0
Com a introdução das classes do PowerShell no Windows PowerShell 5.0, agora pode definir um recurso do DSC ao criar uma classe. A classe define o esquema e a implementação do recurso, pelo que não é necessário criar um ficheiro MOF separado. A estrutura de pastas de um recurso baseado em classes também é mais simples, porque não é necessária uma pasta DSCResources .
Num recurso DSC baseado na classe, o esquema é definido como propriedades da classe que podem ser modificadas com atributos para especificar o tipo de propriedade. O recurso é implementado pelos Get()métodos , Set()e Test() (equivalentes Get-TargetResourceàs funções , Set-TargetResourcee Test-TargetResource num recurso de script.
Neste artigo, vamos criar um recurso simples com o nome NewFile que gere um ficheiro num caminho especificado.
Para obter mais informações sobre os recursos do DSC, veja Build Custom Windows PowerShell Desired State Configuration Resources (Criar Recursos de Windows PowerShell Desired State Configuration Personalizados)
Nota
As coleções genéricas não são suportadas em recursos baseados na classe.
Estrutura de pastas para um recurso de classe
Para implementar um recurso personalizado do DSC com uma classe do PowerShell, crie a seguinte estrutura de pastas.
A classe é definida em MyDscResource.psm1 e o manifesto do módulo é definido em MyDscResource.psd1.
$env:ProgramFiles\WindowsPowerShell\Modules (folder)
|- MyDscResource (folder)
MyDscResource.psm1
MyDscResource.psd1
Criar a classe
Utilize a palavra-chave de classe para criar uma classe do PowerShell. Para especificar que uma classe é um recurso do DSC, utilize o DscResource() atributo . O nome da classe é o nome do recurso do DSC.
[DscResource()]
class NewFile {
}
Declarar propriedades
O esquema de recursos do DSC é definido como propriedades da classe . Declaramos três propriedades da seguinte forma.
[DscProperty(Key)]
[string] $path
[DscProperty(Mandatory)]
[ensure] $ensure
[DscProperty()]
[string] $content
[DscProperty(NotConfigurable)]
[MyDscResourceReason[]] $Reasons
Repare que as propriedades são modificadas por atributos. O significado dos atributos é o seguinte:
- DscProperty(Chave): a propriedade é necessária. A propriedade é uma chave. Os valores de todas as propriedades marcadas como chaves têm de ser combinados para identificar exclusivamente uma instância de recurso numa configuração.
- DscProperty(Obrigatório): a propriedade é necessária.
- DscProperty(NotConfigurable): a propriedade é só de leitura. As propriedades marcadas com este atributo não podem ser definidas por uma configuração, mas são preenchidas pelo
Get()método quando estão presentes. - DscProperty(): a propriedade é configurável, mas não é necessária.
As $Path propriedades e $SourcePath são ambas cadeias. É $CreationTime uma propriedade DateTime . A $Ensure propriedade é um tipo de enumeração, definido da seguinte forma.
enum Ensure
{
Absent
Present
}
Classes de incorporação
Se quiser incluir um novo tipo com propriedades definidas que pode utilizar no recurso, basta criar uma classe com tipos de propriedade, conforme descrito acima.
class MyDscResourceReason {
[DscProperty()]
[string] $Code
[DscProperty()]
[string] $Phrase
}
Nota
A MyDscResourceReason classe é declarada aqui com o nome do módulo como um prefixo. Embora possa atribuir qualquer nome às classes incorporadas, se dois ou mais módulos definirem uma classe com o mesmo nome e forem ambos utilizados numa configuração, o PowerShell gera uma exceção.
Para evitar exceções causadas por conflitos de nomes no DSC, prefixe os nomes das classes incorporadas com o nome do módulo. Se o nome da sua classe incorporada já for improvável que entre em conflito, pode utilizá-lo sem um prefixo.
Se o recurso do DSC for concebido para ser utilizado com a funcionalidade de configuração do computador do Azure Automanage, prefixe sempre o nome da classe incorporada que criar para a propriedade Motivos .
Funções Públicas e Privadas
Pode criar funções do PowerShell no mesmo ficheiro de módulo e utilizá-las dentro dos métodos do recurso da classe DSC. As funções têm de ser declaradas como públicas. No entanto, os blocos de script nessas funções públicas podem chamar funções privadas. A única diferença é se estão listados na FunctionsToExport propriedade do manifesto do módulo.
<#
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
}
Implementar os métodos
Os Get()métodos , Set()e Test() são análogos às Get-TargetResourcefunções , Set-TargetResourcee Test-TargetResource num recurso de script.
Como melhor prática, minimize a quantidade de código na implementação da classe. Em vez disso, mova a maioria do código para funções públicas no módulo, que podem ser testadas de forma independente.
<#
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
}
O ficheiro completo
Segue-se o ficheiro de classe completo.
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
}
}
Criar um manifesto
Para disponibilizar um recurso baseado na classe ao motor DSC, tem de incluir uma DscResourcesToExport instrução no ficheiro de manifesto que dê instruções ao módulo para exportar o recurso. O nosso manifesto tem o seguinte aspeto:
@{
# 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
}
}
Testar o recurso
Depois de guardar os ficheiros de classe e manifesto na estrutura de pastas, conforme descrito anteriormente, pode criar uma configuração que utilize o novo recurso. Para obter informações sobre como executar uma configuração do DSC, veja Decretar configurações. A seguinte configuração verificará se o ficheiro em /tmp/test.txt existe e se o conteúdo corresponde à cadeia fornecida pela propriedade "Content". Caso contrário, todo o ficheiro é escrito.
Configuration MyConfig
{
Import-DSCResource -ModuleName NewFile
NewFile testFile
{
Path = "/tmp/test.txt"
Content = "DSC Rocks!"
Ensure = "Present"
}
}
MyConfig
Suporte PsDscRunAsCredential
[Nota] O PsDscRunAsCredential é suportado no PowerShell 5.0 e posterior.
A propriedade PsDscRunAsCredential pode ser utilizada no bloco de recursos de configurações do DSC para especificar que o recurso deve ser executado sob um conjunto especificado de credenciais. Para obter mais informações, veja Executar o DSC com credenciais de utilizador.
Exigir ou não permitir PsDscRunAsCredential para o recurso
O DscResource() atributo utiliza um parâmetro opcional RunAsCredential. Este parâmetro utiliza um de três valores:
OptionalPsDscRunAsCredential é opcional para configurações que chamam este recurso. Este é o valor predefinido.MandatoryO PsDscRunAsCredential tem de ser utilizado para qualquer configuração que chame este recurso.NotSupportedAs configurações que chamam este recurso não podem utilizar PsDscRunAsCredential.DefaultO mesmo queOptional.
Por exemplo, utilize o seguinte atributo para especificar que o recurso personalizado não suporta a utilização de PsDscRunAsCredential:
[DscResource(RunAsCredential=NotSupported)]
class NewFile {
}
Declarar vários recursos de classe num módulo
Um módulo pode definir vários recursos de DSC baseados em classes. Só tem de declarar todas as classes no mesmo .psm1 ficheiro e incluir cada nome no .psd1 manifesto.
$env:ProgramFiles\WindowsPowerShell\Modules (folder)
|- MyDscResource (folder)
|- MyDscResource.psm1
MyDscResource.psd1
Aceder ao contexto de utilizador
Para aceder ao contexto de utilizador a partir de um recurso personalizado, pode utilizar a variável $global:PsDscContextautomática .
Por exemplo, o código seguinte escreveria o contexto de utilizador no qual o recurso está a ser executado para o fluxo de saída verboso:
if (PsDscContext.RunAsUser) {
Write-Verbose "User: $global:PsDscContext.RunAsUser";
}
Consulte também
Criar Recursos de Windows PowerShell Desired State Configuration Personalizados
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários