PowerShell@2 - مهمة PowerShell v2

استخدم هذه المهمة لتشغيل برنامج نصي PowerShell على Linux أو macOS أو Windows.

ملاحظة

بشكل افتراضي، يستخدم PowerShell v2 PowerShell Core لوكلاء Linux Windows PowerShell لوكلاء Windows. لاستخدام أحدث إصدار من PowerShell على وكلاء Windows، قم بتعيين المعلمة pwsh إلى true. سيتم بعد ذلك استخدام PowerShell Core بدلا من ذلك.

بناء الجملة

# PowerShell v2
# Run a PowerShell script on Linux, macOS, or Windows.
- task: PowerShell@2
  inputs:
    #targetType: 'filePath' # 'filePath' | 'inline'. Type. Default: filePath.
    filePath: # string. Required when targetType = filePath. Script Path. 
    #arguments: # string. Optional. Use when targetType = filePath. Arguments. 
    #script: # string. Required when targetType = inline. Script. 
  # Preference Variables
    #errorActionPreference: 'stop' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
    #warningPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. WarningPreference. Default: default.
    #informationPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. InformationPreference. Default: default.
    #verbosePreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. VerbosePreference. Default: default.
    #debugPreference: 'default' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. DebugPreference. Default: default.
    #progressPreference: 'silentlyContinue' # 'default' | 'stop' | 'continue' | 'silentlyContinue'. ProgressPreference. Default: silentlyContinue.
  # Advanced
    #failOnStderr: false # boolean. Fail on Standard Error. Default: false.
    #showWarnings: false # boolean. Show warnings as Azure DevOps warnings. Default: false.
    #ignoreLASTEXITCODE: false # boolean. Ignore $LASTEXITCODE. Default: false.
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #workingDirectory: # string. Working Directory. 
    #runScriptInSeparateScope: false # boolean. Run script in the separate scope. Default: false.

الإدخالات

targetType - نوع
string. القيم المسموح بها: filePath (مسار الملف)، inline. القيمة الافتراضية: filePath.

يحدد نوع البرنامج النصي للمهمة المراد تشغيلها: برنامج نصي مضمن أو مسار إلى .ps1 ملف.

filePath - مسار البرنامج النصي
string. مطلوب عند targetType = filePath.

يحدد مسار البرنامج النصي المراد تنفيذه. يجب أن يكون مسارا مؤهلا بالكامل أو بالنسبة إلى $(System.DefaultWorkingDirectory).

arguments - الحجج
string. ‏‏اختياري. استخدم عندما targetType = filePath.

يحدد الوسيطات التي تم تمريرها إلى البرنامج النصي PowerShell. يمكن أن تكون الوسيطات معلمات ترتيبية أو معلمات مسماة. على سبيل المثال، ⁧-Name someName -Path -Value "Some long string value"⁩.

arguments لا يتم استخدامه عند targetType تعيين إلى inline.

script - البرنامج النصي
string. مطلوب عند targetType = inline. القيمة الافتراضية: # Write your PowerShell commands here.\n\nWrite-Host "Hello World".

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

errorActionPreference - ErrorActionPreference
string. القيم المسموح بها: default، stop، continue، silentlyContinue. القيمة الافتراضية: stop.

إلحاق السطر $ErrorActionPreference = 'VALUE' في أعلى البرنامج النصي الخاص بك.

warningPreference - تحذيرPreference
string. القيم المسموح بها: default، stop، continue، silentlyContinue. القيمة الافتراضية: default.

عند عدم التعيين إلى Default، يقوم بإيقاف السطر $WarningPreference = 'VALUE' في أعلى البرنامج النصي الخاص بك.

informationPreference - InformationPreference
string. القيم المسموح بها: default، stop، continue، silentlyContinue. القيمة الافتراضية: default.

عند عدم التعيين إلى Default، يقوم بإيقاف السطر $InformationPreference = 'VALUE' في أعلى البرنامج النصي الخاص بك.

verbosePreference - VerbosePreference
string. القيم المسموح بها: default، stop، continue، silentlyContinue. القيمة الافتراضية: default.

عند عدم التعيين إلى Default، يقوم بإيقاف السطر $VerbosePreference = 'VALUE' في أعلى البرنامج النصي الخاص بك.

debugPreference - تتبع الأخطاء
string. القيم المسموح بها: default، stop، continue، silentlyContinue. القيمة الافتراضية: default.

عند عدم التعيين إلى Default، يقوم بإيقاف السطر $DebugPreference = 'VALUE' في أعلى البرنامج النصي الخاص بك.

progressPreference - تقدم التفوق
string. القيم المسموح بها: default، stop، continue، silentlyContinue. القيمة الافتراضية: silentlyContinue.

عند عدم التعيين إلى Default، يقوم بإيقاف السطر $ProgressPreference = 'VALUE' في أعلى البرنامج النصي الخاص بك.

failOnStderr - فشل عند الخطأ القياسي
boolean. القيمة الافتراضية: false.

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

showWarnings - إظهار التحذيرات كتحذيرات Azure DevOps
boolean. القيمة الافتراضية: false.

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

ignoreLASTEXITCODE - تجاهل $LASTEXITCODE
boolean. القيمة الافتراضية: false.

إذا تم تعيين القيمة إلى false، يتم إلحاق السطر if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } بنهاية البرنامج النصي الخاص بك. سيؤدي هذا إلى نشر التعليمة البرمجية للخروج الأخير من أمر خارجي كتعلم برمجي للخروج من powershell. وإلا، لا يتم إلحاق السطر بنهاية البرنامج النصي الخاص بك.

pwsh - استخدام PowerShell Core
boolean. القيمة الافتراضية: false.

إذا كان هذا صحيحا، فستستخدم pwsh.exe المهام التي تعمل على وكلاء Windows من المسار بدلا من powershell.exe.

workingDirectory - دليل العمل
string.

يحدد دليل العمل حيث يتم تشغيل البرنامج النصي. إذا لم يتم تحديد قيمة، فإن دليل العمل هو $(Build.SourcesDirectory).

runScriptInSeparateScope - تشغيل البرنامج النصي في نطاق منفصل
boolean. القيمة الافتراضية: false.

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

خيارات التحكم بالمهمة

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

متغيرات الإخراج

لا شيء

الملاحظات

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

اختصارات المهام

PowerShell@2 يحتوي على اختصارين في YAML: steps.powershell و steps.pwsh.

• powershellيعمل باستخدام إما Windows PowerShell (على Windows) أو pwsh (Linux وmacOS).
• pwsh يشغل PowerShell Core، الإصدار عبر الأنظمة الأساسية من PowerShell المبني على .NET Core.

steps:
- powershell: # Run a script in Windows PowerShell on Windows, and pwsh on Linux and macOS.
- pwsh: # Run a script in PowerShell Core on Windows, macOS, and Linux.

تعيين متغير بحيث يمكن قراءته بواسطة البرامج النصية والمهام اللاحقة

لمعرفة المزيد حول تعريف متغيرات البناء في برنامج نصي، راجع تعريف متغيرات البناء وتعديلها في برنامج نصي.

لمعرفة المزيد حول تعريف متغيرات الإصدار في برنامج نصي، راجع تعريف متغيرات الإصدار وتعديلها في برنامج نصي.

تمرير أسرار البنية الأساسية لبرنامج ربط العمليات التجارية في البرنامج النصي، ولكن البيانات السرية غير مخفية في سجلات البنية الأساسية لبرنامج ربط العمليات التجارية

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

./script.ps1 --arg1 value1 --arg2 <some_secret_which_will_be_masked_here>

قد يكون هناك استثناء مثل: At <path_to_temp_script_file>:4 char:3

+   ./script.ps1 --arg1 value1 --arg2 <unmasked_part_of_original_secret> ...
+   ~~~~~~~~~~
    + <Additional exception details>

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

أمثلة

• استدعاء برنامج نصي من ملف
• كتابة تحذير
• كتابة خطأ
• استدعاء برنامج PowerShell النصي باستخدام وسيطات متعددة

استدعاء برنامج نصي من ملف

فيما يلي نموذج لملف PowerShell المسمى test.ps1 موجود في جذر المستودع الخاص بك.

Write-Host "Hello World from $Env:AGENT_NAME."
Write-Host "My ID is $Env:AGENT_ID."
Write-Host "AGENT_WORKFOLDER contents:"
gci $Env:AGENT_WORKFOLDER
Write-Host "AGENT_BUILDDIRECTORY contents:"
gci $Env:AGENT_BUILDDIRECTORY
Write-Host "BUILD_SOURCESDIRECTORY contents:"
gci $Env:BUILD_SOURCESDIRECTORY
Write-Host "Over and out."

يمكنك استدعاء هذا البرنامج النصي في البنية الأساسية لبرنامج ربط العمليات التجارية الخاصة بك مثل هذا.

steps:
- task: PowerShell@2
  inputs:
    targetType: 'filePath'
    filePath: 'test.ps1'

كتابة تحذير

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: Write-Host "##vso[task.LogIssue type=warning;]This is the warning"
    # Writes a warning to build summary and to log in yellow text

كتابة خطأ

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: Write-Host "##vso[task.LogIssue type=error;]This is the error"
    # Writes an error to build summary and to log in red text

إذا كنت تريد أن يفشل هذا الخطأ في البنية، أضف exit 1 إلى البرنامج النصي.

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host "##vso[task.LogIssue type=error;]This is the error"
      exit 1
    # Writes an error to build summary and to log in red text

استدعاء برنامج PowerShell النصي باستخدام وسيطات متعددة

إنشاء برنامج PowerShell النصي test2.ps1:

param ($input1, $input2)
Write-Host "$input1 $input2"

في البنية الأساسية لبرنامج ربط العمليات التجارية YAML، اتصل:

- task: PowerShell@2
  inputs:
    targetType: 'filePath'
    filePath: $(System.DefaultWorkingDirectory)\test2.ps1
    arguments: > # Use this to avoid newline characters in multiline string
      -input1 "Hello"
      -input2 "World"
  displayName: 'Print Hello World'

المتطلبات

المتطلبات	الوصف
أنواع البنية الأساسية لبرنامج ربط العمليات التجارية	YAML، الإصدار الكلاسيكي، الإصدار الكلاسيكي
يعمل على	Agent, DeploymentGroup
المطالب	بلا
القدرات	لا تفي هذه المهمة بأي متطلبات للمهام اللاحقة في الوظيفة.
قيود الأوامر	أي
متغيرات Settable	أي
إصدار الوكيل	2.115.0 أو أحدث
فئة المهمة	الأداة المساعدة

راجع أيضًا

• استخدم برنامج PowerShell النصي لتخصيص البنية الأساسية لبرنامج ربط العمليات التجارية الخاصة بك - ApplyVersionToAssemblies.ps1
• تعرف على المزيد حول برامج PowerShell النصية
  • البرمجة النصية باستخدام Windows PowerShell
  • Microsoft Script Center (رجال البرمجة النصية)
  • PowerShell.org