تأليف مورد DSC المستند إلى MOF

توضح هذه المقالة كيف يمكنك إنشاء مورد DSC يستند إلى MOF عن طريق كتابة مخطط وتطوير وحدة برنامج نصي لإدارة موقع IIS على الويب.

هام

بدءا من DSC 3.0، لا يتم دعم موارد DSC المستندة إلى MOF. إذا كنت تكتب مورد DSC جديدا وتريد أن يعمل مع الإصدارات المستقبلية، فاكتب مورد DSC المستند إلى الفئة بدلا من ذلك.

إنشاء مخطط MOF

يجب أن يحتوي مورد DSC المستند إلى MOF على ملف مخطط (.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

فيما يلي مثال على ملف MOF الذي يصف خصائص موقع ويب لمورد DSC. لاتباع هذا المثال، احفظ هذا المخطط إلى ملف يسمى 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 وقيمة مؤهلات.
• يوصى بتضمين خاصية تسمى ضمان بالقيم Present وفي Absent مورد DSC لموارد DSC التي يمكن للمستخدم إضافتها وإزالتها من نظام.
• قم بتسمية ملف المخطط لمورد DSC الخاص بك كما يلي: <classname>.schema.mof، حيث <classname> هو المعرف الذي يتبع class الكلمة الأساسية في تعريف المخطط الخاص بك.

كتابة وحدة البرنامج النصي

تنفذ وحدة البرنامج النصي لمورد DSC المستندة إلى MOF منطق مورد DSC. في هذه الوحدة النمطية، يجب تضمين ثلاث دالات تسمى Get-TargetResourceو Set-TargetResourceو.Test-TargetResource يجب أن تأخذ جميع الدالات الثلاث مجموعة معلمات مطابقة لمجموعة الخصائص المحددة في مخطط مورد DSC. احفظ هذه الدالات الثلاث في ملف يسمى <ResourceName>.psm1. في المثال التالي، يتم حفظ الدالات في ملف يسمى Demo_IISWebsite.psm1.

ملاحظة

عند استخدام Invoke-DscResource لتعيين الحالة المطلوبة بنفس الخصائص أكثر من مرة، يجب ألا تتلقى أي أخطاء ويجب أن يظل النظام في نفس الحالة كما هو الحال بعد المرة الأولى التي استخدمتها فيها. للقيام بذلك، تأكد من أن Get-TargetResource الدالتين و Test-TargetResource تتركان النظام دون تغيير، وأن استدعاء Set-TargetResource الدالة أكثر من مرة في تسلسل بنفس قيم المعلمة هو دائما نفس استدعاءها مرة واحدة.

في تنفيذ الدالة Get-TargetResource ، استخدم قيم خاصية المفتاح التي يتم توفيرها كمعلمات للتحقق من حالة المثيل المحدد لمورد 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.

إنشاء بيان الوحدة النمطية

وأخيرا، استخدم New-ModuleManifest cmdlet لتعريف <ResourceName>.psd1 ملف لوحدة مورد DSC. استخدم ملف الوحدة النمطية للبرنامج النصي (.psm1) الموضح في القسم السابق كقيمة للمعلمة NestedModules . قم بتضمين Get-TargetResourceو Set-TargetResourceو Test-TargetResource كقيم للمعلمة FunctionsToExport .

$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