قائمة اختيار تأليف مورد 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 مباشرة:
- قم بتشغيل دالة مورد
Set-TargetResource
DSC. - افحص حالة النظام للتحقق من أنها في الحالة المطلوبة دون إعدادات غير مرغوب فيها.
- قم بتشغيل الدالة 'Set-TargetResource' لمورد DSC مرة أخرى. لا ينبغي أن يثير أي أخطاء.
- كرر الخطوات من 2 إلى 3 حتى تكون راضيا عن أن الاتصال
Set-TargetResource
يعين الحالة المطلوبة فقط كما هو متوقع ودون أي أخطاء.
لاختبار مورد DSC المستند إلى الفئة مباشرة:
- أنشئ مثيلا جديدا لفئة مورد DSC واحفظه في متغير ككائن.
- قم بتعيين قيمة كل خاصية إلى الحالة المطلوبة على العنصر .
- استدعاء الأسلوب Set على الكائن .
- افحص حالة النظام للتحقق من أنها في الحالة المطلوبة دون إعدادات غير مرغوب فيها.
- استدعاء الأسلوب Set على الكائن مرة أخرى. لا ينبغي أن يثير أي أخطاء.
- كرر الخطوات من 4 إلى 5 حتى تشعر بالرضا عن أن استدعاء الأسلوب Set يعين الحالة المطلوبة فقط كما هو متوقع ودون أي أخطاء.
لاختبار مورد DSC باستخدام Invoke-DscResource
:
- قم بتشغيل
Invoke-DscResource
باستخدام أسلوب Set . - افحص حالة النظام للتحقق من أنها في الحالة المطلوبة دون إعدادات غير مرغوب فيها.
- قم بتشغيل
Invoke-DscResource
باستخدام أسلوب Set . - كرر الخطوات من 2 إلى 3 حتى تشعر بالرضا عن أن الاتصال
Invoke-DscResource
بالأسلوب Set يعين الحالة المطلوبة فقط كما هو متوقع ودون أي أخطاء.
اختبار سيناريو تعديل المستخدم
يجب أن تتصرف موارد DSC بشكل متوقع حتى عندما يغير المستخدمون حالة النظام يدويا خارج DSC. فيما يلي الخطوات التي يجب عليك اتخاذها للتحقق من سلوك مورد DSC عندما يقوم المستخدم بتعديل النظام:
- ابدأ بالنظام غير في الحالة المطلوبة.
- تشغيل
Invoke-DscResource -Method Set
باستخدام المورد الخاص بك - التحقق من
Invoke-DscResource -Method Test
الإرجاع$true
- تعيين العنصر الذي تم تكوينه ليكون خارج الحالة المطلوبة
- التحقق من
Invoke-DscResource -Method Test
الإرجاع$false
فيما يلي مثال أكثر واقعية Registry
باستخدام مورد DSC:
- ابدأ بمفتاح التسجيل ليس في الحالة المطلوبة.
- قم بتشغيل
Invoke-DscResource -Method Test
مع خصائص الحالة المطلوبة وتأكد من أن خاصية InDesiredState للنتيجة هي$false
. - قم بتشغيل
Invoke-DscResource -Method Get
بالخصائص المطلوبة وتأكد من أن الحالة التي تم الإبلاغ عنها لا تتطابق مع خصائص الحالة المطلوبة. - قم بتشغيل
Invoke-DscResource -Method Set
مع خصائص الحالة المطلوبة وتأكد من عدم حدوث خطأ. - قم بتشغيل
Invoke-DscResource -Method Test
مرة أخرى وتأكد من أن خاصية InDesiredState للنتيجة صحيحة الآن. - قم بتشغيل
Invoke-DscResource -Method Get
مرة أخرى وتأكد من تطابق الحالة التي تم الإبلاغ عنها مع خصائص الحالة المطلوبة. - قم بتعيين قيمة المفتاح بحيث لا يكون في الحالة المطلوبة.
- قم بتشغيل
Invoke-DscResource -Method Get
مرة أخرى للتحقق من الحالة المعدلة. - قم بتشغيل
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 الخاص بك لضمان السلوكيات المتوقعة. تأكد من استخدام حالات الاختبار السالبة واختبار الإدخال غير الصالح.