Invoke-AzVMRunCommand从Runbook传参至VM脚本失败问题

1. 确认Invoke-AzVMRunCommand的参数传递格式 #

传参失败最常见原因是格式错误，必须通过-Parameter参数传入哈希表格式的参数，且键名要与脚本参数名完全匹配：

# Runbook中的执行命令示例
$params = @{
    FolderName = "TargetFolder"
}

Invoke-AzVMRunCommand -ResourceGroupName "YourRG" -VMName "YourVM" -CommandId "RunPowerShellScript" -ScriptPath "C:\Scripts\CreateFolder.ps1" -Parameter $params

2. 检查VM脚本的参数接收逻辑 #

脚本必须通过param块显式声明参数，不能直接使用未定义的变量。正确的CreateFolder.ps1示例：

param(
    [string]$FolderName
)

$targetPath = Join-Path -Path "C:\Users" -ChildPath $FolderName
New-Item -Path $targetPath -ItemType Directory -Force

如果脚本没有param块，外部传入的参数无法被识别，只能使用硬编码值。

3. 验证参数是否成功传递到VM #

在脚本中添加日志输出，确认参数是否被正确接收：

param(
    [string]$FolderName
)

# 写入参数日志到VM本地
"Received FolderName: $FolderName" | Out-File -Path "C:\Temp\ParamCheck.log" -Append -Encoding utf8

$targetPath = Join-Path -Path "C:\Users" -ChildPath $FolderName
New-Item -Path $targetPath -ItemType Directory -Force

执行命令后登录VM，查看C:\Temp\ParamCheck.log（若Temp文件夹不存在需先创建），确认参数值是否正确写入。

4. 检查执行权限与上下文 #

Invoke-AzVMRunCommand默认使用NT AUTHORITY\SYSTEM账户执行，需确认该账户对C:\Users有写入权限。可在脚本中添加上下文日志：

param(
    [string]$FolderName
)

"Current execution user: $env:USERNAME" | Out-File -Path "C:\Temp\ContextCheck.log" -Append
(Get-Acl -Path "C:\Users").AccessToString | Out-File -Path "C:\Temp\ContextCheck.log" -Append

$targetPath = Join-Path -Path "C:\Users" -ChildPath $FolderName
New-Item -Path $targetPath -ItemType Directory -Force

登录VM查看日志，确认执行账户的权限是否足够。

5. 查看命令执行的返回日志 #

执行Invoke-AzVMRunCommand后，直接读取返回结果中的错误信息：

$result = Invoke-AzVMRunCommand -ResourceGroupName "YourRG" -VMName "YourVM" -CommandId "RunPowerShellScript" -ScriptPath "C:\Scripts\CreateFolder.ps1" -Parameter $params
# 输出脚本执行的标准输出与错误
$result.Value[0].Message

这里的Message会包含脚本执行时的所有输出，可直接定位参数为空、路径无效等具体问题。

6. 处理含特殊字符的参数 #

如果FolderName包含空格或特殊字符，无需额外加引号，哈希表会自动处理：

$params = @{
    FolderName = "My Test Folder_2024"
}

脚本中的Join-Path会自动生成合法路径。

内容的提问来源于stack exchange，提问作者Fynenix