创作基于 MOF 的 DSC 资源

2023-11-29

本文介绍如何通过编写架构和开发脚本模块来管理 IIS 网站来创建基于 MOF 的 DSC 资源。

重要

从 DSC 3.0 开始，不支持基于 MOF 的 DSC 资源。如果要编写新的 DSC 资源，并希望它适用于将来的版本，请改为编写基于类的 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)

注意

必须在模块的顶级文件夹下创建名为 DSCResources 的文件夹。每个 DSC 资源的文件夹必须与 DSC 资源同名。

MOF 文件的内容

下面是描述 DSC 资源网站属性的示例 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 资源的名称。在此示例中， FriendlyName 为 Website。
DSC 资源的类必须派生自 OMI_BaseResource。
属性上的类型限定 [Key]符指示此属性唯一标识资源实例。每个 DSC 资源必须至少有一个 [Key] 属性。
限定 [Required] 符指示使用此 DSC 资源时，属性是必需的。
限定 [write] 符指示此属性是可选的。
限定 [read] 符指示属性不能由 DSC 资源设置，并且仅用于报告目的。
值将可分配给属性的值限制为 ValueMap 中定义的值列表。有关详细信息，请参阅 ValueMap 和值限定符。
对于用户可以在系统中添加和Absent删除的 DSC 资源，建议在 DSC 资源中包含名为“确保”的属性和值Present。
将 DSC 资源的架构文件命名为：<classname>.schema.mof，其中 <classname> 是架构定义中关键字 (keyword) 后面的class标识符。

编写脚本模块

基于 MOF 的 DSC 资源的脚本模块实现 DSC 资源的逻辑。在此模块中必须包含三个分别名为 Get-TargetResource、Set-TargetResource 和 Test-TargetResource 的函数。所有三个函数都必须采用与 DSC 资源的架构中定义的属性集相同的参数集。将这三个函数保存在名为的 <ResourceName>.psm1文件中。在以下示例中，函数保存在名为的 Demo_IISWebsite.psm1文件中。

注意

使用 Invoke-DscResource 多次使用相同的属性设置所需状态时，应不会收到任何错误，并且系统应保持与首次使用之后相同的状态。为此，请确保 Get-TargetResource 和 Test-TargetResource 函数保持系统不变，且在具有相同参数值的序列中多次调用 Set-TargetResource 函数始终与调用一次函数相同。

在 Get-TargetResource 函数实现中，使用作为参数提供的 Key 属性值来验证 DSC 资源的指定实例的状态。此函数必须返回一个哈希表，该哈希表将所有 DSC 资源属性列为键，将这些属性的实际值作为相应的值列出。以下代码是一个示例。

# The Get-TargetResource function is used to retrieve the current state of a
# website on the system.
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 hashtable
        # This 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
}

根据用户为 DSC 资源的属性指定的值， Set-TargetResource 必须执行下列操作之一：

添加新网站
更新现有网站
删除现有网站

下面的示例对此进行了演示。

# The Set-TargetResource function is used to add, update, or remove a website
# on the system.
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 doesn't exist, then add 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
    $getParameters = @{
        Ensure          = $Ensure 
        Name            = $Name 
        PhysicalPath    = $PhysicalPath 
        State           = $State 
        ApplicationPool = $ApplicationPool 
        BindingInfo     = $BindingInfo 
        Protocol        = $Protocol
    }
    $currentState = Get-TargetResource @getParameters

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

注意

为方便调试，请在上述三个函数的实现中使用 Write-Verbose cmdlet。此 cmdlet 将文本写入详细消息流。默认情况下，不会显示详细消息流，但可以通过更改变量的值$VerbosePreference或使用带 Invoke-DscResource的 Verbose 参数来显示它。

创建模块清单

最后，使用 New-ModuleManifest cmdlet 为 DSC 资源模块定义 <ResourceName>.psd1 文件。使用上一 .psm1 部分所述的脚本模块 () 文件作为 NestedModules 参数的值。将、 Set-TargetResource和 Test-TargetResource 作为 Get-TargetResourceFunctionsToExport 参数的值包含在内。

$ManifestParameters = @{
    Path              = 'Demo_IISWebsite.psd1'
    NestedModules     = 'Demo_IISWebsite.psm1'
    FunctionsToExport = @(
        'Get-TargetResource'
        'Set-TargetResource'
        'Test-TargetResource'
    )
}
New-ModuleManifest @ManifestParameters

@{

# 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 = 'Create and configure IIS websites with DSC.'

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

# 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'
)

}

重新启动系统

如果函数中 Set-TargetResource 执行的操作需要重新启动，则可以使用全局标志来告知调用方重新启动系统。

在 Set-TargetResource 函数中，添加以下代码行。

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

通过