JSON en PowerShell: leer, modificar, validar y guardar archivos JSON

JSON en PowerShell: diez muñecas rusas pintadas a mano, ordenadas de la más grande a la más pequeña sobre un fondo negro, como los niveles de un objeto dentro de otro

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 JSONWindows PowerShell 5.1PowerShell 7.7
Objeto { }PSCustomObjectPSCustomObject (o tabla hash con -AsHashtable)
Lista [ ]Object[]Object[]
15Int32Int64
3000000000Int64Int64
0.1DecimalDouble
12345678901234567890DecimalBigInteger
true / falseBooleanBoolean
null$null (la propiedad existe)$null (la propiedad existe)
"2026-11-20T08:30:00Z"StringDateTime
"2026-11-20" (solo fecha)StringString
[] vacíaUna 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:

ComandoPara qué sirveParámetros en 5.1Parámetros en 7.7
ConvertFrom-JsonConvierte texto JSON en objetosInputObjectInputObject, AsHashtable, Depth, NoEnumerate, DateKind
ConvertTo-JsonConvierte objetos en texto JSONInputObject, Depth, CompressLos de 5.1 más EnumsAsStrings, AsArray, EscapeHandling
Test-JsonComprueba si un texto es JSON válido y si cumple un esquemaNo existeExiste desde la 6.1; -Path desde la 7.4
Get-Content -RawLee el archivo entero como un solo textoSíSí
Set-Content, Out-FileGuardan el texto en un archivoCodificación según el comandoUTF-8 sin BOM por defecto
Invoke-RestMethodPide datos a una API y convierte el JSON soloSí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-Content lo leyó con la página de códigos de Windows y $config.sede devolvió «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 BF al 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-Object devolvió 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:

CasoWindows PowerShell 5.1PowerShell 7.7
Comentarios // … dentro del JSONError: Se ha pasado un objeto no válido. Se esperaba ':' o '}'Los acepta y los ignora
Coma después del último elementoError: «Primitivo JSON no válido»La acepta
Comillas simples en vez de doblesLas aceptaLas acepta
Falta una comaError con la posiciónError 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 avisoSe queda con la última, sin aviso
Claves que solo cambian en mayúsculas (id, Id)Error: contiene las claves duplicadasError, y sugiere usar -AsHashtable
Clave vacía ("":1)Error: el valor del argumento «name» no es válidoError, solo se admite con -AsHashtable
150 niveles de anidaciónError: «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 -DateKindQué devolvió con "2026-11-20T08:30:00Z"
DefaultDateTime en UTC, 08:30
LocalDateTime en hora local, 03:30 en Bogotá
UtcDateTime en UTC, 08:30
OffsetDateTimeOffset 08:30 +00:00, que conserva la zona
StringEl 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 guardaWindows PowerShell 5.1PowerShell 7.7
Out-FileUTF-16 (empieza por FF FE), 514 bytesUTF-8 sin BOM, 150 bytes
Set-ContentPágina de códigos de Windows: las tildes no son UTF-8UTF-8 sin BOM
Set-Content -Encoding UTF8UTF-8 con BOM (EF BB BF)UTF-8 sin BOM
Out-File -Encoding utf8UTF-8 con BOMUTF-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:

DetalleWindows PowerShell 5.1PowerShell 7.7
SangríaCuatro espacios y alineaciones extrañas en las listasDos espacios, como un editor
< > & 'Escapados como \u003c, \u003e, \u0026, \u0027Tal cual; se escapan con -EscapeHandling EscapeHtml
TildesTal cualTal cual; con -EscapeHandling EscapeNonAscii salen como \u00e1
Fechas ([datetime])"\/Date(1795181400000)\/""2026-11-20T08:30:00"
Enumeraciones (DayOfWeek)El número: 5El 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-Json produjo 1.745 caracteres: cada línea salió con PSPath, PSParentPath, PSDrive y 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 $despues devolvió 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, sede sí 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 UTF8 lo añade en Windows PowerShell 5.1 pero no en PowerShell 7, donde UTF8 significa UTF-8 sin BOM; en 7 hay que escribir -Encoding utf8BOM, que en 5.1 no existe. Los ejemplos usan UTF8 para que funcionen en las dos: en PowerShell 7, cámbielo por utf8BOM si el archivo va a Excel.
  • -NoTypeInformation evita 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ónWindows PowerShell 5.1PowerShell 7.7
Leer con Get-Content -Raw y ConvertFrom-JsonEntre 0,6 y 0,8 sEntre 0,65 y 1,1 s
Leer sin -Raw (archivo con formato, 50.002 líneas)0,93 s0,91 s
Convertir a JSON por la canalización1,0 s1,0 s
Convertir con -InputObject0,8 s0,7 s
Filtrar los 5.000 con disco por encima de 901,15 s0,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

  1. Leer sin -Encoding UTF8 en 5.1. Las tildes salen como «Bogotá» y nada avisa.
  2. Olvidar -Depth al guardar. A partir del tercer nivel, el archivo guarda «System.Collections.Hashtable» en lugar de los datos.
  3. Guardar con Out-File o Set-Content en 5.1 sin pensar en la codificación. Out-File escribe UTF-16, Set-Content la página de códigos de Windows y -Encoding UTF8 añade un BOM que Python rechaza.
  4. 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 \t es 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-Json las duplica solo.
  5. Filtrar la salida de ConvertFrom-Json directamente en 5.1. La lista entra como un solo objeto; use paréntesis.
  6. Comparar objetos con Compare-Object sin -Property. Da cero diferencias aunque las haya.
  7. Esperar corchetes en una lista de un elemento. Por la canalización sale un objeto; use -InputObject @($lista) o -AsArray.
  8. Asignar una propiedad que no existe. Falla; use Add-Member.
  9. Archivos con comentarios o coma final en 5.1. Solo PowerShell 7 los lee, y Test-Json los rechaza salvo con -Options.
  10. Claves repetidas. No dan error: gana la última y la primera se pierde sin aviso.
  11. Fechas UTC tratadas como locales en PowerShell 7. Use -DateKind Local o Offset, o compare en UTC.
  12. Fechas de 5.1 guardadas con ConvertTo-Json. Salen como \/Date(…)\/; guárdelas como texto ISO.
  13. Usar parámetros de 7 en un servidor con 5.1. -AsHashtable, -AsArray, -DateKind y Test-Json no existen allí.
  14. Convertir objetos completos de PowerShell. Get-Content o Get-Item meten propiedades ocultas; elija las que necesita con Select-Object.
  15. Exportar a CSV sin aplanar. Las listas salen como System.Object[].
  16. 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, -AsHashtable y -DateKind, y filtra casi cuatro veces más rápido.
  • Si el script debe correr en 5.1, escriba siempre -Raw -Encoding UTF8 al leer, -Depth al 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.

Hablemos de la TI de su empresa

Cuéntenos qué necesita su operación y le enviamos una propuesta por escrito. Cada línea del portafolio se contrata por separado.

Compartir este artículo

Últimas entradas

Escríbanos ahora