قائمة اختيار تأليف مورد DSC

قائمة الاختيار هذه هي قائمة بأفضل الممارسات عند تأليف مورد DSC جديد.

تحتوي الوحدة النمطية على بيان

يجب أن تحتوي الوحدة النمطية التي تحتوي على موارد DSC على ملف بيان الوحدة النمطية (.psd1). يجب أن يسرد إعداد DscResourcesToExport الخاص بالبيان اسم كل مورد DSC.

لن تكون أي موارد DSC مستندة إلى الفئة لا تقوم بتضمينها في إعداد DscResourcesToExport قابلة للاكتشاف باستخدام Get-DscResource cmdlet، ولا يمكن استخدامها مع Invoke-DscResource cmdlet، ولن يحصل مؤلفو تكوين DSC على IntelliSense لموارد DSC هذه عند تأليف تكوين DSC في VS Code.

يحتوي كل مورد DSC يستند إلى MOF على ملف مخطط

تحقق من أن مورد DSC الخاص بك يحتوي على البنية الصحيحة ويحتوي على جميع الملفات المطلوبة. يجب أن يحتوي كل مورد DSC يستند إلى MOF على schema.mof ملف. لن يتم سرد موارد DSC المستندة إلى MOF التي لا تحتوي على ملف مخطط بواسطة Get-DscResource ولن يحصل مؤلفو تكوين DSC على IntelliSense لموارد DSC هذه عند تأليف تكوين DSC في VS Code.

تبدو بنية الدليل لمورد xRemoteFile DSC، وهو جزء من الوحدة النمطية xPSDesiredStateConfiguration كما يلي:

xPSDesiredStateConfiguration
    DSCResources
        MSFT_xRemoteFile
            MSFT_xRemoteFile.psm1
            MSFT_xRemoteFile.schema.mof
    Examples
        xRemoteFile_DownloadFile.ps1
    ResourceDesignerScripts
        GenerateXRemoteFileSchema.ps1
    Tests
        ResourceDesignerTests.ps1
    xPSDesiredStateConfiguration.psd1

تحميل مورد DSC دون أخطاء

يجب تحميل موارد DSC دون أخطاء. للتحقق، قم بتشغيل Import-Module <resource_module> -Force وتأكد من أن الأمر لا يثير أي أخطاء.

مورد DSC غير فعال

يجب أن تكون موارد DSC غير فعالة. يكون مورد DSC غير فعال عندما يمكنك استدعاء الأسلوب Set لمورد DSC عدة مرات بنفس الخصائص وتحقيق نفس النتيجة دائما.

على سبيل المثال، مع تعريف تجزئة المعلمة هذه للحالة المطلوبة لقيمة مفتاح التسجيل باستخدام Registry مورد DSC من الوحدة النمطية PSDscResources :

$DscParameters = @{
    Name       = 'Registry'
    ModuleName = 'PSDscResources'
    Property   = @{
        Key       = 'HKEY_CURRENT_USER\DscExample'
        Ensure    = 'Present'
        Force     = $true
        ValueName = 'Test'
        ValueData = 'Example'
        ValueType = 'String'
    }
}

في المرة الأولى التي DscExample تستدعي Invoke-DscResource -Method Set @DscParametersفيها ، يجب أن يظهر مفتاح التسجيل في الخلية HKEY_CURRENT_USER مع تعيين قيمة الاختبار إلى Example. يجب ألا تغير استدعاءات المستقبل حالة النظام.

للتأكد من أن المورد غير فعال، يمكنك اختبار المورد مباشرة أو باستخدام Invoke-DscResource.

لاختبار مورد DSC المستند إلى MOF مباشرة:

1. قم بتشغيل دالة مورد Set-TargetResource DSC.
2. افحص حالة النظام للتحقق من أنها في الحالة المطلوبة دون إعدادات غير مرغوب فيها.
3. قم بتشغيل الدالة 'Set-TargetResource' لمورد DSC مرة أخرى. لا ينبغي أن يثير أي أخطاء.
4. كرر الخطوات من 2 إلى 3 حتى تكون راضيا عن أن الاتصال Set-TargetResource يعين الحالة المطلوبة فقط كما هو متوقع ودون أي أخطاء.

لاختبار مورد DSC المستند إلى الفئة مباشرة:

1. أنشئ مثيلا جديدا لفئة مورد DSC واحفظه في متغير ككائن.
2. قم بتعيين قيمة كل خاصية إلى الحالة المطلوبة على العنصر .
3. استدعاء الأسلوب Set على الكائن .
4. افحص حالة النظام للتحقق من أنها في الحالة المطلوبة دون إعدادات غير مرغوب فيها.
5. استدعاء الأسلوب Set على الكائن مرة أخرى. لا ينبغي أن يثير أي أخطاء.
6. كرر الخطوات من 4 إلى 5 حتى تشعر بالرضا عن أن استدعاء الأسلوب Set يعين الحالة المطلوبة فقط كما هو متوقع ودون أي أخطاء.

لاختبار مورد DSC باستخدام Invoke-DscResource:

1. قم بتشغيل Invoke-DscResource باستخدام أسلوب Set .
2. افحص حالة النظام للتحقق من أنها في الحالة المطلوبة دون إعدادات غير مرغوب فيها.
3. قم بتشغيل Invoke-DscResource باستخدام أسلوب Set .
4. كرر الخطوات من 2 إلى 3 حتى تشعر بالرضا عن أن الاتصال Invoke-DscResource بالأسلوب Set يعين الحالة المطلوبة فقط كما هو متوقع ودون أي أخطاء.

اختبار سيناريو تعديل المستخدم

يجب أن تتصرف موارد DSC بشكل متوقع حتى عندما يغير المستخدمون حالة النظام يدويا خارج DSC. فيما يلي الخطوات التي يجب عليك اتخاذها للتحقق من سلوك مورد DSC عندما يقوم المستخدم بتعديل النظام:

1. ابدأ بالنظام غير في الحالة المطلوبة.
2. تشغيل Invoke-DscResource -Method Set باستخدام المورد الخاص بك
3. التحقق من Invoke-DscResource -Method Test الإرجاع $true
4. تعيين العنصر الذي تم تكوينه ليكون خارج الحالة المطلوبة
5. التحقق من Invoke-DscResource -Method Test الإرجاع $false

فيما يلي مثال أكثر واقعية Registry باستخدام مورد DSC:

1. ابدأ بمفتاح التسجيل ليس في الحالة المطلوبة.
2. قم بتشغيل Invoke-DscResource -Method Test مع خصائص الحالة المطلوبة وتأكد من أن خاصية InDesiredState للنتيجة هي $false.
3. قم بتشغيل Invoke-DscResource -Method Get بالخصائص المطلوبة وتأكد من أن الحالة التي تم الإبلاغ عنها لا تتطابق مع خصائص الحالة المطلوبة.
4. قم بتشغيل Invoke-DscResource -Method Set مع خصائص الحالة المطلوبة وتأكد من عدم حدوث خطأ.
5. قم بتشغيل Invoke-DscResource -Method Test مرة أخرى وتأكد من أن خاصية InDesiredState للنتيجة صحيحة الآن.
6. قم بتشغيل Invoke-DscResource -Method Get مرة أخرى وتأكد من تطابق الحالة التي تم الإبلاغ عنها مع خصائص الحالة المطلوبة.
7. قم بتعيين قيمة المفتاح بحيث لا يكون في الحالة المطلوبة.
8. قم بتشغيل Invoke-DscResource -Method Get مرة أخرى للتحقق من الحالة المعدلة.
9. قم بتشغيل Invoke-DscResource -Method Test مرة أخرى وتحقق من إرجاع false.

استدعاء وظائف مورد DSC وأساليبه مباشرة

تأكد من اختبار *-TargetResource الدالات (لموارد DSC الأساسية MOF) وأساليب Get و Set و Test (لموارد DSC المستندة إلى الفئة) عن طريق استدعائها مباشرة والتحقق من أنها تعمل كما هو متوقع.

اختبار التوافق على كل نظام أساسي مدعوم

يجب أن تعمل موارد DSC على أي نظام أساسي يتم دعم DSC عليه. إذا لم يعمل مورد DSC الخاص بك على بعض هذه الأنظمة الأساسية حسب التصميم، فسترجع رسالة خطأ معينة. تأكد من أن مورد DSC الخاص بك يتحقق مما إذا كانت أوامر cmdlets التي تتصل بها موجودة على جهاز معين.

ملاحظة

تتمثل إحدى فجوات الاختبار الشائعة في التحقق من مورد DSC فقط على إصدارات الخادم من Windows. غالبا ما يتم تصميم موارد DSC أيضا للعمل على وحدات SKU للعميل. تأكد من اختبار سلوك وحدات SKU للعميل أو خطأ إذا لم تكن مدعومة من قبل مورد DSC الخاص بك.

يسرد Get-DSCResource مورد DSC

عند تثبيت الوحدة النمطية الخاصة بك، Get-DscResource يجب أن تتضمن مورد DSC الخاص بك في إخراج cmdlet.

تحتوي الوحدة النمطية على أمثلة

إنشاء أمثلة جودة لمساعدة المستخدمين على فهم كيفية استخدام موارد DSC الخاصة بك. هذا أمر بالغ الأهمية، حيث يتعامل المستخدمون غالبا مع نموذج التعليمات البرمجية كوثائق.

أولا، حدد الأمثلة التي يجب تضمينها مع الوحدة النمطية الخاصة بك. يجب عليك على الأقل تغطية أهم حالات الاستخدام لموارد DSC الخاصة بك.

إذا كانت الوحدة النمطية تحتوي على العديد من موارد DSC التي تحتاج إلى العمل معا لسيناريو شامل، اكتب المثال الأساسي من طرف إلى طرف أولا.

اكتب أمثلتك الأولية كمثال أساسي وقصير قدر الإمكان. إظهار كيفية بدء استخدام موارد DSC في مجموعات صغيرة قابلة للإدارة، مثل إنشاء VHD جديد. اكتب أمثلة لاحقة للبناء على أمثلة سابقة (مثل إنشاء جهاز ظاهري من VHD)، وإظهار وظائف متقدمة (مثل إنشاء جهاز ظاهري بذاكرة ديناميكية).

لكل مثال:

• اكتب وصفا مختصرا يشرح الغرض منه وكيفية استخدام أي معلمات.
• تحقق من تشغيل كل مثال دون أخطاء أو تحذيرات غير مقصودة وفرض الحالة المطلوبة.

رسائل الخطأ مفهومة وتساعد المستخدمين على حل المشكلات

يجب أن تكون رسائل الخطأ الجيدة:

• موجود: بدون رسالة خطأ، لن يعرف المستخدم حتى حدوث خطأ ما.
• كن قابلا للقراءة من قبل الإنسان: لا توجد رموز خطأ غامضة.
• كن دقيقا: وصف المشكلة بالضبط.
• كن بناء: قدم المشورة حول كيفية إصلاح المشكلة.
• كن مهذبا: لا تلوم المستخدم أو تجعله يشعر بالسوء.

تأكد من التحقق من الأخطاء في السيناريوهات الشاملة لأنها قد تختلف عن تلك التي تم إرجاعها عند تشغيل الدالات (لموارد DSC المستندة إلى MOF) أو الأساليب (لموارد DSC المستندة إلى الفئة) مباشرة.

لا يحتوي تنفيذ مورد DSC على مسارات مشفرة

تأكد من عدم وجود مسارات مشفرة في أي تنفيذ لمورد DSC، خاصة إذا كانت تفترض لغة، مثل en-US. استخدم متغيرات بيئة النظام عندما يكون ذلك ممكنا.

على سبيل المثال، بدلًا من:

$tempPath = "C:\Users\kkaczma\AppData\Local\Temp\MyResource"
$programFilesPath = "C:\Program Files (x86)"

كتابه:

$tempPath = Join-Path $env:temp "MyResource"
$programFilesPath = ${env:ProgramFiles(x86)}

لا يحتوي تنفيذ مورد DSC على معلومات المستخدم

يجب ألا تتضمن موارد DSC معلومات تعريف شخصية في التعليمات البرمجية. تأكد من عدم وجود أسماء بريد إلكتروني أو معلومات حساب أو أسماء أشخاص في التعليمات البرمجية.

تم اختباره باستخدام بيانات اعتماد صالحة وغير صالحة

إذا كان مورد DSC يأخذ بيانات اعتماد كمعلمة:

• تحقق من أن مورد DSC يتصرف كما هو متوقع عندما لا يكون للحساب حق الوصول.
• تحقق من أن مورد DSC يعمل مع بيانات اعتماد محددة ل Get و Set و Test.
• إذا كان مورد DSC يصل إلى المشاركات، فاختر جميع المتغيرات التي تحتاج إلى دعمها، مثل:
  • مشاركات Windows القياسية
  • مشاركات DFS
  • مشاركات SAMBA (إذا كنت ترغب في دعم Linux)

لا يتطلب مورد DSC إدخالا تفاعليا

يجب ألا تطالب موارد DSC أبدا بإدخالها. بدلا من ذلك، يجب أن تكون جميع القيم المطلوبة خصائص لمورد DSC. على سبيل المثال، بدلا من مطالبة المستخدم ب Get-Credential، أضف خاصية Credential إلى مورد DSC الخاص بك.

اختبار شامل

تحتوي قائمة الاختيار هذه على عناصر مهمة ليتم اختبارها وغالبا ما يتم تفويتها. يجب عليك أيضا كتابة حالات اختبار وظيفية ومن طرف إلى طرف لمورد DSC الخاص بك لضمان السلوكيات المتوقعة. تأكد من استخدام حالات الاختبار السالبة واختبار الإدخال غير الصالح.