معلمات وظائف PowerShell: دليل عملي لبناء وظائف أفضل

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

في هذا البرنامج التعليمي، سنوسع في وظيفة تسجيل بسيطة من خلال إضافة معلمات للتحكم في رسالة السجل، مسار الملف، والتحقق.

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

تحديد وظيفة الكتابة الأساسية Write-Log

سنبدأ بوظيفة أساسية تأخذ معلمة واحدة لرسالة السجل وتلصقها في ملف سجل قياسي مع الطابع الزمني.

في هذا المثال:

• معلمة $LogMessage محددة كمطلوبة، لذلك باورشل يطلبها إذا لم تقدم قيمة.
• يتضمن كل إدخال سجل طابع زمني بتنسيق HH:mm:ss.

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path "C:\Scripts\software_installer.log" -Value "$timeGenerated - $LogMessage"
}

اختبار وظيفة Write-Log

الآن بعد أن لدينا الوظيفة Write-Log بنية أساسية وتقبل معلمات، حان الوقت لاختبار وظائفها. يساعد الاختبار في التأكد من أن كل جزء من الوظيفة، من الإعدادات الافتراضية إلى المدخلات المخصصة، يعمل كما هو متوقع ويتعامل برشاقة مع الأخطاء.

اختبر وظيفة Write-Log عن طريق استدعائها برسالة مخصصة:

Write-Log -LogMessage 'Testing a new log message'

تضيف هذه الأمر إدخالًا جديدًا بطابع زمني إلى ملف السجل (C:\Scripts\software_installer.log).

بعض الأشياء التي يجب ملاحظتها حول وظيفة Write-Log:

Standardized Information Logging	By setting a default path for the log file, you don’t have to specify the file name every time you call the function. This standardizes all log information to a single file, keeping your logs organized.
عملية تسجيل مبسطة	تقوم الوظيفة بتجاهل تفاصيل مثل الحصول على التاريخ والوقت الحالي باستخدام Get-Date وإلحاق المحتوى باستخدام Add-Content. كمستخدم للوظيفة، يمكنك التركيز فقط على كتابة الرسائل إلى ملف السجل دون الحاجة إلى تذكر هذه التفاصيل.
تحسين قراءة الشفرة	تسجل الوظيفة بوضوح الرسائل إلى ملف سجل معين، مما يجعل الغرض واضحًا أنه تسجيل بدلاً من كتابة ببساطة إلى ملف نصي عام. يجعل هذا الشيفرة أكثر وضوحًا ذاتيًا وأسهل فهمًا بلمح البصر.

بفضل هذه التحسينات، تساعد وظيفة Write-Log في تبسيط مهام تسجيل السجل، مما يجعل النصوص أكثر نظافة وصيانة.

يمكنك عرض أحدث رسالة في السجل عن طريق التحقق من محتويات ملف السجل:

Get-Content -Path "C:\Scripts\software_installer.log"

تعرض هذه الأمر جميع الإدخالات في السجل، بما في ذلك آخر رسالة لك مع الطابع الزمني.

ولكن ربما قمت بالاتصال بـ Write-Log عن طريق الخطأ بدون معلمة LogMessage:

Write-Log

ستلاحظ أنه، بسبب أن LogMessage مطلوبة، ستمنع PowerShell الوظيفة من العمل. ولكن إذا لم تكن LogMessage إجبارية، سيتم كتابة رسالة فارغة، مما يخلق إدخال “خطأ” غير مقصود.

تحقق من النتيجة من خلال إعادة التحقق من ملف السجل:

Get-Content -Path "C:\Scripts\software_installer.log"

إضافة مرونة باستخدام مسار ملف سجل مخصص

بينما تعمل الوظيفة بشكل رائع، دعنا نجعلها أكثر مرونة من خلال إضافة معلمة $LogFilePath. تتيح لك هذه المعلمة تحديد مسار ملف مخصص مع توفير مسار افتراضي.

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [string]$LogFilePath = 'C:\Scripts\software_installer.log'
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

لاحظ أن $LogFilePath له مسار افتراضي هو C:\Scripts\software_installer.log، ولكن يمكنك تقديم أي مسار صالح.

لتحديد مسار ملف مختلف، استدعِ Write-Log بهذه الطريقة:

Write-Log -LogMessage 'Custom path log message' -LogFilePath 'C:\Scripts\custom_log.log'

فرض مسار الملف باستخدام ValidateScript

لا ترغب في أن تقوم وظيفتك بتسجيل ملفات غير موجودة. لهذا السبب، يمكنك التأكد من وجود الملف قبل التسجيل باستخدام خاصية المعلمة ValidateScript. تتيح لك هذه الخاصية تشغيل كود ضد قيمة المعلمة، والتحقق منها قبل تشغيل الوظيفة.

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [ValidateScript({ Test-Path -Path $_ })]
        [string]$LogFilePath = 'C:\Scripts\software_installer.log'
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

مع ValidateScript، يتحقق Write-Log من أن مسار الملف الذي تقدمه موجود. إذا لم يكن الملف موجودًا، تتوقف PowerShell وتعيد خطأ.

يمكنك إنشاء ملف فارغ قبل استدعائه للتأكد من أن الوظيفة تعمل كما هو متوقع:

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Log entry in a new file' -LogFilePath 'C:\Scripts\softwarex_installer.log'

اختبار وظيفة Write-Log والتحقق من الصحة

بعد إضافة المرونة إلى وظيفتك، من الطبيعي فقط اختبار ما إذا كانت تعمل كما هو مقصود. يجب عليك ضمان وظيفة تسجيل قوية من خلال فحص خاصية ValidateScript ورؤية كيف تعزز وظيفتك Write-Log.

دعنا نرى كيف تعمل ValidateScript من خلال محاولة التسجيل في ملف غير موجود:

Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

في هذه الحالة، يقوم خاصية ValidateScript بالتحقق مما إذا كان مسار ملف السجل المحدد موجودًا عن طريق استدعاء Test-Path. إذا لم يكن المسار موجودًا، فإن الوظيفة تعود بخطأ.

تفشل الوظيفة لأن C:\Scripts\softwarex_installer.log غير موجود. يمكنك التحقق من ذلك عن طريق تشغيل Test-Path يدويًا:

Test-Path 'C:\Scripts\softwarex_installer.log'

نظرًا لأن Test-Path يعيد $false، فإن الملف مفقود بالفعل.

لإصلاح ذلك، قم بإنشاء ملف سجل فارغ واختبر مرة أخرى.

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

الآن، تعمل الوظيفة كما هو متوقع.

أكد النتيجة عن طريق عرض ملف السجل:

Get-Content -Path 'C:\Scripts\softwarex_installer.log'

استخدام ValidateScript وغيرها من خصائص التحقق من المعلمات يفرض الاستخدام الصحيح لمعلمات الوظيفة، مما يقلل الأخطاء ويجعل وظائف PowerShell الخاصة بك أكثر موثوقية.

الخاتمة

إضافة معلمات إلى وظائف PowerShell تعزز بشكل كبير مرونتها وفائدتها. مع مجموعة من القيم الافتراضية، والخصائص الإلزامية، والتحقق، يمكن لوظائفك التعامل مع مجموعة متنوعة من المدخلات مع الحفاظ على الموثوقية.

باستخدام هذه التقنيات، يمكنك الآن بناء وظائف قابلة للتوسع وسهلة الاستخدام تناسب بسلاسة في مجموعة متنوعة من السكربتات.

قم بتوسيع مهاراتك بينما تقوم بإنشاء أدوات PowerShell أكثر تقدمًا لتبسيط وتعزيز سير عملك. تحقق من هذا دليل معلمات PowerShell واذهب أعمق في معلمات الوظائف!