احتراف وظائف PowerShell: دليل خطوة بخطوة

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

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

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

تم استخراج هذه المقالة من كتابي PowerShell for Sysadmins: Workflow Automation Made Easy. إذا تعلمت شيئًا في هذا البرنامج التعليمي ، تأكد من التحقق من الكتاب لمعرفة المزيد عن الوظائف والكثير من الأشياء الرائعة الأخرى في PowerShell.

الوظائف مقابل الأوامر المساعدة

قد يبدو مفهوم الدالة مألوفًا لأنه يشبه قليلاً الأوامر التي ربما كنت تستخدمها بالفعل. الأوامر مثل Start-Service و Write-Host، على سبيل المثال، مشابهة للدوال. هذه هي قطع الشفرة ذات الأسماء التي تحل مشكلة واحدة. الفرق بين الدالة والأمر هو كيفية إنشاء كل من هذه البنى.

A cmdlet isn’t written with PowerShell. It’s written in another language, typically something like C#. The cmdlet is then compiled and made available inside PowerShell.

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

يمكنك رؤية الأوامر التي هي أمر وأيها هي دالة باستخدام أمر Get-Command ومعامل CommandType كما هو موضح أدناه

Get-Command –CommandType Function

يعيد الأمر أعلاه جميع الدوال المحملة حاليًا في جلستك في PowerShell، أو داخل الوحدات التي تتوفر لـ PowerShell.

ذات الصلة: فهم وبناء وحدات PowerShell

المتطلبات الأساسية

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

بناء دالة بسيطة

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

فيما يلي يمكنك رؤية وظيفة أساسية وتنفيذ تلك الوظيفة. تسمى هذه الوظيفة Install-Software وتستخدم Write-Host لعرض رسالة في وحدة التحكم. بمجرد تعريفها، يمكنك استخدام اسم هذه الوظيفة لتنفيذ الأكواد داخل مجموعة الأكواد الخاصة بها.

PS> function Install-Software { Write-Host 'I installed some software. Yippee!' }
PS> Install-Software
I installed some software, Yippee!

التسمية باستخدام فعل-اسم

A function’s name is important. You can name your functions whatever you want, but the name should always describe what the function does. The function-naming convention in PowerShell is the Verb-Noun syntax.

يجب أن تبدأ اسم الوظيفة دائمًا بفعل تليه شرطة واسم. للعثور على قائمة الأفعال “المعتمدة”، استخدم cmdlet Get-Verb.

تغيير سلوك الوظيفة

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

PS> function Install-Software { Write-Host 'You installed some software, Yay!' }
PS> Install-Software
You installed some software, Yay!

الآن بعد تغيير الأكواد داخل الوظيفة، ستعرض رسالة مختلفة قليلاً.

تعريف وظيفة متقدمة

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

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

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

I suggest you now open your favorite editor and store the function in a .ps1 file as you work through the rest of the tutorial.

إضافة معلمات إلى الوظائف

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

ذات الصلة: كل ما ترغب في معرفته عن معلمات PowerShell

على سبيل المثال، قد يكون للبرنامج الخيالي الذي تقوم بتثبيته عبر وظيفة Install-Software العديد من الإصدارات. ولكن حاليًا، لا توفر وظيفة Install-Software طريقة للمستخدم لتحديد الإصدار الذي يرغبون في تثبيته.

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

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

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

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

إنشاء معامل بسيط

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

function Install-Software {
	[CmdletBinding()]
	param()

	Write-Host 'I installed software version 2. Yippee!'
}

في هذه النقطة ، لم تتغير وظيفة الدالة الفعلية على الإطلاق. لقد قمت فقط بتثبيت الأنابيب ، مما يجهز الدالة لاستخدام معامل.

في الوقت الحالي ، لا تقوم الدالة بتثبيت أي برنامج فعليًا. إنها مجرد استخدام cmdlet “Write-Host” لمحاكاة تثبيت البرنامج حتى تتمكن من التركيز على كتابة الدالة.

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

function Install-Software {
	[CmdletBinding()]
	param(
		[Parameter()]
		[string] $Version
	)
	
	Write-Host "I installed software version $Version. Yippee!"

}

داخل كتلة “param” أعلاه ، يجب أن تقوم بتعريف كتلة المعامل. باستخدام كتلة “Parameter()” بهذه الطريقة ، سيتحول إلى “معامل متقدم”. تعمل كتلة المعامل الفارغة مثل الكتلة الموجودة هنا بشكل عام على لا شيء ، ولكنها مطلوبة ، وسأشرح كيفية استخدامها في القسم التالي.

لنركز بدلاً من ذلك على نوع [string] أمام اسم المعلمة. عن طريق وضع نوع المعلمة بين أقواس مربعة قبل اسم المتغير المعلمة، فإنك تقوم بتحويل قيمة المعلمة إلى نوع محدد. ستحاول PowerShell دائمًا تحويل أي قيمة يتم تمريرها إلى هذه المعلمة إلى سلسلة نصية – إذا لم تكن بالفعل كذلك. أعلاه، سيتم تعامل أي شيء يتم تمريره كـ $Version دائمًا كسلسلة نصية.

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

أضف أيضًا $Version إلى تعليمة Write-Host الخاصة بك الآن. هذا يعني أنه عند تشغيل وظيفة Install-Software بمعلمة Version وتمرير رقم الإصدار إليها، يجب أن تحصل على تعليمة توضح ذلك كما هو مبين أدناه.

PS> Install-Software -Version 2
I installed software version 2. Yippee!

دعنا نرى ما يمكنك فعله باستخدام هذه المعلمة الآن.

سمة المعلمة الإلزامية

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

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

function Install-Software {
	[CmdletBinding()]
	param(
		[Parameter(Mandatory)]
		[string]$Version
	)

	Write-Host "I installed software version $Version. Yippee!"

}

إذا قمت بتشغيل الوظيفة أعلاه، يجب أن تحصل على الرسالة التالية:

بمجرد تعيين السمة الإلزامية، ستتوقف تنفيذ الوظيفة بدون المعلمة حتى يقوم المستخدم بإدخال قيمة. الآن تنتظر الوظيفة حتى يحدد المستخدم قيمة لمعلمة “الإصدار”. بمجرد إدخالها، يقوم PowerShell بتنفيذ الوظيفة.

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

Install-Software -Version 2

قيم المعلمة الافتراضية

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

على سبيل المثال، إذا كنت ترغب في تثبيت الإصدار 2 من هذا البرنامج في 90 بالمائة من الأحيان، وتفضل عدم الحاجة إلى ضبط القيمة في كل مرة تقوم فيها بتشغيل هذه الوظيفة، يمكنك تعيين قيمة افتراضية 2 لمعلمة “$Version”. يمكنك رؤية هذا المثال أدناه.

function Install-Software {
	[CmdletBinding()]
	param(
		[Parameter()]
		[string]$Version = 2
	)

	Write-Host "I installed software version $Version. Yippee!"

}

وجود معلمة افتراضية لا يمنعك من تمرير قيمة. ستستبدل القيمة التي تم تمريرها بالقيمة الافتراضية.

إضافة سمات التحقق من المعلمات

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

سيقوم تقييد المعلومات التي يمكن للمستخدمين (أو حتى أنت!) تمريرها إلى وظائفك أو نصوصك بالتخلص من الشيفرة الغير ضرورية داخل وظيفتك. على سبيل المثال، فلنقل أنك تمرر القيمة 3 إلى وظيفة “Install-Software” الخاصة بك، على علم بأن الإصدار 3 هو إصدار موجود.

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

الحياة بدون التحقق من المعلمة

تحقق من المثال أدناه عند استخدام سلسلة $Version في مسار الملف. إذا قام شخص ما بتمرير قيمة لا تكمل اسم المجلد الموجود (على سبيل المثال، SoftwareV3 أو SoftwareV4)، ستفشل الوظيفة.

function Install-Software {
	param(
		[Parameter(Mandatory)]
		[string]$Version
	)

	Get-ChildItem -Path \\SRV1\Installers\SoftwareV$Version

}

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

إضافة التحقق من المعلمات

هناك أنواع مختلفة من التحقق من المعلمات، ولكن بالنسبة لوظيفتك Install-Software، يعمل سمة التحقق من مجموعة القيم [ValidateSet بشكل أفضل. تمكن سمة التحقق من مجموعة القيم ValidateSet من تحديد قائمة قيم مسموح بها للمعلمة. إذا كنت تستهدف فقط السلسلة 1 أو 2، فيجب على المستخدم تحديد هذه القيم فقط؛ وإلا، ستفشل الوظيفة على الفور وتخطر المستخدم بالسبب.

أضف سمات التحقق من المعلمات داخل كتلة param، تحت كتلة المعلمة الأصلية كما هو موضح أدناه.

function Install-Software {
	param(
		[Parameter(Mandatory)]
		[ValidateSet('1','2')]
		[string]$Version
	)

	Get-ChildItem -Path \\SRV1\Installers\SoftwareV$Version

}

بإضافة مجموعة من العناصر (1 و 2) داخل الأقواس المتتابعة لسمة ValidateSet، يخبر هذا برنامج PowerShell أن القيم الصالحة فقط للمعلمة Version هي 1 أو 2. إذا حاول المستخدم تمرير شيء غير موجود في المجموعة، سيتلقون رسالة خطأ تُخطِرهم بأنهم لديهم عدد محدد من الخيارات المتاحة.

سمة ValidateSet هي سمة التحقق الشائعة، ولكن هناك سمات أخرى متاحة. للحصول على فهم كامل لجميع الطرق التي يمكن أن تُقيد بها قيم المعلمات، يُرجى الاطلاع على وثائق Microsoft.

قبول المدخلات من الأنابيب

حتى الآن، قمت بإنشاء وظيفة تحتوي على معلمة يمكن تمريرها فقط باستخدام بنية الجملة المعتادة -اسمالمعلمة <القيمة>. هذا يعمل ولكن لديك أيضًا خيار آخر لتمرير القيم إلى المعلمات باستخدام أنابيب PowerShell. دعونا نضيف إمكانات الأنابيب إلى وظيفة Install-Software الخاصة بنا.

ذات الصلة: قبول المدخلات من الأنابيب في مقالة معاملات ATA PowerShell

أولاً، أضف معاملًا آخر إلى الكود الخاص بك يحدد الكمبيوتر الذي ترغب في تثبيت البرنامج عليه. أضف أيضًا هذا المعامل إلى مرجعك Write-Host لمحاكاة التثبيت.

function Install-Software {
	param(
		[Parameter(Mandatory)]
		[string]$Version
		[ValidateSet('1','2')],
		
		[Parameter(Mandatory)]
		[string]$ComputerName
	)

	Write-Host "I installed software version $Version on $ComputerName. Yippee!"

}

بمجرد إضافة معامل ComputerName إلى الوظيفة ، يمكنك الآن تكرار أسماء الأجهزة في قائمة وتمرير قيم أسماء الأجهزة والإصدار إلى وظيفة Install-Software ، مثل ما يلي.

$computers = @("SRV1", "SRV2", "SRV3")
foreach ($pc in $computers) {
	Install-Software -Version 2 -ComputerName $pc
}

بدلاً من القيام بكل ذلك ، يجب أن تتعلم استخدام الأنبوبة بدلاً من ذلك.

جعل الوظيفة قابلة للتشغيل في الأنبوبة

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

A PowerShell function uses two kinds of pipeline input: ByValue (entire object) and ByPropertyName (a single object property). Here, because the $computers array contains only strings, you’ll pass those strings via ByValue.

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

function Install-Software {
	param(
		[Parameter(Mandatory)]
		[ValidateSet('1','2')]
		[string]$Version,

		[Parameter(Mandatory, ValueFromPipeline)]
		[string]$ComputerName
	)

	Write-Host "I installed software version $Version on $ComputerName. Yippee!"

}

بمجرد تحميل وظيفة التثبيت المحدثة Instal-Software ، اتصل بها على النحو التالي:

$computers = @("SRV1", "SRV2", "SRV3")
$computers | Install-Software -Version 2

قم بتشغيل النص مرة أخرى ، ويجب أن تحصل على شيء مشابه لهذا:

I installed software version 2 on SRV3. Yippee!

لاحظ أن Install-Software يتم تنفيذه فقط للسلسلة الأخيرة في المصفوفة. سترى كيفية إصلاح هذا في القسم التالي.

إضافة كتلة عملية

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

function Install-Software {
	param(
		[Parameter(Mandatory)]
		[ValidateSet('1','2')]
		[string]$Version,

		[Parameter(Mandatory, ValueFromPipeline)]
		[string]$ComputerName
	)

	process {
		Write-Host "I installed software version $Version on $ComputerName. Yippee!"
	}
}

الآن قم بنداء الوظيفة مرة أخرى تمامًا كما فعلت سابقًا. ستعود وظيفة “تثبيت البرنامج” الآن بثلاثة أسطر (واحدة لكل كائن).

I installed software version 2 on SRV1. Yippee!
I installed software version 2 on SRV2. Yippee!
I installed software version 2 on SRV3. Yippee!

كتلة process تحتوي على الشفرة الرئيسية التي ترغب في تنفيذها. يمكنك أيضًا استخدام كتل “begin” و “end” للشفرة التي ستتم تنفيذها في بداية ونهاية استدعاء الوظيفة. يمكنك معرفة المزيد عن كتل “begin” و “process” و “end” من خلال وثائق Microsoft.

الخطوات التالية

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

I now challenge you to look through some old scripts and see where you can add a PowerShell function. Look for patterns in code. Build a function from those patterns. Notice where you’re copying/pasting code snippets and turn those into PowerShell functions!