إدارة الوحدات في التنفيذ التلقائي في Azure

إشعار

ابتداء من 1 فبراير 2025، سيبدأ التنفيذ التلقائي في Azure تنفيذ جميع دفاتر التشغيل التي تستخدم وحدات AzureRM disstop c1disstop/c1. بدءا من 1 نوفمبر 2024، لن تتمكن من إنشاء دفاتر تشغيل جديدة باستخدام وحدات AzureRM النمطية. تم إهمال وحدة AzureRM PowerShell النمطية رسميا اعتبارا من 29 فبراير 2024. نوصيك بالترحيل من الوحدة النمطية AzureRM إلى الوحدة النمطية Az PowerShell لضمان استمرار الدعم والتحديثات. بينما قد لا تزال الوحدة النمطية AzureRM تعمل، فإنه لم يعد يتم صيانتها أو دعمها، كما أن الاستخدام المستمر للوحدة النمطية AzureRM على مسؤوليته الخاصة. لمزيد من المعلومات، راجع موارد الترحيل للحصول على إرشادات حول الانتقال إلى الوحدة النمطية Az.

يستخدم التنفيذ التلقائي في Azure عددا من وحدات PowerShell لتمكين cmdlets في دفاتر التشغيل وموارد DSC في تكوينات DSC. تتضمن الوحدات النمطية المدعومة ما يلي:

• Azure PowerShell Az modules.
• وحدات PowerShell نمطية أخرى.
• الوحدة النمطية الداخلية Orchestrator.AssetManagement.Cmdlets (غير متوفرة على Linux Hybrid Runbook Worker).
• وحدات Python 2 و Python 3.
• الوحدات النمطية المخصصة التي تقوم بإنشائها.

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

هام

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

بيئات الاختبار المعزولة

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

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

نظرًا إلى عدد الوحدات النمطية وأوامر cmdlets المضمنة، من الصعب معرفة أي من أوامر cmdlets ستجري مكالمات غير مدعومة مسبقًا. بوجه عام، لقد لاحظنا مشكلات في أوامر cmdlets التي تتطلب وصولاً مرتفعًا، أو تتطلب بيانات اعتماد كمعلمة، أو أوامر cmdlets المتعلقة بالشبكات. أي cmdlets التي تقوم بعمليات شبكة كاملة غير مدعومة في صندوق الرمل، بما في ذلك Connect-AipService من وحدة AIPService PowerShell وResolve-DnsName من وحدة DNSClient.

هذه هي القيود المعروفة مع بيئة الاختبار المعزولة. الحل المناسب هو نشر <عامل دفتر التشغيل الهجين> أو استخدام دالات Azure.

هام

لا تقم بتضمين الكلمة الأساسية "AzureRm" في أي برنامج نصي مُصمم ليتم تنفيذه مع الوحدة Az. قد يؤدي تضمين الكلمة الأساسية، حتى في تعليق، إلى تحميل AzureRm ومن ثم تعارضه مع الوحدة النمطية Az.

الوحدات النمطية الافتراضية

تحتوي جميع حسابات "Automation" الجديدة على أحدث إصدار من الوحدة النمطية PowerShell Az يتم استيرادها افتراضيًا. وحدة Az تحل محل AzureRM وهي الوحدة الموصى بها للاستخدام مع Azure. تتضمن الوحدات النمطية الافتراضية في حساب Automation الجديد 24 وحدة AzureRM النمطية وأكثر من 60 وحدة نمطية من Azure.

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

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

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

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

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

تُعرف الوحدات الافتراضية أيضًا بالوحدات النمطية العمومية. في بوابة Azure، ستكون خاصية Global moduletrue عند عرض وحدة تم استيرادها عند إنشاء الحساب.

إشعار

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

اسم الوحدة النمطية	إصدار
Az.*	انظر القائمة الكاملة تحت تفاصيل الطرود على PowerShell Gallery
AuditPolicyDsc	1.1.0.0
Azure	1.0.3
Azure. التخزين	1.0.3
AzureRM.Automation	1.0.3
AzureRM.Compute	1.2.1
AzureRM.Profile	1.0.3
AzureRM.Resources	1.0.3
AzureRM.Sql	1.0.3
AzureRM.Storage	1.0.3
ComputerManagementDsc	5.0.0.0
GPRegistryPolicyParser	0.2
Microsoft. PowerShell.Core	1
Microsoft. PowerShell.Diagnostics
Microsoft. PowerShell.Management
Microsoft. PowerShell.Security
Microsoft. PowerShell.Utility
Microsoft. إدارة WSMan
Orchestrator.AssetManagement.Cmdlets	1
مصادر PSDsc	2.9.0.0
SecurityPolicyDsc	2.1.0.0
مصادر حوسبة الحالة	1
xDSCDomainjoin	1.1
xPowerShellExecutionPolicy	1.1.0.0
xRemoteDesktopAdmin	1.1.0.0

أوامر cmdlets الداخلية

يوفر التنفيذ التلقائي في Azure منافذ تشغيل داخلية متاحة حصريا عند تنفيذ دفاتر التشغيل في بيئة Azure sandbox أو على Windows Hybrid Runbook Worker. وحدة Orchestrator.AssetManagement.Cmdlets، التي تحتوي على هذه ال cmdlets الداخلية، مثبتة افتراضيا في حساب الأتمتة الخاص بك وتحديدا عند تثبيت دور عامل الكتب التشغيلية الهجين Windows على جهاز Windows.

إشعار

هذه الوظيفة غير متوفرة على Linux Hybrid Runbook Workers.

يحدد الجدول التالي أوامر cmdlets الداخلية. تم تصميم هذه الأوامر لتستخدم بدلا من Azure PowerShell cmdlets للتفاعل مع موارد حساب الأتمتة الخاص بك. يمكنها استرداد الأسرار من المتغيرات المشفرة وبيانات الاعتماد والاتصالات المشفرة.

اسم	‏‏الوصف
Get-AutomationCertificate	Get-AutomationCertificate [-Name] <string> [<CommonParameters>]
Get-AutomationConnection	Get-AutomationConnection [-Name] <string> [-DoNotDecrypt] [<CommonParameters>]
Get-AutomationPSCredential	Get-AutomationPSCredential [-Name] <string> [<CommonParameters>]
Get-AutomationVariable	Get-AutomationVariable [-Name] <string> [-DoNotDecrypt] [<CommonParameters>]
Set-AutomationVariable	Set-AutomationVariable [-Name] <string> -Value <Object> [<CommonParameters>]
Start-AutomationRunbook	Start-AutomationRunbook [-Name] <string> [-Parameters <IDictionary>] [-RunOn <string>] [-JobId <guid>] [<CommonParameters>]
Wait-AutomationJob	Wait-AutomationJob -Id <guid[]> [-TimeoutInMinutes <int>] [-DelayInSeconds <int>] [-OutputJobsTransitionedToRunning] [<CommonParameters>]

لاحظ أن أوامر cmdlets الداخلية تختلف في التسمية عن أوامر cmdlet Az وAzureRM. أسماء ال cmdlet الداخلية لا تحتوي على كلمات مثل Azure أو Az في الاسم، لكنها تستخدم كلمة Automation. نوصي باستخدامها بدلا من استخدام أوامر Az أو AzureRM أثناء تنفيذ الكتب التشغيلية في صندوق Azure أو على عامل Runbook الهجين على Windows لأنها تتطلب معلمات أقل وتعمل في سياق وظيفتك أثناء التنفيذ.

استخدم AzureRM cmdlets لمعالجة موارد Automation خارج سياق دليل التشغيل.

وحدات Python

يمكنك إنشاء دفاتر تشغيل Python 2 في التنفيذ التلقائي في Azure. للحصول على معلومات عن Python وحدة، راجع إدارة Python حزمتين في التنفيذ التلقائي في Azure.

الوحدات النمطية المخصصة

يدعم التنفيذ التلقائي في Azure وحدات PowerShell المخصصة التي تنشئها لاستخدامها مع دفاتر التشغيل وتكوينات DSC. أحد أنواع الوحدات المخصصة هو وحدة تكامل تحتوي اختياريًا على ملف بيانات التعريف لتحديد الوظيفة المخصصة للوحدات cmdlets. يتم توفير مثال على استخدام وحدة تكامل في إضافة نوع اتصال.

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

الترحيل إلى الوحدات النمطية Az

يوضح هذا القسم كيفية الترحيل إلى الوحدات النمطية لـ Az في Automation. لمزيد من المعلومات، راجع Migrationrate Azure PowerShell من AzureRM إلى Az.

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

إشعار

عند إنشاء حساب Automation جديد، حتى بعد الترحيل إلى وحدات Az النمطية، سيستمر Automation في تثبيت وحدات AzureRM النمطية بشكل افتراضي.

اختبار دلائل التشغيل وتكوينات DSC قبل ترحيل الوحدة النمطية

تأكد من اختبار جميع دلائل التشغيل وتكوينات DSC بعناية، في حساب أتمتة Automation، قبل الترحيل إلى الوحدات النمطية لـ Az.

إيقاف كافة دلائل التشغيل التي تستخدم الوحدات النمطية AzureRM وإلغاء جدولتها

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

عندما تكون مستعدا لإزالة جداولك، يمكنك استخدام بوابة Azure أو Remove-AzAutomationSchedule cmdlet. راجع إزالة جدول.

إزالة الوحدات النمطية AzureRM

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

استيراد وحدات Az

لا يؤدي استيراد وحدة Az إلى حساب Automation الخاص بك إلى استيراد الوحدة تلقائيًا إلى جلسة PowerShell التي تستخدمها دلائل التشغيل. يتم استيراد الوحدات النمطية إلى جلسة عمل PowerShell في الحالات التالية:

• عندما يستدعي دليل التشغيل أمر cmdlet من وحدة نمطية.
• عند استيراد دليل تشغيل الوحدة النمطية بشكل صريح مع cmdlet وحدة الاستيراد.
• عند استيراد دليل تشغيل الوحدة النمطية بشكل صريح من خلال عبارة وحدة الاستيراد. يدعم بيان الاستخدام بدءا من Windows PowerShell 5.0 ويدعم استيراد الفئات ونوع enum.
• عندما يستورد دليل التشغيل وحدة نمطية غير مستقلة.

يمكنك استيراد وحدات Az إلى حساب الأتمتة من بوابة Azure. نظرًا إلى أن Az.Accounts هي تبعية لوحدات Az الأخرى، فتأكد من استيراد هذه الوحدة قبل أي وحدات أخرى.

إشعار

مع إدخال دعم PowerShell 7.1 (إصدار أولي)، تم تحديث الخيار معرض الاستعراض مع التغييرات التالية:

• معرض الاستعراض متاح على جزء أتمتة العمليات>الوحدات.
• تعرض صفحة الوحدات النمطية عمودين جديدين - إصدار الوحدة النمطية وإصدار وقت التشغيل

1. سجل الدخول إلى Azure portal.

2. ابحث عن حسابات Automation وحددها.

3. في صفحة Automation Accounts، حدد حساب Automation من القائمة.

4. من حساب Automation، ضمن Shared Resources، حدد Modules.

5. حدد Add a module (إضافة وحدة نمطية). في الصفحة Add a module، يمكنك تحديد أي من الخيارات التالية:

   1. استعراض من الملف - يمكنك تحديد ملف من الكمبيوتر المحلي.
   2. استعراض من المعرض - يمكنك استعراض وتحديد دليل التشغيل الحالي من المعرض.

6. انقر فوق Select لتحديد وحدة نمطية.

7. حدد Runtime version وانقر فوق Import.

   

8. في الصفحة Modules، يمكنك عرض الوحدة النمطية التي تم استيرادها ضمن حساب Automation.

يمكنك أيضا إجراء هذا الاستيراد من خلال PowerShell Gallery، بالبحث عن الوحدة التي يجب استيرادها. عندما تجد الوحدة، حددها، واختر تبويب التنفيذ التلقائي في Azure. اختر Deploy إلى التنفيذ التلقائي في Azure.

اختبار دلائل التشغيل لديك

بعد قيامك باستيراد الوحدات النمطية Az إلى حساب Automation، يمكنك البدء في تحرير دلائل التشغيل وتكوينات DSC لاستخدام الوحدات النمطية الجديدة. تتمثل إحدى طرق اختبار تعديل دليل التشغيل لاستخدام أوامر cmdlets الجديدة في استخدام الأمر Enable-AzureRmAlias -Scope Process الموجود في بداية دليل التشغيل. بإضافة هذا الأمر إلى دليل التشغيل الخاص بك، يمكن تشغيل البرنامج النصي بدون تغييرات.

وحدات المنشئ النمطية

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

لمعرفة المزيد حول إنشاء وحدة PowerShell النمطية، راجع كيفية كتابة وحدة البرنامج النصي النمطية لـ PowerShell.

مجلد الإصدار

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

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

TestModule
   1.0.0
   2.0.0

داخل كل مجلد من مجلدات الإصدار، انسخ ملفات PowerShell .psm1 أو .psd1 أو ملفات الوحدة النمطية PowerShell .dll التي تشكل وحدة نمطية في مجلد الإصدار المعني. قم بضغط مجلد الوحدة بحيث يمكن التنفيذ التلقائي في Azure استيراده كملف .zip واحد. بينما تعرض الأتمتة نسخة واحدة فقط من الوحدات المستوردة، إذا كانت حزمة الوحدة تحتوي على نسخ متجاورة من الوحدة، فهي جميعها متاحة للاستخدام في دفاتر التشغيل أو إعدادات DSC.

بينما تدعم الأتمتة وحدات تحتوي على نسخ متجاورة ضمن نفس الحزمة، إلا أنها لا تدعم استخدام عدة إصدارات من الوحدة عبر استيراد حزم الوحدة. على سبيل المثال، يمكنك استيراد الوحدة النمطية "أ"، التي تحتوي على الإصدارين 1 و2 إلى حساب Automation الخاص بك. يمكنك لاحقًا تحديث الوحدة النمطية "أ" لتشمل الإصدارين 3 و4، عندما تقوم بالاستيراد إلى حساب Automation لديك، يمكن استخدام الإصدارين 3 و4 فقط في أي دلائل تشغيل أو تكوينات DSC. إذا كنت تريد توفر كل الإصدارات - 1 و2 و3 و4، يجب أن يحتوي ملف .zip على الإصدارات 1 و2 و3 و4.

إذا كنت ستستخدم إصدارات مختلفة من الوحدة نفسها بين دلائل التشغيل، يجب عليك دائمًا إعلان الإصدار الذي تريد استخدامه في دليل التشغيل الخاص بك باستخدام cmdlet Import-Module وتضمين المعلمة-RequiredVersion <version>. حتى إذا كان الإصدار الذي تريد استخدامه هو أحدث إصدار. هذا لأن وظائف دليل التشغيل قد تعمل في بيئة الاختبار المعزولة نفسها. إذا قامت بيئة الاختبار المعزولة بالفعل بتحميل وحدة نمطية برقم إصدار معين بشكل صريح، نظرًا إلى أن المهمة السابقة في بيئة الاختبار المعزولة هذه قالت إنها تفعل ذلك، فلن تقوم الوظائف المستقبلية في بيئة الاختبار المعزولة هذه بتحميل أحدث إصدار من هذه الوحدة تلقائيًا. وذلك لأن بعض النسخ منه قد تم تحميلها بالفعل في عالم الرمل.

بالنسبة إلى مورد DSC، استخدم الأمر التالي لتحديد إصدار معين:

Import-DscResource -ModuleName "<ModuleName>" -ModuleVersion "<version>"

معلومات التعليمات

قم بتضمين ملخص ووصف ومسؤول URI لكل أمر cmdlet في الوحدة النمطية الخاصة بك. في PowerShell، يمكنك تحديد معلومات التعليمات لأوامر cmdlets باستخدام الأمر cmdlet Get-Help. يوضح المثال التالي كيفية تحديد الملخص ومساعدة URI في ملف الوحدة النمطية .psm1.

<#
     .SYNOPSIS
      Gets a Contoso User account
#>
function Get-ContosoUser {
[CmdletBinding](DefaultParameterSetName='UseConnectionObject', `
HelpUri='https://www.contoso.com/docs/information')]
[OutputType([String])]
param(
   [Parameter(ParameterSetName='UserAccount', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [string]
   $UserName,

   [Parameter(ParameterSetName='UserAccount', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [string]
   $Password,

   [Parameter(ParameterSetName='ConnectionObject', Mandatory=true)]
   [ValidateNotNullOrEmpty()]
   [Hashtable]
   $Connection
)

switch ($PSCmdlet.ParameterSetName) {
   "UserAccount" {
      $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $UserName, $Password
      Connect-Contoso -Credential $cred
   }
   "ConnectionObject" {
      Connect-Contoso -Connection $Connection
  }
}
}

يؤدي توفير هذه المعلومات إلى إظهار نص التعليمات عبر الأمر cmdlet Get-Help في وحدة تحكم PowerShell. هذا النص معروض أيضا في بوابة Azure.

نوع الاتصال

إذا كانت الوحدة النمطية تتصل بخدمة خارجية، فحدد نوع الاتصال باستخدام وحدة تكامل مخصصة. يجب أن يقبل كل أمر cmdlet في الوحدة النمطية مثيلاً لنوع الاتصال هذا (كائن اتصال) كمعامل. يقوم المستخدمون بتعيين معلمات أصل الاتصال إلى المعلمات المقابلة لأمر cmdlet في كل مرة يستدعون فيها الأمر cmdlet.

يستخدم مثال دليل التشغيل التالي أصل اتصال Contoso يسمى ContosoConnection للوصول إلى موارد Contoso وإرجاع البيانات من الخدمة الخارجية. في هذا المثال، يتم تعيين الحقول إلى خصائص UserName وPassword الخاصة بالكائن PSCredential ثم تمريرها إلى cmdlet.

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $contosoConnection.UserName, $contosoConnection.Password
Connect-Contoso -Credential $cred
}

تتمثل الطريقة الأسهل والأفضل للتعامل مع هذا السلوك في تمرير كائن الاتصال مباشرة إلى الأمر cmdlet:

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

Connect-Contoso -Connection $contosoConnection
}

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

نوع الإخراج

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

قم بإضافة [OutputType([<MyOutputType>])]، حيث يكون MyOutputType نوعًا صالحًا. لمعرفة المزيد حول OutputType، راجع حول الدالات OutputTypeAttribute. التعليمات البرمجية التالية مثال لإضافة OutputType إلى cmdlet:

function Get-ContosoUser {
[OutputType([String])]
param(
   [string]
   $Parameter1
)
# <script location here>
}

يشبه هذا السلوك وظيفة "الكتابة مسبقًا" لإخراج cmdlet في بيئة خدمة تكامل PowerShell، دون الحاجة إلى تشغيلها.

حالة Cmdlet

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

$globalNum = 0
function Set-GlobalNum {
   param(
       [int] $num
   )

   $globalNum = $num
}
function Get-GlobalNumTimesTwo {
   $output = $globalNum * 2

   $output
}

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

تأكد من أن الوحدة النمطية مضمنة بالكامل في حزمة يمكن نسخها باستخدام xcopy. يتم توزيع وحدات الأتمتة على بيئات الاختبار المعزولة لـ Automation عند تنفيذ دلائل التشغيل. يجب أن تعمل الوحدات النمطية بشكل مستقل عن المضيف الذي يديرها.

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

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

مسارات ملفات الوحدة النمطية

تأكد من أن كل الملفات في الوحدة تحتوي على مسارات بها أقل من 140 حرفًا. تتسبب أي مسارات يزيد طولها عن 140 حرفًا في حدوث مشكلات في استيراد دلائل التشغيل. لا يمكن لـ Automation استيراد ملف بحجم مسار يزيد عن 140 حرفًا إلى جلسة PowerShell باستخدامImport-Module.

استيراد الوحدات النمطية

يحدد هذا القسم عدة طرق يمكنك من خلالها استيراد وحدة نمطية إلى حساب Automation لديك.

استيراد الوحدات في بوابة Azure

لاستيراد وحدة في بوابة Azure:

1. في المدخل، ابحث عن ⁧⁩Automation Accounts⁧⁩ وحددها.
2. في صفحة Automation Accounts، حدد حساب Automation من القائمة.
3. ضمن Shared Resources، حدد Modules.
4. حدد Add a module (إضافة وحدة نمطية).
5. حدد ملف .zip الذي يحتوي على الوحدة النمطية.
6. حدد OK لبدء عملية الاستيراد.

استيراد الوحدات النمطية باستخدام PowerShell

يمكنك استخدام cmdlet جديد AzAutomationModule لاستيراد وحدة نمطية إلى حساب Automation الخاص بك. يأخذ الأمر cmdlet عنوان URL لحزمة .zip للوحدة النمطية.

$moduleName = "<ModuleName>"
$contentLinkUri = "<ModuleUri>"
$runtimeVersion = "<RuntimeVersion>" # 5.1 or 7.2
$resourceGroupName = "<ResourceGroupName>"
$automationAccountName = "<AutomationAccountName>"
New-AzAutomationModule -Name $moduleName -RuntimeVersion $runtimeVersion -ContentLinkUri $contentLinkUri -ResourceGroupName $resourceGroupName -AutomationAccountName $automationAccountName

يمكنك أيضا استخدام نفس cmdlet لاستيراد وحدة من PowerShell Gallery مباشرة. تأكد من أخذ ModuleName و ModuleVersion من PowerShell Gallery.

$moduleName = "<ModuleName>"
$moduleVersion = "<ModuleVersion>"
$runtimeVersion = "<RuntimeVersion>" # 5.1 or 7.2
$resourceGroupName = "<ResourceGroupName>"
$automationAccountName = "<AutomationAccountName>"
New-AzAutomationModule -AutomationAccountName $automationAccountName -RuntimeVersion $runtimeVersion -ResourceGroupName $resourceGroupName -Name $moduleName -ContentLinkUri "https://www.powershellgallery.com/api/v2/package/$moduleName/$moduleVersion"

استيراد الوحدات من PowerShell Gallery

يمكنك استيراد وحدات PowerShell Gallery إما مباشرة من المعرض أو من حساب الأتمتة الخاص بك.

لاستيراد وحدة مباشرة من PowerShell Gallery:

1. انتقل إلى https://www.powershellgallery.com وابحث عن الوحدة النمطية للاستيراد.
2. تحت خيارات التثبيت، في تبويب التنفيذ التلقائي في Azure، اختر Deploy to التنفيذ التلقائي في Azure. هذا الإجراء يفتح بوابة Azure.
3. في صفحة الاستيراد، حدد حساب Automation الخاص بك، ثم اختر OK.

لاستيراد وحدة PowerShell Gallery مباشرة من حساب الأتمتة الخاص بك:

1. في المدخل، ابحث عن ⁧⁩Automation Accounts⁧⁩ وحددها.
2. في صفحة Automation Accounts، حدد حساب Automation من القائمة.
3. ضمن Shared Resources، حدد Modules.
4. حدد Browse gallery، ثم ابحث في المعرض عن وحدة نمطية.
5. حدد الوحدة المراد استيرادها، وحدد Import.
6. حدد OK لبدء عملية الاستيراد.

حذف الوحدات النمطية

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

حذف الوحدات في بوابة Azure

لإزالة وحدة في بوابة Azure:

1. في المدخل، ابحث عن ⁧⁩Automation Accounts⁧⁩ وحددها.
2. في صفحة Automation Accounts، حدد حساب Automation من القائمة.
3. ضمن Shared Resources، حدد Modules.
4. حدد الوحدة النمطية التي تريد إزالتها.
5. في صفحة الوحدة النمطية، حدد Delete. إذا كانت هذه الوحدة إحدى الوحدات النمطية الافتراضية، فإنها تعود إلى الإصدار الذي كان موجودًا عند إنشاء حساب Automation.

حذف الوحدات النمطية باستخدام PowerShell

لإزالة وحدة نمطية من خلال PowerShell، قم بتشغيل الأمر التالي:

Remove-AzAutomationModule -Name <moduleName> -AutomationAccountName <automationAccountName> -ResourceGroupName <resourceGroupName>

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

• لمزيد من المعلومات حول استخدام وحدات Azure PowerShell، راجع ابدأ مع Azure PowerShell.

• لمعرفة المزيد حول إنشاء وحدات PowerShell، راجع كتابة وحدة Windows PowerShell.

• لحل المشكلات المتعلقة بالموارد المشتركة مثل Azure PowerShell و Python وcmdlet الداخلي والوحدات المخصصة في عام التنفيذ التلقائي في Azure، انظر Troubleshoot التنفيذ التلقائي في Azure مشاكل الموارد المشتركة.