PowerShell / الأساسي: النسخ والكائنات والأنواع والدوال / الدرس 5
تصميم دوال بعقود خرج دقيقة
أعلن المعاملات وتحقق من المدخل واضبط النطاق وامنع الخرج العرضي من إفساد النتيجة.
في هذه الصفحة
أهداف الدرس
- استخدام بيانات المعامل والتحقق واجهة عامة.
- شرح خرج النجاح مقابل تحكم return.
- فصل المحلي ونطاق البرنامج وتوقع المستدعي.
معاملات الدالة مخطط بيانات
تعلن الدالة النوع والمطلوب والتحقق والمجموعات والافتراضي وتضيف CmdletBinding عقداً أوسع. لا يثبت التحويل صلاحية المجال أو المسار. حدد الافتراض وارفض التعارض قبل الأثر؛ الاسم والخرج واجهة للمستدعي. لا تخف المشوه بموضع أو بقية وسائط عامة. وإذا قبل الرابط تمثيلاً عددياً، فلا يعني ذلك أن العملية تسمح به؛ فقد يبقى خارج المجال أو يمثل مورداً لا يملك المستدعي حق تغييره.
قد يصير كل ناتج نجاح غير ملتقط خرج دالة
تنتج أي عبارة على تيار النجاح، ولا تمحو return ما سبقها. قد تضيف رسالة أو قيمة طريقة كائناً فيتغير العدد. استخدم التشخيص المناسب واكبت غير المعني عمداً وافحص الجسم قبل لوم الأنبوب. سم النوع والخصائص والعدد والترتيب لا القيم المعتادة فقط. ويشمل ذلك قيمة ترجعها طريقة جمع عناصر مثلاً أو عبارة عرض وضعت للتشخيص؛ فقد تظهر بين بيانات الدالة حتى لو انتهت بإعادة السجل الصحيح.
يضبط النطاق الرؤية لا العزل المعاملي
تؤثر النطاقات في الحل والتعديل، وينفذ dot-sourcing بالمجال الحالي لا بيانات. لا يعكس نطاق أو وحدة أثر ملف أو خدمة عند الفشل. فضل المدخل والخرج على العام وأعد أو وثق التفضيل والموقع والمشترك. اختبر التكرار ومستدعياً آخر لا جلسة ترث ما يكمل دالة ناقصة. كما أن فشل الدالة لا يعيد تلقائياً محتوى كائن مشترك عدلته أو أثراً خارجياً أحدثته، مهما كانت حدود المتغيرات المحلية واضحة.
إظهار نتيجة الدالة المصطنعة
يتحقق المثال من وضع صغير وينتج سجلاً واحداً دون مضيف أو أثر. الحقول بيانات لا جدول، ويبقى غير منفذ. ليفحص اختبار المحرك النوع والعدد والباطل لا العرض؛ وليكشف إضافة طريقة أو مساعد تلوث النجاح قبل التسلسل. ويجب أن يحمي الاختبار النوع والعدد عند إضافة مساعد جديد، لأن وجود السجل النهائي الصحيح لا يعوض ظهور كائن زائد قبله.
function New-LabRecord {
[CmdletBinding()]
param(
[ValidateSet('Review', 'Archive')]
[string]$Mode = 'Review'
)
[pscustomobject]@{ Mode = $Mode; Enabled = $true; Count = 2 }
}
New-LabRecord -Mode Review
المقصود كائن واحد بالخصائص دون تحقق تنفيذ فلا ندعي الربط أو التنسيق.
فحص قصد المدخل والنتيجة ثم تمييز المحرك
يفحص المثبت المفردات والمخطط لا ValidateSet أو النطاق أو الربط. أظهر الرفض والخرج الثابت واختبر لاحقاً الأثر والتفضيل والمتداخل والخطأ. يتيح الحد مراجعة كل طبقة دون فعل إداري؛ ننفذ النموذج فقط وتبقى المؤثرة والبعيدة توضيحية. ويجب أن يذكر التقرير أن شروط النموذج لا تختبر سمات PowerShell أو معاملاتها المشتركة، وأن اختبار الحالة والاستثناء والنطاق سيحتاج المحرك المدعوم.
def make_record(mode):
if mode not in {'Review', 'Archive'}:
raise ValueError('mode')
return {'Mode': mode, 'Enabled': True, 'Count': 2}
record = make_record('Review')
assert set(record) == {'Mode', 'Enabled', 'Count'}
print(record['Mode'] + ':' + str(record['Count']))Review:2يفحص Python فقط دون PowerShell أو وحدة أو ربط أو مضيف.
الأخطاء الشائعة وإصلاحها
تحول رسالة تقدم لبيانات معادة
- لماذا يحدث؟
- كتب التشخيص بالنجاح.
- كيف تصلحه؟
- استخدم القناة وافحص كل الكائنات.
- كيف تتجنب تكراره؟
- تحقق من النوع والعدد.
توقع إزالة return للخرج السابق
- لماذا يحدث؟
- اختلط التحكم بالخرج المتراكم.
- كيف تصلحه؟
- أزل العرضي بمصدره.
- كيف تتجنب تكراره؟
- اختبر المساعد قبل العودة.
اعتبار حد النطاق رجوعاً
- لماذا يحدث؟
- اختلطت الرؤية بالعزل.
- كيف تصلحه؟
- صمم التعافي للأثر.
- كيف تتجنب تكراره؟
- وثق الحالة مستقلة.
اختبر فهمك
1. تكتب دالة نصاً ثم تعيد سجلاً. ماذا يتوقع المستدعي؟
اعرض الحل المشروح
قد يصل الاثنان ولا تسحب return النص؛ انقله للتشخيص أو اكبحه واختبر النوع والعدد.
2. لماذا يحتاج المعامل النوعي تحقق مجال؟
اعرض الحل المشروح
يحدد التحويل التمثيل لا الصحة أو السلطة؛ قد يكون العدد سالباً أو الوضع غير مدعوم فصرح القيود.
أهم ما تعلمته
- أعلن المخطط وكل خرج نجاح.
- افصل النطاق والتشخيص وتعافي الأثر.