Menulis sumber daya DSC kustom dengan MOF

Artikel
11/29/2023

Berlaku Untuk: Windows PowerShell 4.0, Windows PowerShell 5.0

Dalam artikel ini, kami akan menentukan skema untuk sumber daya kustom Windows PowerShell Desired State Configuration (DSC) dalam file MOF, dan mengimplementasikan sumber daya dalam file skrip Windows PowerShell. Sumber daya kustom ini untuk membuat dan memelihara situs web.

Membuat skema MOF

Skema menentukan properti sumber daya Anda yang dapat dikonfigurasi oleh skrip konfigurasi DSC.

Struktur folder untuk sumber daya MOF

Untuk menerapkan sumber daya kustom DSC dengan skema MOF, buat struktur folder berikut. Skema MOF didefinisikan dalam file Demo_IISWebsite.schema.mof, dan skrip sumber daya ditentukan dalam Demo_IISWebsite.psm1. Secara opsional, Anda dapat membuat file manifes modul (psd1).

$env:ProgramFiles\WindowsPowerShell\Modules (folder)
    |- MyDscResources (folder)
        |- MyDscResources.psd1 (file, required)
        |- DSCResources (folder)
            |- Demo_IISWebsite (folder)
                |- Demo_IISWebsite.psd1 (file, optional)
                |- Demo_IISWebsite.psm1 (file, required)
                |- Demo_IISWebsite.schema.mof (file, required)

Catatan

Anda perlu membuat folder bernama DSCResources di bawah folder tingkat atas, dan bahwa folder untuk setiap sumber daya harus memiliki nama yang sama dengan sumber daya.

Konten file MOF

Berikut ini adalah contoh file MOF yang dapat digunakan untuk sumber daya situs web kustom. Untuk mengikuti contoh ini, simpan skema ini ke file, dan panggil file Demo_IISWebsite.schema.mof.

[ClassVersion("1.0.0"), FriendlyName("Website")]
class Demo_IISWebsite : OMI_BaseResource
{
  [Key] string Name;
  [Required] string PhysicalPath;
  [write,ValueMap{"Present", "Absent"},Values{"Present", "Absent"}] string Ensure;
  [write,ValueMap{"Started","Stopped"},Values{"Started", "Stopped"}] string State;
  [write] string Protocol[];
  [write] string BindingInfo[];
  [write] string ApplicationPool;
  [read] string ID;
};

Perhatikan hal-hal berikut tentang kode sebelumnya:

FriendlyName menentukan nama yang dapat Anda gunakan untuk merujuk ke sumber daya kustom ini dalam skrip konfigurasi DSC. Dalam contoh ini, Website setara dengan nama Archive yang mudah diingat untuk sumber daya Arsip bawaan.
Kelas yang Anda tentukan untuk sumber daya kustom Anda harus berasal dari OMI_BaseResource.
Kualifikasi jenis, [Key], pada properti menunjukkan bahwa properti ini akan mengidentifikasi instans sumber daya secara unik. Setidaknya diperlukan satu [Key] properti.
Kualifikasi [Required] menunjukkan bahwa properti diperlukan (nilai harus ditentukan dalam skrip konfigurasi apa pun yang menggunakan sumber daya ini).
Kualifikasi [write] menunjukkan bahwa properti ini bersifat opsional saat menggunakan sumber daya kustom dalam skrip konfigurasi. Kualifikasi [read] menunjukkan bahwa properti tidak dapat diatur oleh konfigurasi, dan hanya untuk tujuan pelaporan.
Values membatasi nilai yang dapat ditetapkan ke properti ke daftar nilai yang ditentukan dalam ValueMap. Untuk informasi selengkapnya, lihat ValueMap dan Value Qualifiers.
Menyertakan properti yang disebut Ensure dengan nilai Present dan Absent di sumber daya Anda disarankan sebagai cara untuk mempertahankan gaya yang konsisten dengan sumber daya DSC bawaan.
Beri nama file skema untuk sumber daya kustom Anda sebagai berikut: classname.schema.mof, di mana classname adalah pengidentifikasi yang mengikuti class kata kunci dalam definisi skema Anda.

Menulis skrip sumber daya

Skrip sumber daya mengimplementasikan logika sumber daya. Dalam modul ini, Anda harus menyertakan tiga fungsi yang disebut Get-TargetResource, , Set-TargetResourcedan Test-TargetResource. Ketiga fungsi harus mengambil set parameter yang identik dengan kumpulan properti yang ditentukan dalam skema MOF yang Anda buat untuk sumber daya Anda. Dalam dokumen ini, kumpulan properti ini disebut sebagai "properti sumber daya." Simpan ketiga fungsi ini dalam file yang disebut <ResourceName>.psm1. Dalam contoh berikut, fungsi disimpan dalam file yang disebut Demo_IISWebsite.psm1.

Catatan

Saat Anda menjalankan skrip konfigurasi yang sama pada sumber daya Anda lebih dari sekali, Anda tidak akan menerima kesalahan dan sumber daya harus tetap dalam keadaan yang sama seperti menjalankan skrip sekali. Untuk mencapai hal ini, pastikan bahwa fungsi dan Test-TargetResource Anda Get-TargetResource membiarkan sumber daya tidak berubah, dan yang memanggil Set-TargetResource fungsi lebih dari sekali secara berurutan dengan nilai parameter yang sama selalu setara dengan memanggilnya sekali.

Get-TargetResource Dalam implementasi fungsi, gunakan nilai properti sumber daya utama yang disediakan sebagai parameter untuk memeriksa status instans sumber daya yang ditentukan. Fungsi ini harus mengembalikan tabel hash yang mencantumkan semua properti sumber daya sebagai kunci dan nilai aktual properti ini sebagai nilai yang sesuai. Kode berikut memberikan contoh.

# DSC uses the Get-TargetResource function to fetch the status of the resource instance
# specified in the parameters for the target machine
function Get-TargetResource
{
    param
    (
        [ValidateSet("Present", "Absent")]
        [string]$Ensure = "Present",

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Name,

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$PhysicalPath,

        [ValidateSet("Started", "Stopped")]
        [string]$State = "Started",

        [string]$ApplicationPool,

        [string[]]$BindingInfo,

        [string[]]$Protocol
    )

        $getTargetResourceResult = $null;

        <#
          Insert logic that uses the mandatory parameter values to get the website and
          assign it to a variable called $Website
          Set $ensureResult to "Present" if the requested website exists and to "Absent" otherwise
        #>

        # Add all Website properties to the hash table
        # This simple example assumes that $Website is not null
        $getTargetResourceResult = @{
            Name = $Website.Name
            Ensure = $ensureResult
            PhysicalPath = $Website.physicalPath
            State = $Website.state
            ID = $Website.id
            ApplicationPool = $Website.applicationPool
            Protocol = $Website.bindings.Collection.protocol
            Binding = $Website.bindings.Collection.bindingInformation
        }

        $getTargetResourceResult
}

Bergantung pada nilai yang ditentukan untuk properti sumber daya dalam skrip konfigurasi, Set-TargetResource harus melakukan salah satu hal berikut:

Membuat situs web baru
Memperbarui situs web yang sudah ada
Menghapus situs web yang sudah ada

Contoh berikut mengilustrasikan langkah-langkah ini:

# The Set-TargetResource function is used to create, delete or configure a website on the target machine.
function Set-TargetResource
{
    [CmdletBinding(SupportsShouldProcess=$true)]
    param
    (
        [ValidateSet("Present", "Absent")]
        [string]$Ensure = "Present",

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Name,

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$PhysicalPath,

        [ValidateSet("Started", "Stopped")]
        [string]$State = "Started",

        [string]$ApplicationPool,

        [string[]]$BindingInfo,

        [string[]]$Protocol
    )

    <#
        If Ensure is set to "Present" and the website specified in the mandatory input parameters
          does not exist, then create it using the specified parameter values
        Else, if Ensure is set to "Present" and the website does exist, then update its properties
          to match the values provided in the non-mandatory parameter values
        Else, if Ensure is set to "Absent" and the website does not exist, then do nothing
        Else, if Ensure is set to "Absent" and the website does exist, then delete the website
    #>
}

Akhirnya, Test-TargetResource fungsi harus mengambil parameter yang sama yang ditetapkan sebagai Get-TargetResource dan Set-TargetResource. Dalam implementasi Test-TargetResourceAnda, periksa status instans sumber daya yang ditentukan dalam parameter kunci. Jika status aktual instans sumber daya tidak cocok dengan nilai yang ditentukan dalam set parameter, kembalikan $false. Jika tidak, kembalikan $true.

Kode berikut mengimplementasikan Test-TargetResource fungsi .

function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [ValidateSet("Present","Absent")]
        [System.String]
        $Ensure,

        [parameter(Mandatory = $true)]
        [System.String]
        $Name,

        [parameter(Mandatory = $true)]
        [System.String]
        $PhysicalPath,

        [ValidateSet("Started","Stopped")]
        [System.String]
        $State,

        [System.String[]]
        $Protocol,

        [System.String[]]
        $BindingData,

        [System.String]
        $ApplicationPool
    )

    # Get the current state
    $currentState = Get-TargetResource -Ensure $Ensure -Name $Name -PhysicalPath $PhysicalPath -State $State -ApplicationPool $ApplicationPool -BindingInfo $BindingInfo -Protocol $Protocol

    # Write-Verbose "Use this cmdlet to deliver information about command processing."

    # Write-Debug "Use this cmdlet to write debug information while troubleshooting."

    # Include logic to
    $result = [System.Boolean]
    # Add logic to test whether the website is present and its status matches the supplied
    # parameter values. If it does, return true. If it does not, return false.
    $result
}

Catatan

Untuk penelusuran kesalahan yang Write-Verbose lebih mudah, gunakan cmdlet dalam implementasi Anda dari tiga fungsi sebelumnya. Cmdlet ini menulis teks ke aliran pesan verbose. Secara default, aliran pesan verbose tidak ditampilkan, tetapi Anda dapat menampilkannya dengan mengubah nilai variabel $VerbosePreference atau dengan menggunakan parameter Verbose di cmdlet DSC = baru.

Membuat manifes modul

Terakhir, gunakan New-ModuleManifest cmdlet untuk menentukan <ResourceName>.psd1 file untuk modul sumber daya kustom Anda. Saat Anda memanggil cmdlet ini, referensikan file modul skrip (.psm1) yang dijelaskan di bagian sebelumnya. Sertakan Get-TargetResource, Set-TargetResource, dan Test-TargetResource dalam daftar fungsi yang akan diekspor. Berikut ini adalah contoh file manifes.

# Module manifest for module 'Demo.IIS.Website'
#
# Generated on: 1/10/2013
#

@{

# Script module or binary module file associated with this manifest.
# RootModule = ''

# Version number of this module.
ModuleVersion = '1.0'

# ID used to uniquely identify this module
GUID = '6AB5ED33-E923-41d8-A3A4-5ADDA2B301DE'

# Author of this module
Author = 'Contoso'

# Company or vendor of this module
CompanyName = 'Contoso'

# Copyright statement for this module
Copyright = 'Contoso. All rights reserved.'

# Description of the functionality provided by this module
Description = 'This Module is used to support the creation and configuration of IIS Websites through Get, Set and Test API on the DSC managed nodes.'

# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '4.0'

# Minimum version of the common language runtime (CLR) required by this module
CLRVersion = '4.0'

# Modules that must be imported into the global environment prior to importing this module
RequiredModules = @("WebAdministration")

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
NestedModules = @("Demo_IISWebsite.psm1")

# Functions to export from this module
FunctionsToExport = @("Get-TargetResource", "Set-TargetResource", "Test-TargetResource")

# Cmdlets to export from this module
#CmdletsToExport = '*'

# HelpInfo URI of this module
# HelpInfoURI = ''
}

Mendukung PsDscRunAsCredential

Catatan

PsDscRunAsCredential didukung di PowerShell 5.0 dan yang lebih baru.

Properti PsDscRunAsCredential dapat digunakan dalam blok sumber daya konfigurasi DSC untuk menentukan bahwa sumber daya harus dijalankan di bawah serangkaian kredensial yang ditentukan. Untuk informasi selengkapnya, lihat Menjalankan DSC dengan kredensial pengguna.

Untuk mengakses konteks pengguna dari dalam sumber daya kustom, Anda dapat menggunakan variabel $PsDscContextotomatis .

Misalnya kode berikut akan menulis konteks pengguna di mana sumber daya berjalan ke aliran output verbose:

if (PsDscContext.RunAsUser) {
    Write-Verbose "User: $PsDscContext.RunAsUser";
}

Me-reboot Node

Jika tindakan yang diambil dalam fungsi Anda Set-TargetResource memerlukan boot ulang, Anda dapat menggunakan bendera global untuk memberi tahu LCM untuk me-reboot Node. Reboot ini terjadi langsung setelah Set-TargetResource fungsi selesai.

Di dalam fungsi Anda Set-TargetResource , tambahkan baris kode berikut.

# Include this line if the resource requires a system reboot.
$global:DSCMachineStatus = 1

Agar LCM dapat me-reboot Node, bendera RebootNodeIfNeeded perlu diatur ke $true. Pengaturan ActionAfterReboot juga harus diatur ke ContinueConfiguration, yang merupakan default. Untuk informasi selengkapnya tentang mengonfigurasi LCM, lihat Mengonfigurasi Configuration Manager Lokal, atau Mengonfigurasi Configuration Manager Lokal (v4).

Bagikan melalui

Menulis sumber daya DSC kustom dengan MOF

Membuat skema MOF

Struktur folder untuk sumber daya MOF

Konten file MOF

Menulis skrip sumber daya

Membuat manifes modul

Mendukung PsDscRunAsCredential

Me-reboot Node

Sumber Daya Tambahan: