JSON en PowerShell es una de esas habilidades que todo profesional de TI termina necesitando: la respuesta de casi cualquier API llega en JSON, muchos programas guardan su configuración en un archivo .json y los inventarios, informes y exportaciones de las consolas modernas usan el mismo formato. PowerShell lo convierte en objetos con dos cmdlets, ConvertFrom-Json y ConvertTo-Json, y a partir de ahí se filtra, se cambia y se guarda como cualquier otro dato.
Esta guía de consulta explica cómo leer un archivo JSON en PowerShell, cómo cambiar sus valores, cómo guardar un archivo JSON en PowerShell sin romper las tildes ni el formato, cómo validarlo, cómo comparar dos versiones y cómo pasar de JSON a CSV con PowerShell para abrirlo en Excel. Cada comportamiento se midió el 20 de noviembre de 2026 en un Windows 11 en español con Windows PowerShell 5.1 y con PowerShell 7.7.0, y las dos versiones se comportan distinto en más casos de los que parece: muchas de las trampas de este artículo solo existen en una de ellas.
Si todavía no trabaja con la consola, empiece por la guía de PowerShell. Si lo que necesita es hablar con una API, la guía de Invoke-RestMethod cubre las peticiones y aquí se trata lo que se hace con el JSON antes y después.
Qué es JSON y cómo lo ve PowerShell
JSON (JavaScript Object Notation) es un formato de texto para datos estructurados: objetos entre llaves con pares "clave": valor, listas entre corchetes y cuatro tipos de valor (texto, número, verdadero o falso y nulo). Es legible para una persona y fácil de procesar para un programa, por eso lo usan las API REST, los archivos de configuración de Visual Studio Code, Windows Terminal o Docker y las exportaciones de herramientas como winget.
Este es el archivo de ejemplo que se usa en toda la guía, config.json, la configuración de un script de revisión de equipos:
{
"empresa": "KHARONTE",
"sede": "Bogotá",
"umbralDisco": 15,
"alertas": { "correo": "mesa@empresa.com", "activas": true },
"equipos": [
{ "nombre": "PC-001", "ip": "10.0.0.11" },
{ "nombre": "PC-002", "ip": "10.0.0.12" }
]
}
Al convertirlo, PowerShell entrega un objeto de tipo PSCustomObject y cada clave pasa a ser una propiedad. Pero el tipo de cada valor depende de la versión, y eso cambia comparaciones, sumas y fechas:
| En el JSON | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
Objeto { } | PSCustomObject | PSCustomObject (o tabla hash con -AsHashtable) |
Lista [ ] | Object[] | Object[] |
15 | Int32 | Int64 |
3000000000 | Int64 | Int64 |
0.1 | Decimal | Double |
12345678901234567890 | Decimal | BigInteger |
true / false | Boolean | Boolean |
null | $null (la propiedad existe) | $null (la propiedad existe) |
"2026-11-20T08:30:00Z" | String | DateTime |
"2026-11-20" (solo fecha) | String | String |
[] vacía | Una lista vacía, no $null | $null |
La fila de las fechas es la que más sorprende: el mismo script compara texto en 5.1 y fechas en 7. Más abajo se explica cómo controlarlo.
Los comandos de JSON en PowerShell
Todo el trabajo con JSON en PowerShell gira en torno a pocos comandos. Medido con Get-Command, los parámetros propios de cada uno cambian mucho de una versión a otra:
| Comando | Para qué sirve | Parámetros en 5.1 | Parámetros en 7.7 |
|---|---|---|---|
ConvertFrom-Json | Convierte texto JSON en objetos | InputObject | InputObject, AsHashtable, Depth, NoEnumerate, DateKind |
ConvertTo-Json | Convierte objetos en texto JSON | InputObject, Depth, Compress | Los de 5.1 más EnumsAsStrings, AsArray, EscapeHandling |
Test-Json | Comprueba si un texto es JSON válido y si cumple un esquema | No existe | Existe desde la 6.1; -Path desde la 7.4 |
Get-Content -Raw | Lee el archivo entero como un solo texto | Sí | Sí |
Set-Content, Out-File | Guardan el texto en un archivo | Codificación según el comando | UTF-8 sin BOM por defecto |
Invoke-RestMethod | Pide datos a una API y convierte el JSON solo | Sí | Sí |
Según la referencia oficial, -AsHashtable llegó en la 6.0, -Depth de ConvertFrom-Json en la 6.2 (con 1.024 niveles por defecto) y -DateKind en la 7.5. Dicho de otro modo, un script que use cualquiera de ellos falla en Windows PowerShell 5.1 con «No se encuentra ningún parámetro que coincida con el nombre del parámetro», que es el error que se ve al ejecutar en un servidor un script escrito en el portátil. Para ver la versión de la consola, escriba $PSVersionTable.PSVersion.
Leer un archivo JSON en PowerShell
La forma correcta de leer un archivo JSON en PowerShell es leerlo entero con -Raw, decir en qué codificación está y pasarlo a ConvertFrom-Json:
$config = Get-Content -Path 'C:\Scripts\config.json' -Raw -Encoding UTF8 | ConvertFrom-Json
$config.sede
$config.alertas.correo
$config.equipos | Format-Table nombre, ip
A partir de ahí, las propiedades se leen con el punto: $config.alertas.activas devuelve True y $config.equipos[1].nombre devuelve PC-002. Si una clave tiene espacios, puntos o guiones, va entre comillas:
$persona = '{"nombre completo":"Ana Pérez","ip.privada":"10.0.0.5"}' | ConvertFrom-Json
$persona.'nombre completo'
$persona.'ip.privada'
Las tildes rotas de Windows PowerShell 5.1
El parámetro -Encoding UTF8 no está de adorno. Medido con un archivo guardado en UTF-8 sin BOM, que es como lo guardan Visual Studio Code, Python, PowerShell 7 y casi cualquier herramienta moderna:
- En Windows PowerShell 5.1 sin
-Encoding,Get-Contentlo leyó con la página de códigos de Windows y$config.sededevolvió «Bogotá». No hubo error ni aviso. - Con
-Encoding UTF8, en 5.1, devolvió «Bogotá». - En PowerShell 7, «Bogotá» con y sin el parámetro, porque su codificación por defecto es UTF-8.
- Si el archivo lleva BOM (la marca de tres bytes
EF BB BFal principio), 5.1 lo detecta y lo lee bien aunque no se indique la codificación.
Así que la costumbre que evita el problema en las dos versiones es escribir siempre -Encoding UTF8 al leer.
Por qué -Raw
Sin -Raw, Get-Content entrega el archivo línea por línea. ConvertFrom-Json junta las líneas y funcionó igual en las dos versiones, pero con un archivo de 50.000 registros con formato (50.002 líneas) tardó entre 909 y 928 ms frente a 602-652 ms con -Raw, entre un 40 y un 55 % más. Con -Raw el archivo llega como un solo texto y no hay nada que juntar.
Una lista de JSON en la canalización
Cuando el archivo es una lista (empieza por [), las dos versiones se comportan distinto. Medido con 50.000 equipos y un filtro aplicado directamente a la salida de ConvertFrom-Json:
- PowerShell 7 envía cada elemento por la canalización:
Where-Objectdevolvió los 5.000 equipos que cumplían el filtro. - Windows PowerShell 5.1 envía la lista entera como un solo objeto: el mismo filtro devolvió 1 resultado, la lista completa, sin error.
La solución que funciona en las dos es poner la conversión entre paréntesis o guardarla antes en una variable:
(Get-Content 'C:\Scripts\equipos.json' -Raw -Encoding UTF8 | ConvertFrom-Json) | Where-Object { $_.ip -like '10.0.0.*' }
En PowerShell 7, si lo que se quiere es lo contrario (que la lista viaje entera, por ejemplo para volver a convertirla igual), existe -NoEnumerate. Es la misma trampa que aparece con las respuestas de las API, explicada con más detalle en la guía de Invoke-RestMethod.
ConvertFrom-Json: lo que cambia entre 5.1 y 7
ConvertFrom-Json en Windows PowerShell 5.1 usa el analizador antiguo de .NET Framework; en PowerShell 7 usa Newtonsoft Json.NET. Por eso un mismo archivo puede ser válido en una consola y fallar en la otra. Medido con textos de prueba:
| Caso | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
Comentarios // … dentro del JSON | Error: Se ha pasado un objeto no válido. Se esperaba ':' o '}' | Los acepta y los ignora |
| Coma después del último elemento | Error: «Primitivo JSON no válido» | La acepta |
| Comillas simples en vez de dobles | Las acepta | Las acepta |
| Falta una coma | Error con la posición | Error en inglés con línea y posición: «After parsing a value an unexpected character was encountered» |
Dos claves iguales ("a":1,"a":2) | Se queda con la última, sin aviso | Se queda con la última, sin aviso |
Claves que solo cambian en mayúsculas (id, Id) | Error: contiene las claves duplicadas | Error, y sugiere usar -AsHashtable |
Clave vacía ("":1) | Error: el valor del argumento «name» no es válido | Error, solo se admite con -AsHashtable |
| 150 niveles de anidación | Error: «Se ha superado el valor de RecursionLimit» | Lo lee (el límite por defecto es 1.024) |
Dos filas merecen atención. Las claves repetidas no dan error en ninguna versión: si un archivo de configuración tiene dos veces la misma clave, gana la última y nadie se entera. Y los archivos con comentarios, habituales en la configuración de Visual Studio Code o de Windows Terminal, solo se leen en PowerShell 7.
ConvertFrom-Json con -AsHashtable
Con -AsHashtable (solo PowerShell 7), el resultado es una tabla hash en vez de un objeto. Sirve en tres situaciones: cuando el JSON trae claves que solo cambian en mayúsculas, cuando trae una clave vacía y cuando se necesita comprobar si una clave existe sin recorrer propiedades. Desde la 7.3 la tabla es ordenada (OrderedHashtable) y conserva el orden del archivo; medido, {"b":1,"a":2,"B":3} dio tres claves en el orden b,a,B.
$tabla = Get-Content 'C:\Scripts\config.json' -Raw | ConvertFrom-Json -AsHashtable
$tabla['sede']
$tabla.ContainsKey('umbralDisco')
Fechas: DateKind en PowerShell 7.5 o posterior
Desde PowerShell 6, ConvertFrom-Json convierte en fecha cualquier texto con formato de fecha y hora. Medido con "2026-11-20T08:30:00Z", el resultado fue un DateTime en hora UTC (Kind igual a Utc) que la consola muestra como 08:30. En Bogotá, esa hora corresponde a las 03:30: si el script la compara con Get-Date, se equivoca en cinco horas. Para evitarlo, PowerShell 7.5 añadió -DateKind:
Valor de -DateKind | Qué devolvió con "2026-11-20T08:30:00Z" |
|---|---|
Default | DateTime en UTC, 08:30 |
Local | DateTime en hora local, 03:30 en Bogotá |
Utc | DateTime en UTC, 08:30 |
Offset | DateTimeOffset 08:30 +00:00, que conserva la zona |
String | El texto original, sin convertir |
$evento = '{"creado":"2026-11-20T13:30:00Z"}' | ConvertFrom-Json -DateKind Local
$evento.creado
$texto = '{"creado":"2026-11-20T13:30:00Z"}' | ConvertFrom-Json -DateKind String
$texto.creado
En Windows PowerShell 5.1 las fechas siempre llegan como texto y hay que convertirlas con [datetime] o [datetimeoffset]. Si el script debe funcionar en las dos versiones, -DateKind String en 7 y la conversión explícita dan el mismo resultado en ambas.
Modificar un JSON: cambiar, agregar y quitar propiedades
Una vez convertido, el JSON es un objeto normal. Cambiar un valor existente es una asignación; agregar una propiedad nueva, en cambio, no lo es. Medido en las dos versiones, $config.nueva = 1 falla con No se encuentra la propiedad "nueva" en este objeto (en 5.1, La propiedad 'nueva' no se encuentra en este objeto). Las propiedades nuevas se agregan con Add-Member, y las que sobran se quitan desde PSObject.Properties:
$ruta = 'C:\Scripts\config.json'
$config = Get-Content $ruta -Raw -Encoding UTF8 | ConvertFrom-Json
$config.umbralDisco = 10
$config.equipos += [pscustomobject]@{ nombre = 'PC-003'; ip = '10.0.0.13' }
$config | Add-Member -NotePropertyName 'actualizado' -NotePropertyValue (Get-Date -Format 'yyyy-MM-dd')
$config.PSObject.Properties.Remove('alertas')
Al volver a convertirlo, el umbral quedó en 10, la lista con tres equipos y la propiedad actualizado en su sitio, en las dos versiones. Y += funciona porque la lista se reconstruye entera en cada vuelta; para unos pocos elementos no importa, pero en la guía de PowerShell se midieron 77 segundos para llenar 50.000 elementos así en 5.1, de modo que en bucles grandes conviene recoger la salida del bucle en una variable. Si estas modificaciones se repiten en varios scripts, conviene envolverlas en una función con parámetros, como se explica en la guía de funciones en PowerShell.
Guardar un archivo JSON en PowerShell con ConvertTo-Json
Para guardar un archivo JSON en PowerShell se convierte el objeto con ConvertTo-Json y se escribe el texto con Set-Content. Hay tres decisiones que cambian el resultado: la profundidad, la codificación del archivo y el formato. En PowerShell 7 basta con esto:
$config | ConvertTo-Json -Depth 10 | Set-Content -Path 'C:\Scripts\config.json' -Encoding utf8NoBOM
La profundidad: -Depth
ConvertTo-Json solo baja dos niveles por defecto. Medido en las dos versiones, un objeto de cuatro niveles se guardó como {"a":{"b":{"c":"System.Collections.Hashtable"}}}: el tercer nivel desapareció y en su lugar quedó el nombre del tipo. Las listas cuentan como un nivel más, así que @{ lista = @(@{ a = @{ b = 1 } }) } también se cortó en a. PowerShell 7 avisa con «El JSON resultante se trunca porque la serialización ha superado la profundidad establecida de 2»; Windows PowerShell 5.1 no avisa. El máximo es 100 en las dos versiones. La regla es poner siempre -Depth con margen, por ejemplo 10. El efecto de esta trampa al enviar datos a una API se explica en la guía de Invoke-RestMethod.
La codificación del archivo
Es la trampa que más archivos rompe, porque el JSON se ve bien en la consola y falla en el programa que lo lee. Medido con el mismo objeto (con «Bogotá» dentro) guardado de cuatro maneras:
| Cómo se guarda | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
Out-File | UTF-16 (empieza por FF FE), 514 bytes | UTF-8 sin BOM, 150 bytes |
Set-Content | Página de códigos de Windows: las tildes no son UTF-8 | UTF-8 sin BOM |
Set-Content -Encoding UTF8 | UTF-8 con BOM (EF BB BF) | UTF-8 sin BOM |
Out-File -Encoding utf8 | UTF-8 con BOM | UTF-8 sin BOM |
El BOM tampoco es inofensivo. El archivo que Windows PowerShell 5.1 guardó con -Encoding UTF8 lo abrió el módulo json de Python con el error «Unexpected UTF-8 BOM», y lo mismo les pasa a otros programas que siguen la norma de JSON al pie de la letra. El de PowerShell 7 lo abrió sin problema. Para guardar UTF-8 sin BOM desde 5.1, el camino que funcionó fue escribir con .NET:
$json = $config | ConvertTo-Json -Depth 10
$utf8SinBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText('C:\Scripts\config.json', $json, $utf8SinBom)
WriteAllText necesita la ruta completa: con una ruta relativa usa la carpeta del proceso, que no siempre es la de la consola.
El formato: sangría, orden y caracteres especiales
El texto que genera ConvertTo-Json también cambia según la versión:
| Detalle | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
| Sangría | Cuatro espacios y alineaciones extrañas en las listas | Dos espacios, como un editor |
< > & ' | Escapados como \u003c, \u003e, \u0026, \u0027 | Tal cual; se escapan con -EscapeHandling EscapeHtml |
| Tildes | Tal cual | Tal cual; con -EscapeHandling EscapeNonAscii salen como \u00e1 |
Fechas ([datetime]) | "\/Date(1795181400000)\/" | "2026-11-20T08:30:00" |
Enumeraciones (DayOfWeek) | El número: 5 | El número; con -EnumsAsStrings, "Friday" |
-Compress (todo en una línea) | Sí | Sí |
La fila de las fechas es la que rompe integraciones: el formato \/Date(…)\/ de 5.1 no lo entiende casi ningún programa actual. Si el script corre en 5.1, conviene guardar las fechas como texto ISO con (Get-Date).ToString('o').
El orden de las claves depende del origen. Una tabla hash normal (@{ }) no guarda el orden: medido, @{ zeta = 1; alfa = 2; medio = 3; beta = 4 } salió como beta, zeta, medio, alfa en 5.1 y alfa, medio, beta, zeta en 7. Con [ordered]@{ } sale en el orden escrito, igual que un objeto leído de un archivo:
[ordered]@{
equipo = $env:COMPUTERNAME
revisado = (Get-Date).ToString('o')
estado = 'OK'
} | ConvertTo-Json
Listas de un solo elemento
Por la canalización, una lista de un elemento pierde los corchetes. Medido en las dos versiones, @([pscustomobject]@{ id = 1 }) | ConvertTo-Json -Compress dio {"id":1}, un objeto, y el programa que esperaba una lista falla. Hay dos soluciones: pasar la lista con -InputObject o, solo en PowerShell 7, usar -AsArray:
$equipos = @(Get-CimInstance Win32_ComputerSystem | Select-Object Name, Model)
ConvertTo-Json -InputObject @($equipos) -Depth 3
$equipos | ConvertTo-Json -AsArray
La arroba de -InputObject @($equipos) no sobra. En Windows PowerShell 5.1, -InputObject con una lista recién salida de ConvertFrom-Json produjo {"value":[{"id":1},{"id":2}],"Count":2}: un objeto envoltorio que no es lo que había en el archivo. Con @( ) salió la lista correcta en las dos versiones.
Objetos de PowerShell con más datos de la cuenta
ConvertTo-Json guarda todas las propiedades del objeto, también las que la consola no muestra. Medido con un archivo de texto de dos líneas:
- En Windows PowerShell 5.1,
Get-Content archivo.txt | ConvertTo-Jsonprodujo 1.745 caracteres: cada línea salió conPSPath,PSParentPath,PSDrivey el proveedor de archivos completo. - En PowerShell 7, el mismo comando dio
["uno","dos"], 13 caracteres. - Con las líneas convertidas antes en texto puro, las dos versiones dieron lo mismo:
[string[]]$lineas = Get-Content 'C:\Scripts\equipos.txt'
ConvertTo-Json -InputObject $lineas
Lo mismo pasa con otros objetos: un solo archivo de Get-Item, convertido con -Depth 1, ocupó 4.582 caracteres en 5.1 y 3.714 en 7, y con Select-Object Name, Length, LastWriteTime antes de convertir quedó en menos de 90. Elegir las propiedades con Select-Object antes de ConvertTo-Json es la forma de obtener un JSON limpio.
Validar un JSON: Test-Json
PowerShell 7 trae Test-Json, que dice si un texto o un archivo es JSON válido y, con un esquema, si tiene las claves y los valores esperados. Es la forma de comprobar un archivo de configuración antes de que el script lo use:
Test-Json -Path 'C:\Scripts\config.json'
$esquema = @'
{
"type": "object",
"required": ["empresa", "umbralDisco"],
"properties": { "umbralDisco": { "type": "integer", "minimum": 1, "maximum": 50 } }
}
'@
Test-Json -Path 'C:\Scripts\config.json' -Schema $esquema
Medido: el archivo de ejemplo pasó el esquema y uno con "umbralDisco": 80 no, con el mensaje El JSON no es válido con el esquema: 80 should be at most 50 en "/umbralDisco", que mezcla español e inglés pero dice exactamente qué valor falla y dónde.
Hay una incoherencia que conviene conocer. Desde la 7.4, Test-Json usa otro analizador que ConvertFrom-Json y rechaza por defecto los comentarios y la coma final, que ConvertFrom-Json sí acepta en PowerShell 7. Medido, {"a":1,} dio False con Test-Json y se leyó sin problema con ConvertFrom-Json. Para aceptarlos existe -Options IgnoreComments, AllowTrailingCommas.
Windows PowerShell 5.1 no tiene Test-Json. La alternativa es intentar la conversión dentro de un try, como se explica en la guía de try catch en PowerShell:
function Test-JsonTexto([string]$Texto) {
try { $null = $Texto | ConvertFrom-Json -ErrorAction Stop; $true }
catch { $false }
}
Test-JsonTexto (Get-Content 'C:\Scripts\config.json' -Raw -Encoding UTF8)
Comparar dos JSON en PowerShell
Comparar dos versiones de un archivo (la configuración de ayer y la de hoy, el inventario del mes pasado y el actual) parece trabajo para Compare-Object, pero sin cuidado da un resultado falso. Medido en las dos versiones con dos objetos de JSON distintos (umbral 15 frente a 10):
Compare-Object $antes $despuesdevolvió 0 diferencias. Compara el texto de cada objeto, y el de un objeto leído de JSON está vacío, así que todos parecen iguales.Compare-Object $antes $despues -Property *falló con «El método especificado no es compatible».Compare-Object $antes $despues -Property umbral, sedesí mostró la diferencia.
Con listas de objetos, que es el caso de un inventario, la solución es nombrar las propiedades que identifican cada elemento. Medido con dos inventarios en los que el PC-002 cambió de IP y apareció un PC-003, el resultado fueron tres líneas: la IP vieja del PC-002 en el lado izquierdo (<=), la nueva y el equipo nuevo en el derecho (=>):
$antes = Get-Content 'C:\Scripts\inventario-antes.json' -Raw -Encoding UTF8 | ConvertFrom-Json
$despues = Get-Content 'C:\Scripts\inventario-despues.json' -Raw -Encoding UTF8 | ConvertFrom-Json
Compare-Object $antes $despues -Property nombre, ip
Para dos objetos sueltos, como dos versiones de un archivo de configuración, sirve comparar propiedad por propiedad. Esta función convierte cada valor a JSON compacto, así que también detecta cambios dentro de objetos y listas:
function Compare-JsonObjeto($Antes, $Despues) {
$nombres = @($Antes.PSObject.Properties.Name) + @($Despues.PSObject.Properties.Name) | Sort-Object -Unique
foreach ($n in $nombres) {
$a = $Antes.$n | ConvertTo-Json -Depth 10 -Compress
$d = $Despues.$n | ConvertTo-Json -Depth 10 -Compress
if ($a -ne $d) { [pscustomobject]@{ Propiedad = $n; Antes = $a; Despues = $d } }
}
}
Compare-JsonObjeto -Antes $configAyer -Despues $configHoy
Comparar los dos archivos enteros convertidos en una línea no sirve: medido, dos objetos con los mismos datos en distinto orden dieron False.
JSON a CSV con PowerShell
Pasar de JSON a CSV con PowerShell es la forma más rápida de llevar una exportación o la respuesta de una API a Excel. El problema son los datos anidados: Export-Csv escribe cada propiedad como texto y lo que no es texto sale con el nombre de su tipo. Medido en las dos versiones con el archivo de ejemplo, la columna equipos salió como System.Object[] y la columna alertas como @{correo=mesa@empresa.com; activas=True}.
La solución es aplanar antes de exportar: una fila por elemento de la lista y propiedades calculadas para lo que viene de niveles superiores.
$config = Get-Content 'C:\Scripts\config.json' -Raw -Encoding UTF8 | ConvertFrom-Json
$config.equipos |
Select-Object @{ n = 'Empresa'; e = { $config.empresa } }, @{ n = 'Sede'; e = { $config.sede } }, nombre, ip |
Export-Csv -Path 'C:\Scripts\equipos.csv' -NoTypeInformation -Encoding UTF8 -Delimiter ';'
El resultado fueron dos filas limpias, "KHARONTE";"Bogotá";"PC-001";"10.0.0.11" y la del PC-002. Tres detalles para que Excel lo abra bien:
-Delimiter ';', porque Excel con la configuración regional de Colombia separa con punto y coma; con coma, todo cae en la primera columna. Lo medimos al preparar la guía de Active Directory con PowerShell.- El BOM, que aquí sí ayuda: Excel lo necesita para mostrar las tildes de un CSV. Medido,
-Encoding UTF8lo añade en Windows PowerShell 5.1 pero no en PowerShell 7, dondeUTF8significa UTF-8 sin BOM; en 7 hay que escribir-Encoding utf8BOM, que en 5.1 no existe. Los ejemplos usanUTF8para que funcionen en las dos: en PowerShell 7, cámbielo porutf8BOMsi el archivo va a Excel. -NoTypeInformationevita en 5.1 una primera línea#TYPE. En PowerShell 7 ya no hace falta y muestra un aviso de parámetro obsoleto, sin efecto en el archivo.
Si un campo es una lista de valores simples, como los planes de licencia de un usuario, basta con unirlos en una sola celda:
$licencias = '[{"usuario":"ana@empresa.com","planes":["E3","Teams"]},{"usuario":"luis@empresa.com","planes":["E1"]}]' | ConvertFrom-Json
$licencias |
Select-Object usuario, @{ n = 'Planes'; e = { $_.planes -join ', ' } } |
Export-Csv -Path 'C:\Scripts\licencias.csv' -NoTypeInformation -Encoding UTF8 -Delimiter ';'
El camino contrario, de CSV a JSON, es directo: Import-Csv 'C:\Scripts\equipos.csv' -Delimiter ';' | ConvertTo-Json.
Rendimiento con archivos grandes
Para saber hasta dónde llega, se generó un archivo de 50.000 registros (3,55 MB) con cinco propiedades cada uno. Medido:
| Operación | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
Leer con Get-Content -Raw y ConvertFrom-Json | Entre 0,6 y 0,8 s | Entre 0,65 y 1,1 s |
Leer sin -Raw (archivo con formato, 50.002 líneas) | 0,93 s | 0,91 s |
| Convertir a JSON por la canalización | 1,0 s | 1,0 s |
Convertir con -InputObject | 0,8 s | 0,7 s |
| Filtrar los 5.000 con disco por encima de 90 | 1,15 s | 0,31 s |
Leer y escribir cuestan casi lo mismo en las dos versiones; lo que gana PowerShell 7 es el trabajo con los objetos, casi cuatro veces más rápido al filtrar. Para archivos de decenas de megas ya conviene pensar en otro formato o en una base de datos, porque todo el archivo se carga en memoria.
Escenarios de JSON en PowerShell para administradores
Un archivo de configuración para un script
Separar la configuración del código es la mejor razón para usar JSON en PowerShell: el mismo script sirve para varias sedes o clientes cambiando solo el archivo, y quien ajusta un umbral no toca el código. Este ejemplo revisa los discos del equipo con el umbral del archivo y avisa de los que tienen poco espacio:
$rutaConfig = 'C:\Scripts\config.json'
$config = Get-Content $rutaConfig -Raw -Encoding UTF8 | ConvertFrom-Json
$umbral = if ($config.umbralDisco) { $config.umbralDisco } else { 15 }
Get-CimInstance Win32_LogicalDisk -Filter 'DriveType=3' | ForEach-Object {
$libre = [math]::Round($_.FreeSpace / $_.Size * 100, 1)
if ($libre -lt $umbral) {
[pscustomobject]@{ Equipo = $env:COMPUTERNAME; Unidad = $_.DeviceID; LibrePorcentaje = $libre; Avisar = $config.alertas.correo }
}
}
El valor por defecto (15) evita que el script se rompa si alguien borra la clave del archivo. Si el script corre en una tarea programada, conviene validar el archivo antes con Test-Json o la función de 5.1, porque un JSON mal escrito a las tres de la mañana no lo ve nadie; cómo se monta la tarea está en la guía de tareas programadas con PowerShell.
Inventario de un equipo en JSON
JSON guarda bien lo que un CSV no puede: un equipo con varios discos en un solo registro. Este bloque genera la ficha del equipo con la fecha en formato ISO y la guarda con el nombre del equipo:
$so = Get-CimInstance Win32_OperatingSystem
$inventario = Get-CimInstance Win32_ComputerSystem | ForEach-Object {
[ordered]@{
equipo = $_.Name
fabricante = $_.Manufacturer
modelo = $_.Model
memoriaGB = [math]::Round($_.TotalPhysicalMemory / 1GB, 1)
sistema = $so.Caption
discos = @(Get-CimInstance Win32_LogicalDisk -Filter 'DriveType=3' | ForEach-Object {
[ordered]@{ unidad = $_.DeviceID; libreGB = [math]::Round($_.FreeSpace / 1GB, 1) } })
revisado = (Get-Date).ToString('o')
}
}
$inventario | ConvertTo-Json -Depth 5 | Set-Content "C:\Scripts\inventario-$env:COMPUTERNAME.json" -Encoding UTF8
En Windows PowerShell 5.1, -Encoding UTF8 deja el archivo con BOM, que PowerShell lee sin problema; si lo va a leer otro programa, guárdelo con WriteAllText como se explicó antes.
Con fichas como esta guardadas cada mes, comparar dos inventarios es el Compare-Object con -Property del apartado anterior. Para inventarios de muchos equipos a la vez, el mismo bloque se ejecuta en remoto con PowerShell remoto.
Respuesta de una API convertida en informe
Invoke-RestMethod ya entrega el JSON convertido, así que el paso a Excel es el mismo aplanado de antes. Este ejemplo consulta las cinco últimas versiones de PowerShell en la API pública de GitHub y las deja en un CSV:
$versiones = Invoke-RestMethod 'https://api.github.com/repos/PowerShell/PowerShell/releases?per_page=5' -Headers @{ 'User-Agent' = 'inventario' }
$versiones |
Select-Object tag_name, published_at, @{ n = 'Archivos'; e = { @($_.assets).Count } } |
Export-Csv -Path 'C:\Scripts\versiones.csv' -NoTypeInformation -Encoding UTF8 -Delimiter ';'
Otras herramientas de administración también exportan en JSON: winget export guarda la lista de programas instalados en un archivo JSON que se lee con ConvertFrom-Json, como se ve en la guía de winget.
Errores comunes con JSON en PowerShell
- Leer sin
-Encoding UTF8en 5.1. Las tildes salen como «Bogotá» y nada avisa. - Olvidar
-Depthal guardar. A partir del tercer nivel, el archivo guarda «System.Collections.Hashtable» en lugar de los datos. - Guardar con
Out-FileoSet-Contenten 5.1 sin pensar en la codificación.Out-Fileescribe UTF-16,Set-Contentla página de códigos de Windows y-Encoding UTF8añade un BOM que Python rechaza. - Rutas de Windows sin duplicar la barra. Medido en las dos versiones,
"C:\temp"se leyó sin error como «C:», un tabulador y «emp», porque\tes un escape válido;"C:\nuevos"metió un salto de línea, y"C:\temp\logs"falló con «Secuencia de escape no reconocida» en 5.1 y «Bad JSON escape sequence» en 7. Dentro de un JSON escrito a mano, cada barra va doble:"C:\\temp".ConvertTo-Jsonlas duplica solo. - Filtrar la salida de
ConvertFrom-Jsondirectamente en 5.1. La lista entra como un solo objeto; use paréntesis. - Comparar objetos con
Compare-Objectsin-Property. Da cero diferencias aunque las haya. - Esperar corchetes en una lista de un elemento. Por la canalización sale un objeto; use
-InputObject @($lista)o-AsArray. - Asignar una propiedad que no existe. Falla; use
Add-Member. - Archivos con comentarios o coma final en 5.1. Solo PowerShell 7 los lee, y
Test-Jsonlos rechaza salvo con-Options. - Claves repetidas. No dan error: gana la última y la primera se pierde sin aviso.
- Fechas UTC tratadas como locales en PowerShell 7. Use
-DateKind LocaloOffset, o compare en UTC. - Fechas de 5.1 guardadas con
ConvertTo-Json. Salen como\/Date(…)\/; guárdelas como texto ISO. - Usar parámetros de 7 en un servidor con 5.1.
-AsHashtable,-AsArray,-DateKindyTest-Jsonno existen allí. - Convertir objetos completos de PowerShell.
Get-ContentoGet-Itemmeten propiedades ocultas; elija las que necesita conSelect-Object. - Exportar a CSV sin aplanar. Las listas salen como
System.Object[]. - Tablas hash normales cuando importa el orden. Use
[ordered]@{ }.
Recomendaciones para trabajar con JSON en PowerShell
- Prefiera PowerShell 7 para scripts nuevos. Lee comentarios y comas finales, guarda UTF-8 sin BOM, trae
Test-Json,-AsHashtabley-DateKind, y filtra casi cuatro veces más rápido. - Si el script debe correr en 5.1, escriba siempre
-Raw -Encoding UTF8al leer,-Depthal guardar, paréntesis antes de filtrar y fechas como texto ISO. - Guarde la configuración en JSON y no en el código, con valores por defecto para cada clave y una validación antes de usarla.
- Elija las propiedades antes de convertir y use
[ordered]para que el archivo sea legible y estable entre ejecuciones. - Guarde una copia antes de modificar un archivo de configuración de otro programa: un JSON roto puede impedir que ese programa arranque.
- Edite los archivos JSON en un editor que valide la sintaxis, como Visual Studio Code; en la guía de PowerShell ISE vs Visual Studio Code se explica cómo configurarlo para PowerShell.
- Consulte la referencia oficial de ConvertFrom-Json en Microsoft Learn cuando cambie de versión: los parámetros siguen creciendo.
JSON en PowerShell en la administración diaria
JSON en PowerShell es el puente entre los scripts y casi todo lo demás: las API, los archivos de configuración, las exportaciones de las consolas y los informes para Excel. Con -Raw -Encoding UTF8 al leer, -Depth y la codificación correcta al guardar, Select-Object antes de convertir y las diferencias entre 5.1 y 7 presentes, los archivos dejan de romperse en el equipo de otra persona.
En KHARONTE usamos este tipo de scripts en el soporte TI a nuestros clientes: revisiones de equipos con la configuración en un archivo, inventarios en JSON y comparaciones entre un mes y el siguiente, siempre documentados en la mesa de ayuda TI. Si su empresa busca soporte técnico para empresas o quiere conocer nuestros servicios administrados de TI, revise los servicios de TI para empresas o escríbanos.




