معلمة PowerShell: النحو والأنواع والسمات والحجج والأمثلة

15 يونيو 2021 16760 الآراء معلمة PowerShell: النحو والأنواع والسمات والحجج والأمثلة

يستخدم مطورو البرامج النصية لـ PowerShell كتلة Powershell Param لإضافة معلمات إلى الوظائف المتقدمة. يمكن لأي شخص يقوم بتشغيل الوظيفة الوصول إلى المعلمات المضافة باستخدام PowerShell Param.

بالإضافة إلى ذلك ، بصرف النظر عن المعلمات المضافة إلى وظيفة مع كتلة المعلمات ، يضيف Windows PowerShell تلقائيًا المعلمات الشائعة.

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

تصفح مواضيع المنشور

بناء جملة كتلة معلمة PowerShell

بناء جملة كتلة معلمة PowerShell

بناء جملة PowerShell Param هو ...

)

لإضافة معلمة إلى دالة ، ابدأ بالكلمة توقف ، متبوعًا بكتلة المعلمة ، (). هنا شكل بسيط من كتلة البارامترات ...

) ال Cmdlet ملزمة السمة اختيارية وهي السمة الوحيدة المحددة خارج كتلة البارامترات. المزيد عن هذا لاحقًا في الدليل

داخل كتلة المعلمة - param () - ستحدد سمات المعلمة ووسيطاتها. علاوة على ذلك ، يتم وضع سمة المعلمة في كتلة [()].

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

ضمن كتلة المعلمات ، ستحدد وسيطات المعلمات ، مفصولة بفاصلات. مثال على سمة PowerShell Param هو ملف معامل ينسب.

بالإضافة إلى ذلك ، مثال على وسيطة بارام هو إلزامي جدال. مثال آخر على الحجة البارام هو ParameterSetName .

أخيرًا ، ستحدد اسم المعلمة. علاوة على ذلك ، ستحدد أيضًا نوع بيانات المعلمة.

في القسم التالي ، سأناقش الأنواع الشائعة لمعلمات PowerShell. بعد ذلك ، يغطي القسم الثالث سمات المعلمات الشائعة وحججها.

أخيرًا ، في القسم الأخير من هذا الدليل ، سأقدم مثالًا واقعيًا لـ SysAdmin على PowerShell Param. سيعطي القسم أيضًا أمثلة على كيفية استخدام كتلة المعلمات في وظيفة متقدمة.

أنواع معلمات بوويرشيل

أنواع معلمة بوويرشيل

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

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

بوويرشيل بارام سلسلة معامل

عند إنشاء معلمات PowerShell ، فمن المحتمل أن تقوم بإنشاء ملف سلسلة معامل. أ سلسلة المعلمة تقبل أي قيمة سلسلة.

في Windows PowerShell ، يمكن أن تكون السلسلة عبارة عن أرقام أو كلمات أو أحرف. على وجه التحديد ، أي شيء تعلن عنه في اقتباس مزدوج أو منفرد هو عبارة عن سلسلة.

في PowerShell ، يكون نوع الكائن لسلسلة هو النظام .

للإعلان عن معلمة PowerShell كمعلمة سلسلة ، قبل اسم المعلمة ، قم بتضمين الكلمة سلسلة بين قوسين. هنا مثال…

[  CmdletBinding  (DefaultParameterSetName=, SupportsShouldProcess=$true | $false ) ] Param( [  Parameter  (Mandatory=$true | $false, ValueFromPipeline=$true | $false, Position=, ParameterSetName = 'ParameterSetName')] [  Alias  ('')] [  ValidateNotNullOrEmpty  ()] [data type]$parametername |_+_| 

بوويرشيل بارام int معامل

ان int نوع البيانات هو 32 بت عدد صحيح موقع. في اللغة الإنجليزية ، أ int هو رقم ، على سبيل المثال 1 أو 2 أو 3.

على عكس أ سلسلة نوع بيانات المعامل الذي يمكن أن يأخذ أي نوع من البيانات ، ملف int المعلمة إلزامية للغاية.

إذا قمت بتعريف ملف int المعلمة ، يمكن للمعلمة قبول الأرقام فقط. علاوة على ذلك ، إذا قمت بإدخال الكلمات كقيمة لملف int المعلمة ، سيرمي PowerShell رسالة خطأ.

قبل أن أوضح لك كيفية تحديد معامل PowerShell int المعلمة ، هنا مثال عام على كيفية تحديد نوع البيانات int ...

[CmdletBinding()] Param( [Parameter()] $ParameterName )

إذا قمت بتشغيل الكود في PowerShell ، فسوف يعود 123 .

معلمة PowerShell معلمة int

على العكس من ذلك ، إذا استبدلت ، 123 بهذا هو int ، فسيقوم PowerShell بإلقاء رسالة خطأ.

[string]$ReportPath

الآن بعد أن كان لديك ملف int دورة تدريبية عن نوع البيانات ، لإنشاء معلمة PowerShell int المعلمة تسمى الرقم ، ها هو الرمز ...

[int]'123'

سيؤدي هذا إلى إجبار مستخدمي البرنامج النصي أو الوظيفة على توفير نوع البيانات الصحيح.

بوويرشيل بارام التاريخ والوقت معامل

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

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

[int]'this is an int'

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

بوويرشيل بارام يحول معامل

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

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

الطريقة التي تحدد بها ملف تحول تتشابه المعلمة مع الطريقة التي تحدد بها أنواع المعلمات الأخرى. ومع ذلك ، في مكان تحول و int ، أو التاريخ والوقت ، استخدم الكلمة تحول .

على سبيل المثال لتعريف معلمة PowerShell يحول معامل، تصدير ، استخدم الكود أدناه ...

[int]$Number

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

قد ترغب أيضًا في منح المستخدم خيار تصدير النتيجة إلى ملف نصي أو ملف CSV.

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

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

يمكنك أيضًا تحديد معلمات PowerShell أخرى بأنواع بيانات محددة. للتعرف على أنواع بيانات PowerShell ، قم بزيارة هذا الارتباط - كيفية تحديد أنواع بيانات PowerShell .

سمات معلمة PowerShell وحججها

سمات معلمة PowerShell وحججها

في صيغة PowerShell Param لهذا الدليل ، ألمحت إلى أن معلمة PowerShell لها سمات. علاوة على ذلك ، أشرت أيضًا إلى أن كل سمة معلمة لها أيضًا وسيطات.

في هذا القسم ، سأناقش سمات المعلمات وحججها.

لشرح سمات المعلمات وحججها ، سأشير إلى بناء جملة معلمة PowerShell المقدمة في القسم الأول من هذا الدليل.

[  DateTime  ]$EnterDate

بوويرشيل بارام Cmdlet ملزمة يصف

ال Cmdlet ملزمة عادة ما يتم تحديد السمة قبل كتلة المعلمات. عندما تحدد ال Cmdlet ملزمة السمة ، سيتعرف PowerShell على البرنامج النصي كوظيفة متقدمة.

في قسم بناء الجملة في هذا الدليل ، استخدمت هذا الرمز كإصدار مبسط من كتلة المعلمات.

[    Switch   ]$ExportCSV

في هذا القسم ، سأركز على Cmdlet ملزمة يصف جزء من الكود. إليك كيفية تحديد ملف يصف ...

[  CmdletBinding  (DefaultParameterSetName=, SupportsShouldProcess=$true | $false ) ] Param( [  Parameter  (Mandatory=$true | $false, ValueFromPipeline=$true | $false, Position=, ParameterSetName = 'ParameterSetName')] [  Alias  ('')] [  ValidateNotNullOrEmpty  ()] [data type]$parametername |_+_| 

في الأقسام الفرعية الثلاثة التالية ، سأناقش بعض الحجج الشائعة ، يمكنك تحديدها في Cmdlet ملزمة ينسب.

لتجنب الشك ، يجب تحديد الكل الحجج داخل () كتلة من يصف . أيضًا ، يجب عليك فصل جميع السمات بفاصلة (،) ، باستثناء الأخير الحجج في حدود يصف .

بوويرشيل بارام DefaultParameterSetName جدال

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

ومع ذلك ، لا يمكن للمستخدم خلط المعلمات في المجموعة الأولى مع المعلمات في المجموعة الثانية.

علاوة على ذلك ، يحدد مطور الوظيفة جميع المعلمات التي يمكن للمستخدم استخدامها في نفس الأمر مع ParameterSetName جدال. ال ParameterSetName يتم تحديد الوسيطة داخل سمة المعلمة (المزيد حول هذا في القسم التالي).

المعنى الضمني لوجود مجموعات مختلفة من المعلمات المجمعة هو أنه سيكون لديك مختلفة ParameterSetName س.

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

ال DefaultParameterSetName يتم تعريف الوسيطة داخل Cmdlet ملزمة كتلة السمة. هنا مثال…

[CmdletBinding()] Param( [Parameter()] $ParameterName )

أخيرًا ، للاحتفاظ بتنسيق كتلة معلمات PowerShell ، سأعيد تقديم كتلة المعلمات أدناه ...

[CmdletBinding()]

بوويرشيل بارام يدعم العملية جدال

هذه حجة أخرى يمكنك تحديدها في Cmdlet ملزمة يصف . مثل ال DefaultParameterSetName حجة يدعم العملية الحجة اختيارية.

ال يدعم العملية الوسيطة يضيف ال يتأكد و ماذا إذا المعلمات المشتركة للوظيفة.

لإضافة هذه الوسيطة ، أضف فاصلة (،) إلى نهاية ملف DefaultParameterSetName جدال. ثم أضف السطر - يدعم العملية = $ true أو $ false.

مع هذه الحجة الجديدة المدرجة ، Cmdlet ملزمة يصف سيبدو الآن مثل هذا ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1')]

بوويرشيل بارام HelpURI جدال

إذا كنت معتادًا على PowerShell احصل على مساعدة Cmdlet ، ربما تكون قد صادفت ملف متصل معامل. عندما تقوم بتشغيل احصل على مساعدة مع ال متصل المعلمة ، يفتح PowerShell صفحة التعليمات عبر الإنترنت الخاصة بـ Cmdlet.

على سبيل المثال ، لفتح صفحة التعليمات عبر الإنترنت الخاصة بـ Out-File Cmdlet ، قم بتشغيل الأمر أدناه ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1')] Param( [Parameter()] $ParameterName )

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

هنا مثال…

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true)] Param( [Parameter()] $ParameterName )

سأدرج الآن هذه الحجة الأخيرة في Cmdlet ملزمة يصف . هذا هو الرمز المحدث ...

  Get-Help  Out-File -  Online  

بوويرشيل بارام معامل يصف

في بوويرشيل بارام Cmdlet ملزمة قسم السمة الفرعي ، ناقشت 3 حجج يمكنك تضمينها في Cmdlet ملزمة كتلة السمة.

كما رأيت ، فإن Cmdlet ملزمة كتلة السمة هي السمة الوحيدة المحددة خارج كتلة المعلمات.

في هذا القسم الفرعي ، ستتعرف على سمة المعلمة. بالإضافة إلى ذلك ، ستتعرف أيضًا على الوسائط الشائعة التي يمكنك إضافتها إلى هذه السمة.

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

يمكنك تحديد سمة المعلمة من خلال إرفاق كلمة معلمة ، متبوعة بأقواس () في كتلة []. هنا مثال…

HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/'

للمضي قدمًا ، يجب عليك تحديد جميع وسائط سمة المعلمة داخل كتلة ().

في الأقسام الفرعية التالية من قسم سمة معلمة PowerShell ، سأقدم وأشرح الحجج الشائعة التي يمكنك تحديدها داخل سمة المعلمة.

بوويرشيل بارام ParameterSetName جدال

عندما شرحت DefaultParameterSetName في وقت سابق في هذا الدليل ، قدمت ParameterSetName جدال. يمكنك استخدام هذه الوسيطة للدُفعة أو مجموعة المعلمات التي يمكن للمستخدم تشغيلها في نفس الأمر.

على سبيل المثال ، لتحديد ملف ParameterSetName اتصل ParameterSetName1 ، أدخل الرمز أدناه في كتلة سمة المعلمة ().

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter()] $ParameterName )

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

Param(  
[Parameter()]
$ParameterName
)

إذا أعدت ملف Cmdlet ملزمة السمة ، سيبدو نموذج كود معلمات PowerShell الخاص بي بهذا الشكل ...

ParameterSetName='ParameterSetName1'

بوويرشيل بارام إلزامي جدال

يمكنك استعمال ال إلزامي حجة لتحديد ما إذا كانت المعلمة مطلوبة أم اختيارية. ال إلزامي تقبل الوسيطة قيمة $ true أو $ false - يعني $ true يتطلب ، $ false ، ليس مطلوبًا.

علاوة على ذلك ، فإن إلزامي الحجة اختيارية. ومع ذلك ، إذا لم يتم تعريف هذه الوسيطة ، فسيتم التعامل مع المعلمة على أنها اختيارية.

لتحديد ال إلزامي وسيطة ، أضف الشفرة أدناه إلى كتلة سمة المعلمة ...

Param( [Parameter(ParameterSetName='ParameterSetName1')] $ParameterName )

أخيرًا ، إذا قمت بتضمين ملف إلزامي رمز الوسيطة إلى كود معلمات PowerShell الخاص بي ، سأحصل الآن ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1')] $ParameterName )

بوويرشيل بارام موضع جدال

ال موضع تحدد وسيطة سمة المعلمة موضع المعلمة. القيمة هي عدد صحيح يبدأ من 0 (صفر).

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

سيقوم PowerShell بعد ذلك بتعيين كل قيمة في سطر الأوامر وفقًا لموضع المعلمة.

على سبيل المثال ، ملف Get-ChildItem Cmdlet له معلمة تسمى طريق (مع الموضع 0). يحتوي Cmdlet أيضًا على معلمة أخرى ، منقي (مع الموضع 1).

بشكل افتراضي ، إذا قمت بتشغيل ملف Get-ChildItem الأمر ، لا بد لي من تضمين أسماء المعلمات قبل إضافة قيمها. انظر الأمر أدناه ...

Mandatory=$true

في هذا الأمر ، استدعيت المعلمات ثم حددت قيمها.

حجة موقف معلمة PowerShell

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

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1', Mandatory=$true)] $ParameterName )

من الواضح أن هذا يوفر لي الوقت! ومع ذلك ، إذا كنت تبحث عن رمز PowerShell طويل ، فقد يتسبب ذلك في بعض الالتباس.

يعطي الأمر نفس النتيجة في PowerShell ...

سيقوم PowerShell تلقائيًا بتعيين القيم الموجودة في المواضع إلى المعلمات بناءً على موضع جدال.

للمضي قدمًا ، إليك كيفية تحديد ملف موضع جدال…

Get-ChildItem -Path D:G-Drive -Filter *.txt
في هذا المثال ، موضع المعلمة الخاص بي هو 0 (صفر). عندما أحدد المعلمة التالية ، ستكون في الموضع 1 ، وهكذا. لا يمكن أن يكون لديك معلمتان في نفس الموضع. لاحقًا في الدليل ، ستتعلم كيفية إضافة معلمة واحدة في نفس الموضع لكن ParameterSetNames مختلفة.

سأضيف الآن هذه الوسيطة إلى نموذج الشفرة الخاص بي ...

Get-ChildItem D:G-Drive *.txt

بوويرشيل بارام ValueFromPipeline جدال

معلمة أخرى شائعة الاستخدام هي ValueFromPipeline جدال. كما يوحي الاسم ، تحدد هذه الوسيطة ما إذا كانت المعلمة تقبل قيمًا من خط الأنابيب.

هذه هي الطريقة التي تحدد بها هذه الحجة ...

Position=0

إذا أضفت هذه الوسيطة الجديدة إلى الكود الخاص بي ، فسيبدو مثل هذا ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1', Mandatory=$true, Position=0)] $ParameterName )

هناك حجة أخرى تسمى ValueFromPipelineByPropertyName . للقراءة عن هذه الحجة ، قم بزيارة about_Functions_Advanced_Parameters .

بوويرشيل بارام المساعدة جدال

يمكنك استخدام هذه الوسيطة لتحديد الرسالة لإظهار كيفية استخدام المعلمة للمستخدمين. لتحديد أ المساعدة وسيطة للمعلمة ، استخدم رمزًا مشابهًا للرمز أدناه ...

ValueFromPipeline=$true or $false

وها هو الكود المحدّث الآن ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1', Mandatory=$true, Position=0, ValueFromPipeline=$true)] $ParameterName )

لقد ناقشت حتى الآن في هذا القسم سمتان من سمات معلمات PowerShell - Cmdlet ملزمة و معامل . بالإضافة إلى ذلك ، ناقشت أيضًا الحجج الشائعة التي يمكنك تحديدها لهذه السمات.

في الأقسام الفرعية الثلاثة المتبقية من هذا القسم ، سأعلمك 3 سمات معلمات PowerShell شائعة الاستخدام. ومع ذلك ، لا تتطلب هذه السمات الثلاث تحديد الوسائط.

بوويرشيل بارام الاسم المستعار يصف

تُستخدم سمة الاسم المستعار لتحديد الأسماء المستعارة للمعلمة. كما خمنت ، يمكن استخدام الاسم المستعار لمعلمة PowerShell بدلاً من المعلمة.

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

لسرد جميع الأسماء المستعارة لـ Cmdlets والوظائف ، قم بتشغيل الأمر أدناه

HelpMessage='Specifiy your message here'

سيؤدي هذا إلى سرد كافة الأسماء المستعارة ...

سمة الاسم المستعار لمعامل PowerShell

الانتقال إلى الاسم المستعار السمة ، لتحديد واحدة لمعلمة معلمات PowerShell ، استخدم رمزًا مشابهًا للرمز أدناه ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1', Mandatory=$true, Position=0, ValueFromPipeline=$true, HelpMessage='Specifiy your message here')] $ParameterName )
في هذا المثال ، FP هو الاسم المستعار للمعلمة.

إذا أضفت هذا إلى الكود الخاص بي ، فإن الإصدار المحدث سيبدو هكذا ...

Get-Alias

بوويرشيل بارام يدعم البطاقات البرية يصف

تحدد سمة معلمة المعلمة هذه ما إذا كانت المعلمة تقبل أحرف البدل أم لا. إليك كيفية تحديد هذه السمة ...

[Alias('FP')]

بوويرشيل بارام ValidateNotNullOrEmpty سمة التحقق

مثل معظم السمات التي تم تناولها بالفعل في هذا الدليل ، فإن اسم هذه السمة يعطيها أيضًا. إنها سمة التحقق من الصحة.

عند تحديد هذه السمة ، لن تقبل المعلمة قيمة خالية ($ null). بالإضافة إلى ذلك ، لن يقبل قيمة فارغة ().

إذا قام المستخدم بإدخال $ null ، أو ستظهر الدالة خطأ. لتحديد هذه السمة ، أدخل الرمز أدناه ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1', Mandatory=$true, Position=0, ValueFromPipeline=$true, HelpMessage='Specifiy your message here', [Alias('FP')])] $ParameterName )

أخيرًا ، سوف أقوم بتحديث الكود الخاص بي بآخر سمتين ...

[SupportsWildcards()]

اسم معلمة PowerShell

بعد أن تحدد جميع سمات ووسائط المعلمة ، تحتاج إلى إضافة اسم المعلمة. يتم تعريف معلمة معلمات PowerShell كمتغير - بعلامة الدولار ($) ، متبوعة باسم المعلمة.

يمكنك أيضًا إدخال نوع بيانات اختياريًا للمعلمة. في القسم 2 من هذا الدليل ، ناقشت أنواعًا مختلفة من معلمات PowerShell.

إليك كيفية تحديد المعلمة التي يمكن قبولها سلسلة نوع البيانات.

[ValidateNotNullOrEmpty()]

هذا هو مثال الكود المحدث ...

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1', Mandatory=$true, Position=0, ValueFromPipeline=$true, HelpMessage='Specifiy your message here', [Alias('FP')])] [SupportsWildcards()] [ValidateNotNullOrEmpty()] $ParameterName )

كيفية تحديد معلمة PowerShell واحدة في مجموعات معلمات متعددة

كيفية تحديد معلمة PowerShell واحدة في مجموعات معلمات متعددة

إذا كنت جديدًا في ترميز وظائف PowerShell ، فمن المحتمل أنك ستقع في إغراء تحديد معلمة واحدة عدة مرات.

أحد أسباب رغبتك في الحصول على معلمة عدة مرات هو عندما يتم استخدام معلمة في العديد من ParameterSetNames (مجموعات معلمات متعددة).

لقيادة هذا المنزل ، لنفترض أنك تقوم بتطوير وظيفة PowerShell التي تحتوي على طريق معامل. ومع ذلك ، لديك 2 ParameterSetNames التي تتطلب معلمة المسار.

من المحتمل أن يحدد معظم الأشخاص الجدد في البرمجة النصية لـ PowerShell المعلمات الموضحة أدناه ...

[  string  ]$ParameterName

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

كيفية تحديد معلمة PowerShell واحدة في مجموعات معلمات متعددة

إذا كيف يمكنك حل هذه المشكلة؟ الحل هو تحديد سمات المعلمات 2 ووسائطها - بما في ذلك ParameterSetNames الخاصة بهم.

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

[CmdletBinding(  DefaultParameterSetName  ='ParameterSetName1', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter(ParameterSetName='ParameterSetName1', Mandatory=$true, Position=0, ValueFromPipeline=$true, HelpMessage='Specifiy your message here', [Alias('FP')])] [SupportsWildcards()] [ValidateNotNullOrEmpty()] [string]$ParameterName )

الآن إذا قمت بنسخ هذا الرمز إلى PowerShell ISE ، فسيكون الأمر على ما يرام.

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

أمثلة على معلمة PowerShell

أمثلة على معلمة PowerShell

في هذا القسم الأخير من الدليل ، سأقدم مثالًا حقيقيًا على معلمة SysAdmin PowerShell.

أثناء كتابتي لهذا الدليل ، بدأت في تطوير برنامج نصي / وظيفة PowerShell للحصول على حجم المجلد وعدد الملفات. هنا الجزء البارز من الوظيفة ...

Param( [Parameter(ParameterSetName='  ParameterSetName1  ', Mandatory=$true, Position=0)] [string]$  Path  , [Parameter(ParameterSetName='  ParameterSetName2  ', Mandatory=$true, Position=0)] [string]$  Path  )

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

لتسهيل اتباع الأسطر الموجودة في الكود المشار إليه في الأقسام الفرعية التالية ، قم بتنزيل PowerShellParamExample.zip. بعد ذلك ، قم بفك ضغط الملف وافتح ملف .ps1 في PowerShell ISE.

مثال على معلمة ParameterSetName PowerShell

يشتمل رمز مثال معلمة PowerShell الخاص بي على ثلاثة أسماء ParameterSetNames - DisplayResult و تصدير و تصدير . لقد استخدمت هذه الأسماء لتسهيل التعرف على ما يفعلونه.

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

لذلك ، توفر ParameterSetNames الثلاثة للمستخدم خيار عرض النتائج على وحدة تحكم PowerShell. بدلاً من ذلك ، لدى المستخدم خيار تصدير النتيجة إلى ملف نصي أو ملف CSV.

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

سوف أتوسع في هذه الفكرة في الأقسام الفرعية والأمثلة اللاحقة.

Cmdlet ملزمة السمة و DefaultParameterSetName أمثلة الحجة

في الأقسام السابقة من هذا الدليل ، صادفت ملف Cmdlet ملزمة يصف. علاوة على ذلك ، صادفت أيضًا إحدى حججها - DefaultParameterSetName .

ال DefaultParameterSetName يتم استخدام الوسيطة لتحديد مجموعة المعلمات الافتراضية التي تستدعيها الوظيفة. في هذا المثال ، اسم مجموعة المعلمات الافتراضية هو DisplayResult .

ال DefaultParameterSetName أعلن في السطر 1 من الكود.

سيحاول PowerShell استخدام مجموعة المعلمات المعلنة بواسطة ملف DefaultParameterSetName إذا كان لا يمكن تحديد المعلمة التي يجب استخدامها. ومع ذلك ، إذا قمت بتعيين المعلمات الإلزامية ، يمكنك تجنب هذه المشكلة.

على أي حال ، لا ضرر من الإعلان عن اسم مجموعة معلمات افتراضية.

مسار الملف مثال على معلمة السلسلة

هنا يبدا المرح! ال مسار الملف تُستخدم المعلمة لإدخال مسار المجلد ، وستحصل الوظيفة على حجم مجلداتها الفرعية - وتحسب عدد الملفات في كل مجلد فرعي.

هذه معلمة سلسلة. بمعنى أنه يقبل أي سلسلة كمدخلات.

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

للإعلان عن مسار الملف المعلمة في أسماء مجموعة المعلمات الثلاثة ، لقد قمت بإنشاء ثلاث سمات للمعلمات.

تكون سمة المعلمة الأولى بين السطرين 5 و 11. بالإضافة إلى ذلك ، تحتوي سمة المعلمة الأولى هذه على عدة وسيطات.

ومع ذلك ، أود منك أن تولي اهتماما خاصا إلى ParameterSetName جدال - DisplayResult .

مثال على معلمة سلسلة FolderPath

ثانيًا ، بين السطور 12 و 18 ، أعلنت سمة معلمة أخرى بامتداد ParameterSetName دعا حجة تصدير .

أخيرًا ، بين السطور 19 و 25 ، أعلنت عن سمة معلمة ثالثة بامتداد ParameterSetName دعا حجة تصدير .

مثال على معلمة سلسلة FolderPath

علاوة على ذلك ، إذا لاحظت ، على عكس الإعلان عن سمات 3 معلمات ، فقد أعلنت عن واحد الاسم المستعار ، و ValidateNotNullOrEmpty صفات. يمكن العثور على هذه السمات في السطر 26 و 27.

مثال على معلمة سلسلة FolderPath

أخيرًا ، أسفل كل السمات وحججها ، قمت بتضمين اسم المعلمة - مسار الملف . اسم المعلمة موجود في السطر 28.

مثال على معلمة سلسلة FolderPathفي القسم الفرعي الأخير من هذا القسم ، سترى كيف تعرض الوظيفة هذه المعلمة في 3 صيغ أوامر.

DisplayResult و تصدير و تصدير مثال معلمة التبديل

من السطر 29 من كود المعلمة ، أعلنت مجموعة أخرى من سمات المعلمات وحججها.

أولاً ، بين السطور 29 و 37 ، أعلن عن سمات المعلمة والحجج الخاصة بـ DisplayResult معامل.

بعد ذلك ، بين السطور 38 و 47 ، أعلن عن معامل آخر يسمى تصدير .

مثال على معلمة DisplayResult و ExportTxt و ExportCSV

أخيرًا ، بين السطور 48 و 57 ، أعلنت تصدير معامل.

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

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

كيفية استخدام PowerShell Param في وظيفة PowerShell

في هذا القسم الفرعي ، أرغب في إدخال كتلة وظيفة PowerShell في رمز المثال الخاص بي.

صيغة كتلة وظيفة PowerShell هي ...

Param( [Parameter(ParameterSetName='  ParameterSetName1  ', Mandatory=$true, Position=0)] [Parameter(ParameterSetName='  ParameterSetName2  ', Mandatory=$true, Position=0)] [string]$  Path  )

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

ستبدو الوظيفة النهائية الآن هكذا ...

[CmdletBinding(  DefaultParameterSetName  ='DisplayResult', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter( ParameterSetName='DisplayResult', Mandatory=$true, Position=0, HelpMessage='Specifiy the folder path to calculate size and file count for its sub-folders', ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Parameter( ParameterSetName='ExportTxt', Mandatory=$true, Position=0, HelpMessage='Specifiy the folder path to calculate size and file count for its sub-folders', ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Parameter( ParameterSetName='ExportCSV', Mandatory=$true, Position=0, HelpMessage='Specifiy the folder path to calculate size and file count for its sub-folders', ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Alias('FP')] #attribute must appear once [ValidateNotNullOrEmpty()] [string[]]$FolderPath, #can specify multiple paths separated by commas [Parameter( ParameterSetName='DisplayResult', Mandatory=$true, Position=1, HelpMessage='USe this parameter to display result on the console', ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$false)] [Alias('DR')] [Switch]$DisplayResult, [Parameter( ParameterSetName='ExportTxt', Mandatory=$true, Position=1, HelpMessage='USe this parameter to send result to a text file', ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$false)] [Alias('ExTxt')] [ValidateNotNullOrEmpty()] [Switch]$ExportTxt, [Parameter( ParameterSetName='ExportCSV', Mandatory=$true, Position=1, HelpMessage='USe this parameter to send result to a CSV file', ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$false)] [Alias('ExCSV')] [ValidateNotNullOrEmpty()] [Switch]$ExportCSV, [Parameter( ParameterSetName='ExportTxt', Mandatory=$true, Position=2, ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$true)] [Parameter( ParameterSetName='ExportCSV', Mandatory=$true, Position=2, ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$true)] [ValidateNotNullOrEmpty()] #attribute must appear once [string]$ReportPath )
في هذا المثال ، كتل البداية {} ، والعملية {} ، والنهاية {} فارغة.

اختبار معلمات PowerShell الخاصة بي في وظيفة PowerShell

في هذا القسم الأخير ، سأختبر المعلمات في الوظيفة التي أنشأتها في القسم الأخير.

إذا كنت ترغب في اختباره بنفسك ، يمكنك تنزيل الكود بالنقر فوق هذا الارتباط - Get-FolderSizeFileCount.zip. بعد ذلك ، قم بفك ضغط الملف المضغوط.

بمجرد فك ضغط الملف ، افتح PowerShell وقم بتشغيل الأمر أدناه:

Function { Param( ) Begin { } Process { } End { } }
قم بالتغيير إلى المسار الكامل للملف الذي تم فك ضغطه.

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

اختبار معلمات PowerShell الخاصة بي في وظيفة PowerShell

بمجرد استيراد الوحدة النمطية ، على نفس وحدة تحكم PowerShell ، قم بتشغيل الأمر أدناه:

Function Get-FolderSizeFileCount { [CmdletBinding(  DefaultParameterSetName  ='DisplayResult', SupportsShouldProcess=$true, HelpURI='https://www.itechguides.com/category/technology-explained/powershell-cmd-explained/')] Param( [Parameter( ParameterSetName='DisplayResult', Mandatory=$true, Position=0, HelpMessage='Specifiy the folder path to calculate size and file count for its sub-folders', ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Parameter( ParameterSetName='ExportTxt', Mandatory=$true, Position=0, HelpMessage='Specifiy the folder path to calculate size and file count for its sub-folders', ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Parameter( ParameterSetName='ExportCSV', Mandatory=$true, Position=0, HelpMessage='Specifiy the folder path to calculate size and file count for its sub-folders', ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Alias('FP')] #attribute must appear once [ValidateNotNullOrEmpty()] [string[]]$FolderPath, #can specify multiple paths separated by commas [Parameter( ParameterSetName='DisplayResult', Mandatory=$true, Position=1, HelpMessage='USe this parameter to display result on the console', ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$false)] [Alias('DR')] [Switch]$DisplayResult, [Parameter( ParameterSetName='ExportTxt', Mandatory=$true, Position=1, HelpMessage='USe this parameter to send result to a text file', ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$false)] [Alias('ExTxt')] [ValidateNotNullOrEmpty()] [Switch]$ExportTxt, [Parameter( ParameterSetName='ExportCSV', Mandatory=$true, Position=1, HelpMessage='USe this parameter to send result to a CSV file', ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$false)] [Alias('ExCSV')] [ValidateNotNullOrEmpty()] [Switch]$ExportCSV, [Parameter( ParameterSetName='ExportTxt', Mandatory=$true, Position=2, ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$true)] [Parameter( ParameterSetName='ExportCSV', Mandatory=$true, Position=2, ValueFromPipeline=$false, ValueFromPipelineByPropertyName=$true)] [ValidateNotNullOrEmpty()] #attribute must appear once [string]$ReportPath ) Begin { } Process { } End { } }

ها هي نتيجة الأمر ...

ما أريد أن أعرضه لكم هو قسم SYNTAX في صفحة المساعدة الخاصة بوظيفتي. من لقطة الشاشة أعلاه ، يمكنك تشغيل الأمر Get-FolderSizeFileCount في 3 أوامر مختلفة:

Import-Module    Get-FolderSizeFileCountGet-FolderSizeFileCountGet-FolderSizeFileCount.psm1

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

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

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

هذا هو - دليل شامل حول معلمة PowerShell! آمل أن تجد أنه من المفيد؟

إذا وجدت أنها مفيدة ، يرجى التصويت نعم إلى هل كان هذا المنشور سؤالًا مفيدًا أدناه.

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

أخيرًا ، لمزيد من مناطق S PowerShell tech ، تفضل بزيارة صفحة دليل Windows PowerShell How-To. قد تجد أيضًا صفحة العمل من الصفحة الرئيسية الخاصة بنا مفيدة جدًا.

المراجع وقراءات إضافية

  1. كيفية تحديد أنواع بيانات PowerShell
  2. about_Functions_Advanced_Parameters
  3. about_Functions_CmdletBindingAttribute