ConvertFrom-Json

把 JSON 文本解析成对象，便于按属性取值和筛选。

补充说明

ConvertFrom-Json 接收 JSON 字符串并输出 PSCustomObject（数组则输出对象集合），属性可用点号访问；它不保留原始类型信息，日期、枚举和大整数可能需要显式转换。它没有内置别名。管道：按值接收 JSON 字符串，通常与 Get-Content -Raw 或 Invoke-WebRequest 的 .Content 配合。权限：不需要额外权限，读取来源由上游命令决定。

边界：它只解析 JSON，不负责下载；Invoke-RestMethod 会直接返回反序列化后的对象，需要状态码/响应头时才用 Invoke-WebRequest。JSON 必须是严格语法，注释、尾随逗号和单引号都不被接受。属性名含连字符或空格时用引号访问，例如 $obj.'key-name'。

版本：5.1 输出 PSCustomObject，数组默认逐元素输出，单元素数组会被展开为标量；7.x 差异：新增 -AsHashtable 和 -NoEnumerate，可用后者保留数组形态。5.1 没有这两个参数。

常用示例

# 1. 读取 JSON 文件并直接访问属性
PS C:\> $cfg = Get-Content C:\App\config.json -Raw | ConvertFrom-Json; $cfg.Port

# 2. 解析后按属性筛选对象
PS C:\> (Get-Content C:\Temp\services.json -Raw | ConvertFrom-Json) | Where-Object Status -eq 'Running'

# 3. 解析内联 JSON，验证数组和嵌套属性
PS C:\> $r = '{"name":"api","ports":[80,443]}' | ConvertFrom-Json; $r.ports

# 4. 捕获无效 JSON，输出带位置的错误信息
PS C:\> try { Get-Content C:\Temp\bad.json -Raw | ConvertFrom-Json -ErrorAction Stop } catch { $_.Exception.Message }

# 5. 用 @() 包住结果，强制得到数组，避免单元素被展开
PS C:\> $arr = @(Get-Content C:\Temp\list.json -Raw | ConvertFrom-Json); $arr.Count

# 6. 7.x 差异：解析为哈希表，便于动态键访问
PS C:\> $h = Get-Content C:\Temp\data.json -Raw | ConvertFrom-Json -AsHashtable; $h['name']

易错点与排错

• Get-Content 不加 -Raw 时逐行传给 ConvertFrom-Json，多行 JSON 会解析失败或只得到片段；读取文件始终先 -Raw。
• 单元素 JSON 数组会被展开成标量，$x.Count 或索引行为不符合预期；5.1 用 @(...) 包装，7.x 用 -NoEnumerate。
• 属性名含 -、空格或数字开头时不能直接用点号；写 $obj.'key-name'，或先 $obj.PSObject.Properties.Name 查看键名。
• JSON 不允许注释和尾随逗号；报错信息通常给出字符位置，先修上游生成器，不要用字符串替换硬改。
• 只差大小写的重复键可能导致解析错误或覆盖；生成端必须保证键唯一，解析前用严格 JSON 校验器确认。
• 解析后日期仍是字符串或自动转换结果因版本而异；需要 DateTime 时显式 [datetime]::Parse()，不要依赖隐式行为。
• 大 JSON 会整体载入内存；超大文件考虑流式解析器或先用 API 过滤，不要反复 ConvertFrom-Json。

相关命令

• ConvertTo-Json — 反向序列化并检查字段。
• Get-Content — 用 -Raw 读取完整 JSON 文件。
• Invoke-RestMethod — 调用 API 并自动反序列化。
• Where-Object — 解析后按属性筛选。

参考链接

• Microsoft Learn: ConvertFrom-Json
• Microsoft Learn: ConvertTo-Json

读完自测

合上页面，先回答，再展开对照。

1. 为什么读取 JSON 文件时 Get-Content 必须加 -Raw？
2. 单元素 JSON 数组解析后为什么可能没有 Count 或索引？
3. 5.1 没有 -AsHashtable 时，怎样访问带连字符的属性？