管理 Azure 自动化中的模块Manage modules in Azure Automation

Azure 自动化使用许多 PowerShell 模块在 runbook DSC 配置中启用 runbook 和 DSC 资源中的 cmdlet。Azure Automation uses a number of PowerShell modules to enable cmdlets in runbooks and DSC resources in DSC configurations. 支持的模块包括:Supported modules include:

创建自动化帐户时,Azure 自动化默认导入一些模块。When you create an Automation account, Azure Automation imports some modules by default. 请参阅默认模块See Default modules.

沙盒Sandboxes

当自动化执行 runbook 和 DSC 编译作业时,它会将模块加载到沙盒中,其中 runbook 可以运行,并且 DSC 配置可以编译。When Automation executes runbook and DSC compilation jobs, it loads the modules into sandboxes where the runbooks can run and the DSC configurations can compile. 自动化还自动将任何 DSC 资源放置到 DSC 拉取服务器上的模块中。Automation also automatically places any DSC resources in modules on the DSC pull server. 计算机在应用 DSC 配置时可以提取资源。Machines can pull the resources when they apply the DSC configurations.

备注

请务必仅导入 runbook 和 DSC 配置所需的模块。Be sure to import only the modules that your runbooks and DSC configurations require. 建议不要导入根 Az 模块。We don't recommend importing the root Az module. 它包括可能不需要的许多其他模块,这可能导致性能问题。It includes many other modules that you might not need, which can cause performance problems. 改为导入单个模块,如 Az.Compute。Import individual modules, such as Az.Compute, instead.

云沙盒最多支持 48 个系统调用,并出于安全原因限制所有其他调用。Cloud sandbox supports a maximum of 48 system calls, and restricts all other calls for security reasons. 云沙盒不支持其他功能,例如凭据管理和某些网络连接。Other functionality such as credential management and some networking is not supported in the cloud sandbox.

由于包含的模块和 cmdlet 数量众多,因此很难事先知道哪个 cmdlet 会进行不受支持的调用。Due to the number of modules and cmdlets included, it's difficult to know beforehand which of the cmdlets will make unsupported calls. 通常,对于需要提升的访问权限以及需要凭据作为参数的 cmdlet,或者对于与网络相关的 cmdlet,我们都知道其问题所在。Generally, we have seen issues with cmdlets which require elevated access, require a credential as a parameter, or cmdlets related to networking. 沙盒不支持执行完全堆栈网络操作的任何 cmdlet,包括 AIPService PowerShell 模块中的 Connect-AipService 和 DNSClient 模块中的 Resolve-DnsNameAny cmdlets that perform full stack network operations are not supported in the sandbox, including Connect-AipService from the AIPService PowerShell module and Resolve-DnsName from the DNSClient module.

这些是沙盒的已知限制。These are known limitations with the sandbox. 建议的解决方法是部署混合 Runbook 辅助角色或使用 Azure FunctionsThe recommended workaround is to deploy a Hybrid Runbook Worker or use Azure Functions.

默认模块Default modules

下表列出了在创建自动化帐户时,Azure 自动化默认导入的模块。The following table lists modules that Azure Automation imports by default when you create your Automation account. 自动化可以导入这些模块的较新版本。Automation can import newer versions of these modules. 但是,即使你删除了较新新版本,也不能从自动化帐户中删除原始版本。However, you can't remove the original version from your Automation account, even if you delete a newer version. 请注意,这些默认模块包括多个 AzureRM 模块。Note that these default modules include several AzureRM modules.

默认模块也称为“全局模块”。The default modules are also known as global modules. 在 Azure 门户中,查看创建帐户时导入的模块时,“全局模块”属性将为 true 。In the Azure portal, the Global module property will be true when viewing a module that was imported when the account was created.

Azure 门户中的全局模块属性的屏幕截图

自动化不会自动将根 Az 模块导入任何新的或现有的自动化帐户。Automation doesn't import the root Az module automatically into any new or existing Automation accounts. 要详细了解如何使用这些模块,请参阅迁移到 Az 模块For more about working with these modules, see Migrating to Az modules.

模块名称Module name 版本Version
AuditPolicyDscAuditPolicyDsc 1.1.0.01.1.0.0
AzureAzure 1.0.31.0.3
Azure.存储Azure.Storage 1.0.31.0.3
AzureRM.AutomationAzureRM.Automation 1.0.31.0.3
AzureRM.ComputeAzureRM.Compute 1.2.11.2.1
AzureRM.ProfileAzureRM.Profile 1.0.31.0.3
AzureRM.ResourcesAzureRM.Resources 1.0.31.0.3
AzureRM.SqlAzureRM.Sql 1.0.31.0.3
AzureRM.StorageAzureRM.Storage 1.0.31.0.3
ComputerManagementDscComputerManagementDsc 5.0.0.05.0.0.0
GPRegistryPolicyParserGPRegistryPolicyParser 0.20.2
Microsoft.PowerShell.CoreMicrosoft.PowerShell.Core 00
Microsoft.PowerShell.DiagnosticsMicrosoft.PowerShell.Diagnostics
Microsoft.PowerShell.ManagementMicrosoft.PowerShell.Management
Microsoft.PowerShell.SecurityMicrosoft.PowerShell.Security
Microsoft.PowerShell.UtilityMicrosoft.PowerShell.Utility
Microsoft.WSMan.ManagementMicrosoft.WSMan.Management
Orchestrator.AssetManagement.CmdletsOrchestrator.AssetManagement.Cmdlets 11
PSDscResourcesPSDscResources 2.9.0.02.9.0.0
SecurityPolicyDscSecurityPolicyDsc 2.1.0.02.1.0.0
StateConfigCompositeResourcesStateConfigCompositeResources 11
xDSCDomainjoinxDSCDomainjoin 1.11.1
xPowerShellExecutionPolicyxPowerShellExecutionPolicy 1.1.0.01.1.0.0
xRemoteDesktopAdminxRemoteDesktopAdmin 1.1.0.01.1.0.0

Az 模块Az modules

对于 Az.Automation,大多数 cmdlet 的名称与 AzureRM 模块的名称相同,但 AzureRM 前缀已更改为 AzFor Az.Automation, the majority of the cmdlets have the same names as those used for the AzureRM modules, except that the AzureRM prefix has been changed to Az. 有关不遵循此命名约定的 Az 模块列表,请参阅例外名称列表For a list of Az modules that don't follow this naming convention, see the list of exceptions.

内部 cmdletInternal cmdlets

Azure 自动化支持默认安装的 Windows Log Analytics 代理的内部 Orchestrator.AssetManagement.Cmdlets 模块。Azure Automation supports the internal Orchestrator.AssetManagement.Cmdlets module for the Log Analytics agent for Windows, installed by default. 下表定义了内部 cmdlet。The following table defines the internal cmdlets. 这些 cmdlet 旨在用于代替 Azure PowerShell cmdlet 与共享资源进行交互。These cmdlets are designed to be used instead of Azure PowerShell cmdlets to interact with shared resources. 它们可以从加密的变量、凭据和加密的连接中检索机密。They can retrieve secrets from encrypted variables, credentials, and encrypted connections.

备注

仅当在 Azure 沙盒环境中或对 Windows 混合 Runbook 辅助角色执行 runbook 时,内部 cmdlet 才可用。The internal cmdlets are only available when you're executing runbooks in the Azure sandbox environment, or on a Windows Hybrid Runbook Worker.

名称Name 说明Description
Get-AutomationCertificateGet-AutomationCertificate Get-AutomationCertificate [-Name] <string> [<CommonParameters>]
Get-AutomationConnectionGet-AutomationConnection Get-AutomationConnection [-Name] <string> [-DoNotDecrypt] [<CommonParameters>]
Get-AutomationPSCredentialGet-AutomationPSCredential Get-AutomationPSCredential [-Name] <string> [<CommonParameters>]
Get-AutomationVariableGet-AutomationVariable Get-AutomationVariable [-Name] <string> [-DoNotDecrypt] [<CommonParameters>]
Set-AutomationVariableSet-AutomationVariable Set-AutomationVariable [-Name] <string> -Value <Object> [<CommonParameters>]
Start-AutomationRunbookStart-AutomationRunbook Start-AutomationRunbook [-Name] <string> [-Parameters <IDictionary>] [-RunOn <string>] [-JobId <guid>] [<CommonParameters>]
Wait-AutomationJobWait-AutomationJob Wait-AutomationJob -Id <guid[]> [-TimeoutInMinutes <int>] [-DelayInSeconds <int>] [-OutputJobsTransitionedToRunning] [<CommonParameters>]

请注意,内部 cmdlet 的命名与 Az 和 AzureRM cmdlet 的不同。Note that the internal cmdlets differ in naming from the Az and AzureRM cmdlets. 内部 cmdlet 名称不包含像 AzureAz 这样的单词,但请使用单词 AutomationInternal cmdlet names don't contain words like Azure or Az in the noun, but do use the word Automation. 建议在 Azure 沙盒中或对 Windows 混合 Runbook 辅助角色运行 runbook 时优先使用内部 cmdlet,其次才是 Az 或 AzureRM cmdlet。We recommend their use over the use of Az or AzureRM cmdlets during runbook execution in an Azure sandbox or on a Windows Hybrid Runbook Worker. 它们需要的参数更少,并且可在已运行的作业上下文中运行。They require fewer parameters and run in the context of your job that's already running.

使用 Az 或 AzureRM cmdlet 在 runbook 上下文之外操作自动化资源。Use Az or AzureRM cmdlets for manipulating Automation resources outside the context of a runbook.

Python 模块Python modules

可以在 Azure 自动化中创建 Python 2 runbook。You can create Python 2 runbooks in Azure Automation. 有关 Python 模块信息,请参阅在 Azure 自动化中管理 Python 2 包For Python module information, see Manage Python 2 packages in Azure Automation.

自定义模块Custom modules

Azure 自动化支持你创建用于 runbook 和 DSC 配置的自定义 PowerShell 模块。Azure Automation supports custom PowerShell modules that you create to use with your runbooks and DSC configurations. 自定义模块的一种类型是集成模块,该模块可以选择包含元数据文件,以定义模块 cmdlet 的自定义功能。One type of custom module is an integration module that optionally contains a file of metadata to define the custom functionality for the module cmdlets. 添加连接类型中提供了集成模块的使用的示例。An example of the use of an integration module is provided in Add a connection type.

Azure 自动化可以导入自定义模块以提供其 cmdlet。Azure Automation can import a custom module to make its cmdlets available. 它可以在后台存储该模块并在 Azure 沙盒中使用,方式与其他模块别无二致。Behind the scenes, it stores the module and uses it in the Azure sandboxes, just like it does other modules.

迁移到 Az 模块Migrate to Az modules

本部分介绍如何迁移到自动化中的 Az 模块。This section tells how to migrate to the Az modules in Automation. 有关详细信息,请参阅将 Azure PowerShell 从 AzureRM 迁移到 AzFor more information, see Migrate Azure PowerShell from AzureRM to Az.

我们不建议在同一自动化帐户中运行 AzureRM 模块和 Az 模块。We don't recommend running AzureRM modules and Az modules in the same Automation account. 当确定要从 AzureRM 迁移到 Az 时,最好完全采用完整迁移。When you're sure you want to migrate from AzureRM to Az, it's best to fully commit to a complete migration. 自动化通常会重复使用自动化帐户中的沙盒,以节省启动时间。Automation often reuses sandboxes within the Automation account to save on startup times. 如果不进行完整模块迁移,则可以启动仅使用 AzureRM 模块的作业,然后启动另一个仅使用 Az 模块的作业。If you don't make a full module migration, you might start a job that uses only AzureRM modules, and then start another job that uses only Az modules. 沙盒即将崩溃,你会收到一个错误,其中指出模块不兼容。The sandbox soon crashes, and you receive an error stating that the modules aren't compatible. 这种情况会导致任何特定 runbook 或配置的随机崩溃。This situation results in randomly occurring crashes for any particular runbook or configuration.

备注

创建新的自动化帐户时,即使在迁移到 Az 模块后,自动化也会默认安装 AzureRM 模块。When you create a new Automation account, even after migration to Az modules, Automation installs the AzureRM modules by default. 你仍可以使用 AzureRM cmdlet 更新教程 runbook。You can still update the tutorial runbooks with the AzureRM cmdlets. 但是,不应运行这些 runbook。However, you shouldn't run these runbooks.

在模块迁移之前测试 runbook 和 DSC 配置Test your runbooks and DSC configurations prior to module migration

在迁移到 Az 模块之前,请务必在单独的自动化帐户中仔细测试所有 runbook 和 DSC 配置。Be sure to test all runbooks and DSC configurations carefully, in a separate Automation account, before migrating to the Az modules.

停止并取消计划使用 AzureRM 模块的所有 runbookStop and unschedule all runbooks that use AzureRM modules

要确保不运行任何使用 AzureRM 模块的现有 runbook 或 DSC 配置,必须停止并取消计划所有受影响的 runbook 和配置。To ensure that you don't run any existing runbooks or DSC configurations that use AzureRM modules, you must stop and unschedule all affected runbooks and configurations. 首先,请确保分别查看每个 runbook 或 DSC 配置及其计划,以确保将来可以根据需要重新计划项目。First, make sure that you review each runbook or DSC configuration and its schedules separately, to ensure that you can reschedule the item in the future if necessary.

准备好删除计划时,可以使用 Azure 门户或 Remove-AzureRmAutomationSchedule cmdlet。When you're ready to remove your schedules, you can either use the Azure portal or the Remove-AzureRmAutomationSchedule cmdlet. 请参阅删除计划See Remove a schedule.

删除 AzureRM 模块Remove AzureRM modules

在导入 Az 模块之前,可以删除 AzureRM 模块。It's possible to remove the AzureRM modules before you import the Az modules. 但如果这样做,则可以中断源代码管理同步并导致任何仍在计划的脚本失败。However, if you do, you can interrupt source control synchronization and cause any scripts that are still scheduled to fail. 如果决定删除模块,请参阅卸载 AzureRMIf you decide to remove the modules, see Uninstall AzureRM.

导入 Az 模块Import Az modules

在自动化帐户中导入 Az 模块的行为不会在 runbook 使用的 PowerShell 会话中自动导入该模块。Importing an Az module into your Automation account doesn't automatically import the module into the PowerShell session that runbooks use. 在以下情况中,模块会导入到 PowerShell 会话中:Modules are imported into the PowerShell session in the following situations:

  • runbook 从模块中调用 cmdlet 时。When a runbook invokes a cmdlet from a module.
  • runbook 使用 Import-Module cmdlet 显式导入模块时。When a runbook imports the module explicitly with the Import-Module cmdlet.
  • runbook 导入另一个依赖模块时。When a runbook imports another dependent module.

可以在 Azure 门户中导入 Az 模块。You can import the Az modules in the Azure portal. 请记住仅导入所需的 Az 模块,而不是导入整个 Az.Automation 模块。Remember to import only the Az modules that you need, not the entire Az.Automation module. 由于 Az.Accounts 是其他 Az 模块的依赖项,因此请确保在其他模块之前先将其导入。Because Az.Accounts is a dependency for the other Az modules, be sure to import this module before any others.

  1. 在自动化帐户中的“共享资源”下,选择“模块” 。From your Automation account, under Shared Resources, select Modules.

  2. 选择“浏览库”。Select Browse Gallery.

  3. 在搜索栏中,输入模块名称(例如 Az.Accounts)。In the search bar, enter the module name (for example, Az.Accounts).

  4. 在 PowerShell 模块页,选择“导入”,将模块导入自动化帐户。On the PowerShell Module page, select Import to import the module into your Automation account.

    将模块导入自动化帐户的屏幕截图

还可以搜索要导入的模块,通过 PowerShell 库执行此导入。You can also do this import through the PowerShell Gallery, by searching for the module to import. 找到该模块后,选择它,然后选择“Azure 自动化”选项卡。When you find the module, select it, and choose the Azure Automation tab.

测试 runbookTest your runbooks

将 Az 模块导入自动化帐户后,可以开始编辑 runbook 和 DSC 配置以使用新模块。After you've imported the Az modules into the Automation account, you can start editing your runbooks and DSC configurations to use the new modules. 测试 runbook 的修改以使用新 cmdlet 的一种方法是在 runbook 的开头使用 Enable-AzureRmAlias -Scope Process 命令。One way to test the modification of a runbook to use the new cmdlets is by using the Enable-AzureRmAlias -Scope Process command at the beginning of the runbook. 通过将此命令添加到 runbook,脚本无需更改也可运行。By adding this command to your runbook, the script can run without changes.

创作者模块Author modules

当创作用于 Azure 自动化的自定义 PowerShell 模块时,建议遵循本部分中的注意事项。We recommend that you follow the considerations in this section when you author a custom PowerShell module for use in Azure Automation. 要准备要导入的模块,必须至少创建一个名称与模块文件夹的名称相同的 .psd1、.psm1 或 PowerShell 模块 .dll 文件。To prepare your module for import, you must create at least a .psd1, .psm1, or PowerShell module .dll file with the same name as the module folder. 然后压缩模块文件夹,以便 Azure 自动化可以将其作为单个文件导入。Then you zip up the module folder so that Azure Automation can import it as a single file. .zip 包的名称应与包含的模块文件夹的名称相同。The .zip package should have the same name as the contained module folder.

要详细了解如何创作 PowerShell 模块,请参阅如何编写 PowerShell 脚本模块To learn more about authoring a PowerShell module, see How to Write a PowerShell Script Module.

版本文件夹Version folder

通过 PowerShell 并行模块版本控制,可以在 PowerShell 中使用一个模块的多个版本。PowerShell side-by-side module versioning allows you to use more than one version of a module within PowerShell. 如果你有经过测试的较旧脚本并仅适用于特定版本的 PowerShell 模块,则此方法很有用,但其他脚本需要同一 PowerShell 模块的较新版本。This can be useful if you have older scripts that have been tested and only work against a certain version of a PowerShell module, but other scripts require a newer version of the same PowerShell module.

若要构造 PowerShell 模块以使其包含多个版本,请创建模块文件夹,然后在该模块文件夹中为要使用的每个模块版本创建一个文件夹。To construct PowerShell modules so they contain multiple versions, create the module folder and then create a folder within this module folder for each version of the module you want to be usable. 在以下示例中,名为“TestModule”的模块提供了两个版本:1.0.0 和 2.0.0。In the following example, a module called TestModule provides two versions, 1.0.0 and 2.0.0.

TestModule
   1.0.0
   2.0.0

在每个版本文件夹中,将组成模块的 PowerShell .psm1、.psd1 或 PowerShell 模块 .dll 文件复制到相应的版本文件夹中。Within each of the version folders, copy your PowerShell .psm1, .psd1, or PowerShell module .dll files that make up a module into the respective version folder. 压缩模块文件夹,以便 Azure 自动化可以将其作为单个 .zip 文件导入。Zip up the module folder so that Azure Automation can import it as a single .zip file. 虽然 Azure 自动化仅显示导入的模块的最高版本,但如果模块包中包含并行版本的模块,则它们均可在你的 runbook 或 DSC 配置中使用。While Automation only shows the highest version of the module imported, if the module package contains side-by-side versions of the module, they are all available for use in your runbooks or DSC configurations.

虽然自动化支持在同一包中包含并行版本的模块,但它不支持跨模块包导入使用模块的多个版本。While Automation supports modules containing side-by-side versions within the same package, it does not support using multiple versions of a module across module package imports. 例如,将包含版本 1 和版本 2 的模块 A 导入到你的 Azure 自动化帐户中。For example, you import module A, which contains versions 1 and 2 into your Automation account. 稍后,当你导入 Azure 自动化帐户时,如果将模块 A 更新为包括版本 3 和 4,则在任何 runbook 或 DSC 配置中只有版本 3 和 4 可用。Later you update module A to include versions 3 and 4, when you import into your Automation account, only versions 3 and 4 are usable within any runbooks or DSC configurations. 如果需要所有版本(版本 1、2、3 和 4 都可用),则导入的 .zip 文件应包含版本 1、2、3 和 4。If you require all versions - 1, 2, 3, and 4 to be available, the .zip file your import should contain versions 1, 2, 3, and 4.

如果要在 runbook 之间使用同一模块的不同版本,则应始终使用 Import-Module cmdlet 声明要在 runbook 中使用的版本,并包括参数 -RequiredVersion <version>If you're going to use different versions of the same module between runbooks, you should always declare the version you want to use in your runbook using the Import-Module cmdlet and include the parameter -RequiredVersion <version>. 即使你要使用的版本是最新版本。Even if the version you want to use is the latest version. 这是因为 Runbook 作业可能在同一沙盒中运行。This is because runbook jobs may run in the same sandbox. 如果沙盒已经显式加载了某个版本号的模块(因为该沙盒中的先前作业显示是这样做的),则该沙盒中的未来作业将不会自动加载该模块的最新版本。If the sandbox has already explicitly loaded a module of a certain version number, because a previous job in that sandbox said to do so, future jobs in that sandbox won't automatically load the latest version of that module. 这是因为它的某些版本已在沙盒中加载。This is because some version of it is already loaded in the sandbox.

对于 DSC 资源,请使用以下命令指定特定版本:For a DSC resource, use the following command to specify a particular version:

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

帮助信息Help information

在模块中加入每个 cmdlet 的摘要、说明和帮助 URI。Include a synopsis, description, and help URI for every cmdlet in your module. 在 PowerShell 中,可以使用 Get-Help cmdlet 来定义 cmdlet 的帮助信息。In PowerShell, you can define help information for cmdlets by using the Get-Help cmdlet. 以下示例显示如何在 .psm1 模块文件中定义摘要和帮助 URI。The following example shows how to define a synopsis and help URI in a .psm1 module file.

<#
     .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
  }
}
}

提供此信息通过 PowerShell 控制台中的 Get-Help cmdlet 显示帮助文本。Providing this information shows help text via the Get-Help cmdlet in the PowerShell console. 此文本也显示在 Azure 门户中。This text is also displayed in the Azure portal.

集成模块帮助的屏幕截图

连接类型Connection type

如果模块连接到外部服务,请使用自定义集成模块定义连接类型。If the module connects to an external service, define a connection type by using a custom integration module. 模块中的每个 cmdlet 都应接受该连接类型(连接对象)的实例作为参数。Each cmdlet in the module should accept an instance of that connection type (connection object) as a parameter. 用户可在每次调用 cmdlet 时将连接资产的参数映射到 cmdlet 的相应参数。Users map parameters of the connection asset to the cmdlet's corresponding parameters each time they call a cmdlet.

在 Azure 门户中使用自定义连接

下面的 runbook 示例使用名为 ContosoConnection 的 Contoso 连接资产来访问 Contoso 资源并从外部服务返回数据。The following runbook example uses a Contoso connection asset called ContosoConnection to access Contoso resources and return data from the external service. 在此示例中,字段映射到 PSCredential 对象的 UserNamePassword 属性,然后传递给 cmdlet。In this example, the fields are mapped to the UserName and Password properties of a PSCredential object and then passed to the cmdlet.

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

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

实现此行为的更轻松且更好的方法是直接将连接对象传递给 cmdlet:An easier and better way to approach this behavior is by directly passing the connection object to the cmdlet:

$contosoConnection = Get-AutomationConnection -Name 'ContosoConnection'

Connect-Contoso -Connection $contosoConnection
}

要为 cmdlet 启用类似行为,可以允许 cmdlet 以参数的形式直接接受连接对象,而不是只接受连接字段作为参数。You can enable similar behavior for your cmdlets by allowing them to accept a connection object directly as a parameter, instead of just connection fields for parameters. 通常情况下,需要为每个 cmdlet 提供一个参数集,这样不使用自动化的用户在调用 cmdlet 时就不需要构造一个哈希表来充当连接对象。Usually you want a parameter set for each, so that a user who isn't using Automation can call your cmdlets without constructing a hashtable to act as the connection object. 参数集 UserAccount 可用于传递连接字段属性。The parameter set UserAccount is used to pass the connection field properties. ConnectionObject 允许将连接一直传下去。ConnectionObject lets you pass the connection straight through.

输出类型Output type

在模块中定义所有 cmdlet 的输出类型。Define the output type for all cmdlets in your module. 定义 cmdlet 的输出类型以后,就可以利用设计时 IntelliSense 在创作期间确定 cmdlet 的输出属性。Defining an output type for a cmdlet allows design-time IntelliSense to help determine the output properties of the cmdlet during authoring. 这种做法在图形 runbook 的创作过程中特别有用,这种创作过程要求掌握一定程度的设计时知识,以改进用户对模块的使用体验。This practice is especially helpful during graphical runbook authoring, for which design-time knowledge is key to an easy user experience with your module.

添加 [OutputType([<MyOutputType>])],其中 MyOutputType 是有效类型。Add [OutputType([<MyOutputType>])], where MyOutputType is a valid type. 要详细了解 OutputType,请参阅关于 Functions OutputTypeAttributeTo learn more about OutputType, see About Functions OutputTypeAttribute. 下面代码是将 OutputType 添加到 cmdlet 的示例:The following code is an example of adding OutputType to a cmdlet:

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

图形 runbook 输出类型的屏幕截图

此行为类似于 PowerShell 集成服务环境中 cmdlet 输出的“预输入”功能,但不需要运行。This behavior is similar to the "type ahead" functionality of a cmdlet's output in the PowerShell integration service environment, without having to run it.

POSH IntelliSense 的屏幕截图

Cmdlet 状态Cmdlet state

使模块中的所有 cmdlet 以无状态方式呈现。Make all cmdlets in your module stateless. 多个 runbook 作业可在同一 AppDomain 和同一进程及沙盒中同时运行。Multiple runbook jobs can simultaneously run in the same AppDomain and the same process and sandbox. 如果在这些级别上共享了任何状态,则作业可能会互相影响。If there is any state shared on those levels, jobs can affect each other. 此行为会导致间歇性和难以诊断的问题。This behavior can lead to intermittent and hard-to-diagnose issues. 下面是应避免的处理方式的示例:Here is an example of what not to do:

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

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

   $output
}

模块依赖项Module dependency

确保模块完全包含在可以使用 xcopy 进行复制的包中。Ensure that the module is fully contained in a package that can be copied by using xcopy. runbook 执行时,自动化模块将分发到自动化沙盒中。Automation modules are distributed to the Automation sandboxes when runbooks execute. 模块必须独立于运行它们的主机工作。The modules must work independently of the host that runs them.

你应能够压缩并移动模块包,并确保该模块包在导入到其他主机的 PowerShell 环境时可以正常运行。You should be able to zip up and move a module package, and have it function as normal when it's imported into another host's PowerShell environment. 为此,请确保模块不依赖在模块导入自动化时压缩的模块文件夹外部的任何文件。For this to happen, ensure that the module doesn't depend on any files outside the module folder that is zipped up when the module is imported into Automation.

模块不应依赖主机上的任何唯一注册表设置。Your module shouldn't depend on any unique registry settings on a host. 例如,安装产品时所做的设置。Examples are the settings that are made when a product is installed.

模块文件路径Module file paths

确保模块中所有文件的路径少于 140 个字符。Make sure that all files in the module have paths with fewer than 140 characters. 长度超过 140 个字符的任何路径都会导致导入 runbook 时出现问题。Any paths over 140 characters in length cause problems with importing runbooks. 自动化无法使用 Import-Module 将路径大小超过 140 个字符的文件导入 PowerShell 会话中。Automation can't import a file with path size over 140 characters into the PowerShell session with Import-Module.

导入模块Import modules

本部分定义了将模块导入自动化帐户的几种方法。This section defines several ways that you can import a module into your Automation account.

在 Azure 门户中导入 Azure 模块Import modules in the Azure portal

在 Azure 门户中导入 Azure 模块:To import a module in the Azure portal:

  1. 返回到自动化帐户。Go to your Automation account.
  2. 在“共享资源”下,选择“模块” 。Under Shared Resources, select Modules.
  3. 选择“添加模块”。Select Add a module.
  4. 选择包含模块的 .zip 文件。Select the .zip file that contains your module.
  5. 选择“确定”以开始导入过程。Select OK to start to import process.

使用 PowerShell 导入模块Import modules by using PowerShell

可以使用 New-AzAutomationModule cmdlet 将模块导入自动化帐户。You can use the New-AzAutomationModule cmdlet to import a module into your Automation account. cmdlet 会获取模块 .zip 包的 URL。The cmdlet takes a URL for a module .zip package.

New-AzAutomationModule -Name <ModuleName> -ContentLinkUri <ModuleUri> -ResourceGroupName <ResourceGroupName> -AutomationAccountName <AutomationAccountName>

还可以使用相同的 cmdlet 直接从 PowerShell 库导入模块。You can also use the same cmdlet to import a module from the PowerShell Gallery directly. 请确保从 PowerShell 库获取 ModuleNameModuleVersionMake sure to grab ModuleName and ModuleVersion from the PowerShell Gallery.

$moduleName = <ModuleName>
$moduleVersion = <ModuleVersion>
New-AzAutomationModule -AutomationAccountName <AutomationAccountName> -ResourceGroupName <ResourceGroupName> -Name $moduleName -ContentLinkUri "https://www.powershellgallery.com/api/v2/package/$moduleName/$moduleVersion"

直接从自动化帐户导入 PowerShell 库模块:To import a PowerShell Gallery module directly from your Automation account:

  1. 在“共享资源”下,选择“模块库” 。Under Shared Resources, select Modules gallery.
  2. 选择要导入的模块,然后选择“导入”。Select the module to import, and select Import.
  3. 选择“确定”以开始导入过程。Select OK to start the import process.

从 Azure 门户导入 PowerShell 库模块的屏幕截图

删除模块Delete modules

如果模块出现问题,或者需要回滚到模块的早期版本,则可以将其从自动化帐户中删除。If you have problems with a module, or you need to roll back to a previous version of a module, you can delete it from your Automation account. 无法删除默认模块的原始版本,这些模块是在创建自动化帐户时导入的。You can't delete the original versions of the default modules that are imported when you create an Automation account. 如果要删除的模块是默认模块之一的较新版本,则它会回滚到使用自动化帐户安装的版本。If the module to delete is a newer version of one of the default modules, it rolls back to the version that was installed with your Automation account. 否则,从自动化帐户中删除的任何模块都将被删除。Otherwise, any module you delete from your Automation account is removed.

在 Azure 门户中删除模块Delete modules in the Azure portal

在 Azure 门户中删除模块:To remove a module in the Azure portal:

  1. 返回到自动化帐户。Go to your Automation account. 在“共享资源”下,选择“模块” 。Under Shared Resources, select Modules.
  2. 选择要删除的模块。Select the module you want to remove.
  3. 在“模块”页上,选择“删除”。On the Module page, select Delete. 如果此模块是默认模块之一,则它会回滚到创建自动化帐户时存在的版本。If this module is one of the default modules, it rolls back to the version that existed when the Automation account was created.

使用 PowerShell 删除模块Delete modules by using PowerShell

要通过 PowerShell 删除模块,请运行以下命令:To remove a module through PowerShell, run the following command:

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

后续步骤Next steps