المعلمات

مكتمل

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

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

Cmdlets والدالات والبرامج النصية تقبل جميعها المعلمات.

الإعلان عن معلمة واستخدامها

للإعلان عن معلمة، تحتاج إلى استخدام الكلمة الأساسية Param مع قوسين واحد مفتوح والآخر مغلق:

Param()

داخل الأقواس، يمكنك تحديد معلماتك، والفصل بينها بفواصل. قد يبدو إعلان المعلمة النموذجي مثل هذا:

# CreateFile.ps1
Param (
  $Path
)
New-Item $Path # Creates a new file at $Path.
Write-Host "File $Path was created"

يحتوي البرنامج النصي على معلمة $Path التي يجري استخدامها لاحقًا في البرنامج النصي لإنشاء ملف. أصبح البرنامج النصي الآن أكثر مرونةً.

استخدِم المعلمة

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

./CreateFile.ps1 -Path './newfile.txt' # File ./newfile.txt was created.
./CreateFile.ps1 -Path './anotherfile.txt' # File ./anotherfile.txt was created.

نظرًا لأنك استخدمت معلمة، فلن تحتاج إلى تغيير ملف البرنامج النصي عندما تريد استدعاء الملف بشيءٍ آخر.

إشعار

قد لا يستفيد هذا البرنامج النصي المعين كثيرًا من استخدام معلمة لأنه يستدعي فقط New-Item. بمجرد أن يبلغ طول برنامجك النصي بضعة أسطر، فإن استخدام المعلمة سيؤتي ثماره.

تحسين معلماتك

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

• هل هي إلزامية؟ هل المعلمة اختيارية أم مطلوبة؟
• ما القيم المسموح بها؟ ما القيم المعقولة؟
• هل تقبل أكثر من نوعٍ واحدٍ من أنواع القيمة؟ هل تقبل المعلمة أي نوع من القيم، مثل السلسلة، والقيمة المنطقية، والعدد الصحيح، والعنصر؟
• هل يمكن للمعلمة الاعتماد على قيمة افتراضية؟ هل يمكنك حذف القيمة تمامًا والاعتماد على قيمة افتراضية بدلًا من ذلك؟
• هل يمكنك تحسين تجربة المستخدم أكثر من ذلك؟ هل يمكنك أن تكون أوضح للمستخدم من خلال تقديم رسالة مساعدة؟

تحديد أسلوب

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

هناك أسلوبان يمكنك استخدامها لجعل برنامجك النصي أكثر أمانًا. يمكنك كتابة تعليمات برمجية مخصصة لفحص قيمة المعلمة. أو يمكنك استخدام المزخرفات التي تفعل الشيء نفسه تقريبًا. دعونا نفكر في كلا الأسلوبين.

• استخدم If/Else. تسمح لك البنية If/Else بالتحقق من قيمة المعلمة ثم تقرر ما يجب إجراؤه. إليك مثال:

  Param(
     $Path
  )
  If (-Not $Path -eq '') {
     New-Item $Path
     Write-Host "File created at path $Path"
  } Else {
     Write-Error "Path cannot be empty"
  } 
  

  سيُشغل البرنامج النصي Write-Error إذا لم تزود قيمة لـ$Path.

• استخدام المزخرف Parameter[]. وهناك طريقة أفضل، والتي تتطلب كتابة أقل، وهي استخدام المزخرف Parameter[]:

  Param(
     [Parameter(Mandatory)]
     $Path
  )
  New-Item $Path
  Write-Host "File created at path $Path"
  

  إذا شغلت هذا البرنامج النصي وحذفت قيمة لـ $Path، فسينتهي بك الأمر في مربع حوار يطالب بالقيمة:

  cmdlet CreateFile.ps1 at command pipeline position 1
  Supply values for the following parameters:
  Path:
  

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

  [Parameter(Mandatory, HelpMessage = "Please provide a valid path")]
  

  عند تشغيل البرنامج النصي، تتلقى رسالة تخبرك بكتابة !? للحصول على مزيد من المعلومات:

  cmdlet CreateFile.ps1 at command pipeline position 1
  Supply values for the following parameters:
  (Type !? for Help.)
  Path: !?  # You type !?
  Please provide a valid path  # Your Help message.
  

• تعيين نوع. إذا عينت نوع إلى معلمة، فيمكنك القول، على سبيل المثال، أن المعلمة تقبل السلاسل فقط لا القيم المنطقية. وهكذا سيعرف المستخدم ما الذي يمكنهم توقعه. يمكنك تعيين نوع إلى معلمة من خلال إسباقه بالنوع، محاطًا بأقواس:

  Param(
     [string]$Path
  )
  

هذه الأساليب الثلاثة لا يستبعد بعضها البعض. يمكنك دمج هذه الأساليب لجعل برنامجك النصي أكثر أمانًا.