MOF を使用したカスタム DSC リソースの記述

[アーティクル]
11/29/2023

適用先:Windows PowerShell 4.0、Windows PowerShell 5.0

この記事では、MOF ファイルで Windows PowerShell Desired State Configuration (DSC) カスタムリソースのスキーマを定義し、そのリソースを Windows PowerShell スクリプトファイルで実装します。このカスタムリソースは、Web サイトを作成および保守するためのものです。

MOF スキーマの作成

スキーマでは、DSC 構成スクリプトによって構成できるリソースのプロパティを定義します。

MOF リソースのフォルダー構造

MOF スキーマを使用して DSC カスタムリソースを実装するには、次のフォルダー構造を作成します。 MOF スキーマは、Demo_IISWebsite.schema.mof ファイルで定義され、リソーススクリプトは Demo_IISWebsite.psm1 で定義されます。必要に応じて、モジュールマニフェスト (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)

Note

最上位のフォルダーに DSCResources という名前のフォルダーを作成し、各リソースのフォルダーにリソースと同じ名前を付ける必要があります。

MOF ファイルの内容

カスタム Web サイトリソースに使用できる MOF ファイルの例を次に示します。この例に従うには、このスキーマをファイルに保存し、ファイルの名前は 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;
};

前のコードについて、次のことに注意してください。

FriendlyName では、DSC 構成スクリプトでこのカスタムリソースを参照するために使用できる名前を定義します。この例では、Website は、組み込みのアーカイブリソースのフレンドリ名 Archive に相当します。
カスタムリソース用に定義するクラスは、OMI_BaseResource から派生する必要があります。
プロパティの型修飾子 [Key] は、このプロパティがリソースインスタンスを一意に識別することを示します。 1 つ以上の [Key] プロパティが必要です。
[Required] 修飾子は、プロパティが必須であることを示します (このリソースを使用する構成スクリプトで値を指定する必要があります)。
[write] 修飾子は、構成スクリプトでカスタムリソースを使用するときにこのプロパティが省略可能であることを示します。 [read] 修飾子は、プロパティが構成では設定できず、報告のみを目的とするとを示します。
Values は、プロパティに割り当てることのできる値を ValueMap で定義されている値の一覧に制限します。詳細については、「ValueMap and Value Qualifiers (ValueMap 修飾子と Value 修飾子)」を参照してください。
組み込みの DSC リソースとの一貫したスタイルを維持する方法として、値 Present と Absent を持つ Ensure というプロパティをリソースに含めることをお勧めします。
カスタムリソースのスキーマファイルには、classname.schema.mof のように名前を付けます。ここで、classname はスキーマ定義内の class キーワードに続く識別子です。

リソーススクリプトの作成

リソーススクリプトでは、リソースのロジックを実装します。このモジュールでは、Get-TargetResource、Set-TargetResource、および Test-TargetResource という 3 つの関数を含める必要があります。 3 つのすべての関数は、リソース用に作成した MOF スキーマで定義されている一連のプロパティと同じパラメーターセットを受け取る必要があります。このドキュメントでは、この一連のプロパティを "リソースプロパティ" と呼びます。これら 3 つの関数をという <ResourceName>.psm1名前のファイルに格納します。次の例では、関数は Demo_IISWebsite.psm1 というファイルに格納されます。

Note

リソースに対して同じ構成スクリプトを複数回実行する場合、エラーが発生せずに、スクリプトを 1 回実行したときと同じ状態にリソースが保たれる必要があります。これを実現するには、Get-TargetResource と Test-TargetResource 関数によってリソースが変更されないようにし、シーケンス内で同じパラメーター値を使用して Set-TargetResource 関数を複数回呼び出した場合に、1 回呼び出した場合と常に同じ結果になるようにします。

Get-TargetResource 関数の実装では、パラメーターとして指定されたキーリソースプロパティ値を使用して、指定されたリソースインスタンスの状態を確認します。この関数は、キーとしてすべてのリソースプロパティを、対応する値としてこれらのプロパティの実際の値を一覧表示するハッシュテーブルを返す必要があります。コードの例は次のとおりです。

# 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
}

構成スクリプトでリソースプロパティに指定されている値に応じて、Set-TargetResource は次のいずれかを実行する必要があります。

新しい Web サイトの作成
既存の Web サイトの更新
既存の Web サイトの削除

次の例を使って説明します。

# 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
    #>
}

最後に、Test-TargetResource 関数は、Get-TargetResource および Set-TargetResource と同じパラメーターセットを受け取る必要があります。 Test-TargetResource の実装で、キーパラメーターで指定されているリソースインスタンスの状態を確認します。リソースインスタンスの実際の状態がパラメーターセットで指定された値と一致しない場合は、 $false を返します。それ以外の場合は、$true を返します。

次のコードでは、Test-TargetResource 関数を実装します。

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
}

Note

簡単にデバッグするには、前の 3 つの関数の実装で Write-Verbose コマンドレットを使用します。このコマンドレットは、テキストを詳細メッセージストリームに書き込みます。既定では、詳細メッセージストリームは表示されません。表示するには、 $VerbosePreference 変数の値を変更するか、DSC コマンドレットで Verbose パラメーターを使用します。

モジュールマニフェストの作成

最後に、New-ModuleManifest コマンドレットを使用して、ご自分のカスタムリソースモジュールに <ResourceName>.psd1 ファイルを定義します。このコマンドレットを呼び出すときに、前のセクションで説明したスクリプトモジュール (.psm1) ファイルを参照します。 Get-TargetResource、Set-TargetResource、および Test-TargetResource をエクスポートする関数の一覧に含めます。マニフェストファイルの例を次に示します。

# 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 = ''
}

PsDscRunAsCredential のサポート

Note

PsDscRunAsCredential は PowerShell 5.0 以降でサポートされています。

PsDscRunAsCredential プロパティを DSC 構成リソースブロックで使用して、指定した資格情報のもとでリソースを実行する必要があることを指定できます。詳細については、「ユーザーの資格情報を指定して DSC を実行する」を参照してください。

カスタムリソース内からユーザーコンテキストにアクセスするには、自動変数 $PsDscContext を使用できます。

たとえば、次のコードは、リソースが詳細出力ストリームに実行しているユーザーコンテキストを記述します。

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

Node を再起動する

Set-TargetResource 関数で行われるアクションに再起動が必要となる場合、グローバルフラグを使用し、Node の再起動を LCM に指示できます。この再起動は、Set-TargetResource 関数の完了直後に行われます。

Set-TargetResource 関数内で次のコード行を追加します。

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

LCM で Node を再起動するには、RebootNodeIfNeeded フラグを $true に設定する必要があります。また、ActionAfterReboot 設定を既定である ContinueConfiguration に設定してください。 LCM の構成方法については、「ローカル構成マネージャーの構成」または「ローカル構成マネージャーの構成 (v4)」を参照してください。

次の方法で共有

MOF を使用したカスタム DSC リソースの記述

MOF スキーマの作成

MOF リソースのフォルダー構造

MOF ファイルの内容

リソーススクリプトの作成

モジュールマニフェストの作成

PsDscRunAsCredential のサポート

Node を再起動する

その他のリソース

次の方法で共有

MOF を使用したカスタム DSC リソースの記述

MOF スキーマの作成

MOF リソースのフォルダー構造

MOF ファイルの内容

リソース スクリプトの作成

モジュール マニフェストの作成

PsDscRunAsCredential のサポート

Node を再起動する

その他のリソース

リソーススクリプトの作成

モジュールマニフェストの作成