PowerShell DSC 扩展

2025-09-15

注意

DSC 扩展将于 2028 年 3 月 31 日停止使用。在该日期前迁移到 Azure 机器配置。有关详细信息，请参阅博客文章公告。 Azure 计算机配置服务结合了 DSC 扩展、Azure Automation State Configuration 的某些功能，以及客户反馈中通常请求的功能。 Azure Machine Configuration 还包括通过已启用 Arc 的服务器提供的混合计算机支持。

概述

适用于 Windows 的 PowerShell DSC 扩展上传并在 Azure 虚拟机上应用 PowerShell DSC 配置。 DSC 扩展调用 PowerShell DSC，以在虚拟机上执行收到的 DSC 配置。本文档详细介绍适用于 Windows 的 DSC 虚拟机扩展支持的平台、配置和部署选项。

必备条件

操作系统

DSC 扩展支持以下操作系统：

Windows Server 2022、Windows Server 2019、Windows Server 2016、Windows Server 2012R2、Windows Server 2012、Windows Server 2008 R2 SP1、Windows Client 7/8.1/10

Internet 连接

Windows 的 DSC 扩展要求目标虚拟机能够与 Azure 通信以及配置包（.zip 文件）的位置（如果存储在 Azure 外部）。

扩展架构

以下 JSON 显示用于 Azure 资源管理器模板中 DSC 扩展的设置部分的架构。

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "Microsoft.Powershell.DSC",
  "apiVersion": "2018-10-01",
  "location": "<location>",
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "wmfVersion": "latest",
        "configuration": {
            "url": "http://validURLToConfigLocation",
            "script": "ConfigurationScript.ps1",
            "function": "ConfigurationFunction"
        },
        "configurationArguments": {
            "argument1": "Value1",
            "argument2": "Value2"
        },
        "configurationData": {
            "url": "https://foo.psd1"
        },
        "privacy": {
            "dataCollection": "enable"
        },
        "advancedOptions": {
            "forcePullAndApply": false,
            "downloadMappings": {
             "specificDependencyKey": "https://myCustomDependencyLocation"
            }
        }
    },
    "protectedSettings": {
        "configurationArguments": {
            "parameterOfTypePSCredential1": {
                "userName": "UsernameValue1",
                "password": "PasswordValue1"
            },
            "parameterOfTypePSCredential2": {
                "userName": "UsernameValue2",
                "password": "PasswordValue2"
            }
        },
        "configurationUrlSasToken": "?g!bber1sht0k3n",
        "configurationDataUrlSasToken": "?dataAcC355T0k3N"
    }
  }
}

属性值

名称	值/示例	数据类型
apiVersion	2018-10-01	date
发布服务器	Microsoft.Powershell.DSC	字符串
类型	DSC	字符串
typeHandlerVersion	2.77	int

设置属性值

名称	数据类型	说明
settings.wmfVersion	字符串	指定应在 VM 上安装的 Windows Management Framework 版本。将此属性设置为“latest”会安装最新版本的 WMF。此属性的当前可能值为“4.0”、“5.0”和“latest”。这些可能值将来可能会更新。默认值为“latest”。
settings.configuration.url	字符串	指定要从中下载 DSC 配置 zip 文件的 URL 位置。如果提供的 URL 需要 SAS 令牌才能访问，请将 protectedSettings.configurationUrlSasToken 属性设置为 SAS 令牌的值。如果已定义 settings.configuration.script 和/或 settings.configuration.function，则需要此属性。
settings.configuration.script	字符串	指定包含 DSC 配置定义的脚本的文件名。此脚本必须位于从 configuration.url 属性所指定的 URL 下载的 zip 文件的根文件夹中。如果已定义 settings.configuration.url 和/或 settings.configuration.script，则需要此属性。
settings.configuration.function	字符串	指定 DSC 配置的名称。命名的配置必须包含在 configuration.script 定义的脚本中。如果已定义 settings.configuration.url 和/或 settings.configuration.function，则需要此属性。
settings.configurationArguments	集合	定义想要传递到 DSC 配置的任何参数。此属性不会加密。
settings.configurationData.url	字符串	指定 URL，将从中下载配置数据 (.pds1) 文件用作 DSC 配置的输入。如果提供的 URL 需要 SAS 令牌才能访问，请将 protectedSettings.configurationDataUrlSasToken 属性设置为 SAS 令牌的值。
settings.privacy.dataEnabled	字符串	启用或禁用遥测数据收集。此属性的可能值只有“Enable”、“Disable”或“$null”。将此属性留空或为 null 可启用遥测
settings.advancedOptions.forcePullAndApply	Bool	此设置旨在增强使用扩展将节点注册到 Azure Automation DSC 的体验。如果值为此值 `$true`，则扩展将等待从服务拉取的配置的第一次运行，然后再返回成功/失败。如果该值设置为$false，则扩展返回的状态是指节点是否已成功注册到 Azure Automation State Configuration，并且节点配置不会在注册期间运行。
settings.advancedOptions.downloadMappings	集合	定义用于下载依赖项（如 WMF 和 .NET）的备用位置

受保护设置属性值

名称	数据类型	说明
protectedSettings.configurationArguments	字符串	定义想要传递到 DSC 配置的任何参数。
protectedSettings.configurationUrlSasToken	字符串	指定用于访问 configuration.url 所定义的 URL 的 SAS 令牌。
protectedSettings.configurationDataUrlSasToken	字符串	指定用于访问 configurationData.url 所定义的 URL 的 SAS 令牌。

模板部署

可使用 Azure Resource Manager 模板部署 Azure VM 扩展。部署需要部署后配置的一个或多个虚拟机时，模板是理想选择。包含 Windows 的 DSC 扩展的示例资源管理器模板可以在 Azure 快速入门库中找到。

故障排除和支持

疑难解答

有关扩展部署状态的数据可以从 Azure 门户和使用 Azure CLI 进行检索。若要查看给定 VM 的扩展部署状态，请使用 Azure CLI 运行以下命令。

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

下载扩展包并将其部署到 Azure VM 上的此位置

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}

扩展状态文件包含子状态和状态成功/错误代码以及每个扩展运行的详细错误和说明。

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}\Status\{0}.Status  -> {0} being the sequence number

扩展输出日志会记录到以下目录：

C:\WindowsAzure\Logs\Plugins\{Extension_Name}\{Extension_Version}

错误代码及其含义

错误代码	含义	可能的操作
1000	常规错误	此错误消息由扩展日志中的特定异常提供
52	扩展安装错误	此错误消息由特定异常提供
1002	WMF 安装错误	安装 WMF 时出错。
1004	Zip 包无效	zip 无效; 解压缩 zip 时出错
1100	参数错误	指示用户提供的输入中的问题。此错误消息由特定异常提供

支持

如果对本文中的任何观点存在疑问，可以联系 Azure 支持上的 Azure 专家。或者，你也可以提出 Azure 支持事件。请转到 Azure 支持站点提交请求。有关使用 Azure 支持的信息，请阅读 Azure 支持常见问题。

共用方式為