ConvertTo-Json

把 PowerShell 对象序列化成 JSON 字符串，注意深度。

补充说明

ConvertTo-Json 接收对象并输出 JSON 字符串，默认生成带缩进的多行文本，-Compress 生成单行；-Depth 控制递归层数，默认只有 2，超过会被截断并给出警告。它没有内置别名。管道：-InputObject 按值接收对象，也可以直接接在管道末尾。权限：不需要额外权限，输出到文件时由 Set-Content/Out-File 的权限决定。

边界：它只做序列化，不负责编码和文件写入；落盘时显式指定编码。哈希表的键顺序默认不保证，需要稳定顺序用 [ordered]@{} 或 [pscustomobject]。服务端 API 需要的字段名、空值和日期格式要按接口约定处理，不能假定 PowerShell 的默认格式通用。

版本：5.1 把 DateTime 序列化成 \/Date(...)\/，并转义 <、>、&、' 等 HTML 敏感字符；7.x 差异：日期使用 ISO 8601，新增 -AsArray、-EscapeHandling、-EnumsAsStrings。5.1 没有这些参数。

常用示例

# 1. 把单个对象序列化，查看默认多行格式
PS C:\> Get-Process -Id $PID | Select-Object Name, Id, StartTime | ConvertTo-Json

# 2. 明确提高深度，避免嵌套对象被截断
PS C:\> Get-Service | Where-Object Status -eq 'Running' | Select-Object -First 2 Name, Status, ServicesDependedOn | ConvertTo-Json -Depth 3

# 3. 生成单行 JSON，适合日志或命令行传输
PS C:\> [pscustomobject]@{ Name='api'; Port=8080; Tags=@('prod','web') } | ConvertTo-Json -Compress

# 4. 序列化后写文件，显式 UTF-8 避免编码歧义
PS C:\> Get-ChildItem C:\Logs -File | Select-Object Name, Length | ConvertTo-Json -Depth 3 | Set-Content C:\Temp\logs.json -Encoding UTF8

# 5. 强制保留单元素数组，绕过管道展开
PS C:\> ConvertTo-Json -InputObject @(1) -Compress

# 6. 7.x 差异：确保单对象也输出为数组
PS C:\> Get-Process -Name notepad | Select-Object Name, Id | ConvertTo-Json -AsArray

易错点与排错

• 默认 -Depth 2，嵌套三层的对象会被截断并警告；根据结构显式加 -Depth，但不要盲目设很大，先确认输出结构。
• 管道会把单元素数组展开成单个对象，JSON 从 [...] 变成 {...}；5.1 用 ConvertTo-Json -InputObject @(...)，7.x 可用 -AsArray。
• 5.1 的 DateTime 是 \/Date(...)\/，非 .NET 客户端难以解析；先 .ToString('o') 转成 ISO 字符串再序列化。
• 5.1 会转义 HTML 敏感字符，输出可读性差；7.x 用 -EscapeHandling 控制，但不要为了美观关闭必要转义。
• [hashtable] 的键顺序不稳定，快照对比会出现假差异；用 [ordered]@{} 或固定属性顺序的对象。
• 输出写入文件时，5.1 默认编码可能带 BOM；部分 JSON 解析器不接受 BOM，验证 Format-Hex 并用 7.x 的 utf8NoBOM 或按目标要求处理。
• 复杂对象（如 Process、ServiceController）可能包含循环引用或运行期属性；先 Select-Object 裁剪成纯数据再序列化。

相关命令

• ConvertFrom-Json — 反向解析 JSON 字符串。
• Set-Content — 把 JSON 文本写入文件。
• Invoke-RestMethod — 直接解析 API 返回的 JSON。
• Select-Object — 序列化前裁剪字段。

参考链接

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

读完自测

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

1. 默认深度是多少？超过深度会发生什么？
2. 为什么只有一个元素的数组经过管道后可能变成对象？
3. 5.1 和 7.x 对 DateTime 的 JSON 表示有什么差异？