MOF를 사용하여 사용자 지정 DSC 리소스 작성Writing a custom DSC resource with MOF

적용 대상: Windows PowerShell 4.0, Windows PowerShell 5.0Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

이 항목에서는 MOF 파일에 Windows PowerShell DSC(필요한 상태 구성) 사용자 지정 리소스에 대한 스키마를 정의하고 Windows PowerShell 스크립트 파일에 리소스를 구현합니다.In this topic, we will define the schema for a Windows PowerShell Desired State Configuration (DSC) custom resource in a MOF file, and implement the resource in a Windows PowerShell script file. 이 사용자 지정 리소스는 웹 사이트를 만들고 유지 관리하기 위한 것입니다.This custom resource is for creating and maintaining a web site.

MOF 스키마 만들기Creating the MOF schema

스키마는 DSC 구성 스크립트를 통해 구성할 수 있는 리소스의 속성을 정의합니다.The schema defines the properties of your resource that can be configured by a DSC configuration script.

MOF 리소스에 대한 폴더 구조Folder structure for a MOF resource

MOF 스키마를 사용하여 DSC 사용자 지정 리소스를 구현하려면 다음 폴더 구조를 만듭니다.To implement a DSC custom resource with a MOF schema, create the following folder structure. MOF 스키마는 Demo_IISWebsite.schema.mof 파일에 정의되며, 리소스 스크립트는 Demo_IISWebsite.psm1에 정의됩니다.The MOF schema is defined in the file Demo_IISWebsite.schema.mof, and the resource script is defined in Demo_IISWebsite.psm1. 필요에 따라 모듈 매니페스트(psd1) 파일을 만들 수 있습니다.Optionally, you can create a module manifest (psd1) file.

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

최상위 폴더 아래에 DSCResources라는 폴더를 만들어야 하며, 각 리소스에 대한 폴더의 이름은 리소스의 이름과 동일해야 합니다.Note that it is necessary to create a folder named DSCResources under the top-level folder, and that the folder for each resource must have the same name as the resource.

MOF 파일의 내용The contents of the MOF file

다음은 사용자 지정 웹 사이트 리소스에 사용할 수 있는 MOF 파일의 예입니다.Following is an example MOF file that can be used for a custom website resource. 이 예제를 수행하려면 이 스키마를 파일에 저장하고 Demo_IISWebsite.schema.mof 파일을 호출합니다.To follow this example, save this schema to a file, and call the 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;
};

앞의 코드에 대해 다음 사항에 주목합니다.Note the following about the previous code:

  • FriendlyName은 DSC 구성 스크립트에서 이 사용자 지정 리소스를 참조하는 데 사용할 수 있는 이름을 정의합니다.FriendlyName defines the name you can use to refer to this custom resource in DSC configuration scripts. 이 예제에서 Website는 기본 제공 보관 리소스에 대한 이름인 Archive와 동등합니다.In this example, Website is equivalent to the friendly name Archive for the built-in Archive resource.
  • 사용자 지정 리소스에 대해 정의하는 클래스는 OMI_BaseResource에서 파생해야 합니다.The class you define for your custom resource must derive from OMI_BaseResource.
  • 속성의 형식 한정자 [Key]는 이 속성이 리소스 인스턴스를 고유하게 식별할 것임을 나타냅니다.The type qualifier, [Key], on a property indicates that this property will uniquely identify the resource instance. 하나 이상의 [Key] 속성이 필요합니다.At least one [Key] property is required.
  • [Required] 한정자는 이 속성이 필수임을 나타냅니다(이 리소스를 사용하는 모든 구성 스크립트에서 값을 지정해야 함).The [Required] qualifier indicates that the property is required (a value must be specified in any configuration script that uses this resource).
  • [write] 한정자는 구성 스크립트에서 사용자 지정 리소스를 사용할 때 이 속성이 선택 사항임을 나타냅니다.The [write] qualifier indicates that this property is optional when using the custom resource in a configuration script. [read] 한정자는 속성이 구성으로 설정되지 않으며, 보고만을 위한 것임을 나타냅니다.The [read] qualifier indicates that a property cannot be set by a configuration, and is for reporting purposes only.
  • Values는 속성에 지정된 할당할 수 있는 값을 ValueMap에 정의된 값 목록으로 제한합니다.Values restricts the values that can be assigned to the property to the list of values defined in ValueMap. 자세한 내용은 ValueMap and Value Qualifiers(ValueMap 및 값 한정자)를 참조합니다.For more information, see ValueMap and Value Qualifiers.
  • 기본 제공 DSC 리소스와 일관된 스타일을 유지하는 방법으로서, 리소스에 PresentAbsent 값을 갖는 Ensure라는 속성을 포함하는 것이 좋습니다.Including a property called Ensure with values Present and Absent in your resource is recommended as a way to maintain a consistent style with built-in DSC resources.
  • 사용자 지정 리소스에 대한 스키마 파일의 이름을 classname.schema.mof와 같이 지정합니다. 여기서 classname는 스키마 정의에서 class 키워드의 뒤에 오는 식별자입니다.Name the schema file for your custom resource as follows: classname.schema.mof, where classname is the identifier that follows the class keyword in your schema definition.

리소스 스크립트 작성Writing the resource script

리소스 스크립트는 리소스의 논리를 구현합니다.The resource script implements the logic of the resource. 이 모듈에서는 Get-TargetResource, Set-TargetResourceTest-TargetResource라는 세 가지 함수를 포함해야 합니다.In this module, you must include three functions called Get-TargetResource, Set-TargetResource, and Test-TargetResource. 세 함수는 모두 리소스용으로 만든 MOF 스키마에 정의된 속성 집합과 동일한 매개 변수 집합을 사용해야 합니다.All three functions must take a parameter set that is identical to the set of properties defined in the MOF schema that you created for your resource. 이 문서에서는 이 속성 집합을 "리소스 속성"이라고 합니다.In this document, this set of properties is referred to as the “resource properties.” 이 세 개의 함수를 .psm1이라는 파일에 저장합니다.Store these three functions in a file called .psm1. 다음 예제에서는 이 함수들이 Demo_IISWebsite.psm1이라는 파일에 저장됩니다.In the following example, the functions are stored in a file called Demo_IISWebsite.psm1.

참고: 리소스에 대해 동일한 구성 스크립트를 두 번 이상 실행해도 오류가 표시되지 않으며, 리소스는 스크립트를 한 번 실행하는 것과 동일한 상태로 유지되어야 합니다.Note: When you run the same configuration script on your resource more than once, you should receive no errors and the resource should remain in the same state as running the script once. 이 작업을 해내려면 Get-TargetResourceTest-TargetResource 함수가 리소스를 변경하지 않고 그대로 두고, Set-TargetResource 함수를 동일한 매개 변수 값으로 순서대로 두 번 이상 호출하는 것은 한 번 호출하는 것과 항상 동일한지 확인합니다.To accomplish this, ensure that your Get-TargetResource and Test-TargetResource functions leave the resource unchanged, and that invoking the Set-TargetResource function more than once in a sequence with the same parameter values is always equivalent to invoking it once.

Get-TargetResource 함수 구현에서는 매개 변수로 제공되는 주요 리소스 속성 값을 사용하여 지정된 리소스 인스턴스 상태를 확인합니다.In the Get-TargetResource function implementation, use the key resource property values that are provided as parameters to check the status of the specified resource instance. 이 함수는 모든 리소스 속성을 키로 나열하고, 이러한 속성의 실제 값을 그에 대한 해당 값으로 나열하는 해시 테이블을 반환해야 합니다.This function must return a hash table that lists all the resource properties as keys and the actual values of these properties as the corresponding values. 다음 코드에 예가 나와 있습니다.The following code provides an example.

# 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는 다음 중 하나를 수행해야 합니다.Depending on the values that are specified for the resource properties in the configuration script, the Set-TargetResource must do one of the following:

  • 새 웹 사이트 만들기Create a new website
  • 기존 웹 사이트 업데이트Update an existing website
  • 기존 웹 사이트 삭제Delete an existing website

다음 예제에서는 이것을 보여 줍니다.The following example illustrates this.

# 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-TargetResourceSet-TargetResource와 동일한 매개 변수 집합을 사용해야 합니다.Finally, the Test-TargetResource function must take the same parameter set as Get-TargetResource and Set-TargetResource. Test-TargetResource의 구현에서, 키 매개 변수에 지정된 리소스 인스턴스의 상태를 확인하세요.In your implementation of Test-TargetResource, check the status of the resource instance that is specified in the key parameters. 리소스 인스턴스의 실제 상태가 매개 변수 집합에 지정된 값과 일치하지 않는 경우 $false를 반환하세요.If the actual status of the resource instance does not match the values specified in the parameter set, return $false. 그렇지 않으면 $true를 반환하세요.Otherwise, return $true.

다음 코드는 Test-TargetResource 함수를 구현합니다.The following code implements the Test-TargetResource function.

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
)

#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 mathes the supplied parameter values. If it does, return true. If it does not, return false.
$result
}

참고: 보다 쉽게 디버그하려면, 앞의 세 함수에 대한 구현에서 Write-Verbose cmdlet을 사용하세요.Note: For easier debugging, use the Write-Verbose cmdlet in your implementation of the previous three functions.

이 cmdlet은 자세한 정보 메시지 스트림에 텍스트를 씁니다.This cmdlet writes text to the verbose message stream. 자세한 정보 메시지 스트림은 기본적으로 표시되지 않지만 $VerbosePreference 변수 값을 변경하거나 DSC cmdlets = new에 Verbose 매개 변수를 사용하여 표시할 수 있습니다.By default, the verbose message stream is not displayed, but you can display it by changing the value of the $VerbosePreference variable or by using the Verbose parameter in the DSC cmdlets = new.

모듈 매니페스트 만들기Creating the module manifest

마지막으로, New-ModuleManifest cmdlet을 사용하여 사용자 지정 리소스 모듈에 대한 .psd1 파일을 정의하세요.Finally, use the New-ModuleManifest cmdlet to define a .psd1 file for your custom resource module. 이 cmdlet을 호출할 때에는 이전 섹션에서 설명한 스크립트 모듈(.psm1) 파일을 참조합니다.When you invoke this cmdlet, reference the script module (.psm1) file described in the previous section. 내보낼 함수 목록에 Get-TargetResource, Set-TargetResourceTest-TargetResource를 포함하세요.Include Get-TargetResource, Set-TargetResource, and Test-TargetResource in the list of functions to export. 다음은 매니페스트 파일의 예입니다.Following is an example manifest file.

# 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 지원Supporting PsDscRunAsCredential

참고: PsDscRunAsCredential은 PowerShell 5.0이상에서 지원됩니다.Note: PsDscRunAsCredential is supported in PowerShell 5.0 and later.

PsDscRunAsCredential 속성을 DSC 구성 리소스 블록에서 사용하면 지정된 자격 증명 집합으로 리소스를 실행해야 함을 지정할 수 있습니다.The PsDscRunAsCredential property can be used in DSC configurations resource block to specify that the resource should be run under a specified set of credentials. 자세한 내용은 사용자 자격 증명을 사용하여 DSC 실행을 참조하세요.For more information, see Running DSC with user credentials.

사용자 지정 리소스 내에서 사용자 컨텍스트에 액세스하려는 경우 $PsDscContext 자동 변수를 사용할 수 있습니다.To access the user context from within a custom resource, you can use the automatic variable $PsDscContext.

예를 들어 다음 코드는 리소스가 자세한 정보 출력 스트림으로 실행되는 사용자 컨텍스트를 작성합니다.For example the following code would write the user context under which the resource is running to the verbose output stream:

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