ConvertTo-Json to wbudowany cmdlet PowerShell, który zamienia obiekty .NET (cokolwiek wypluje pipeline — wynik Get-Process, hashtable, własną klasę) na tekst w formacie JSON. Przyda Ci się, gdy chcesz wysłać dane do REST API, zapisać konfigurację do pliku albo po prostu zobaczyć obiekt w czytelnej, ustrukturyzowanej formie zamiast domyślnej tabelki. To odpowiednik json.dumps z Pythona, tyle że dostajesz go w terminalu za darmo.
Składnia i najważniejsze opcje
Najczęściej używasz go na końcu potoku:
-Depth— ile poziomów zagnieżdżenia obiektów ma trafić do JSON-a (od 0 do 100). To najważniejsza flaga, którą musisz znać.-Compress— usuwa wcięcia i białe znaki, daje JSON w jednej linii. Idealne, gdy wysyłasz payload do API i nie chcesz puchnięcia danych.-InputObject— pozwala podać obiekt jako parametr zamiast przez potok.-AsArray— wymusza zwrócenie tablicy nawet dla pojedynczego obiektu (PowerShell 6+). Ratuje, gdy API zawsze oczekuje listy.-EnumsAsStrings— serializuje wartości typu enum jako nazwy tekstowe, a nie liczby (PowerShell 6+).-EscapeHandling— kontroluje escapowanie znaków:Default,EscapeNonAsciilubEscapeHtml(PowerShell 7+).
Przykłady użycia
Get-Process | Select-Object Name, Id, CPU | ConvertTo-Json— eksportuje listę procesów z wybranymi polami do czytelnego JSON-a.@{ nazwa = "serwer01"; port = 8080; aktywny = $true } | ConvertTo-Json— zamienia hashtable na obiekt JSON, świetne do budowania configów ręcznie.Get-Service | ConvertTo-Json -Compress | Out-File services.json— zapisuje stan usług do pliku w wersji jednoliniowej.Get-ChildItem C:\Logs | ConvertTo-Json -Depth 5— wyciąga głębiej zagnieżdżone właściwości obiektów plików, których domyślny depth by nie złapał.$body = $dane | ConvertTo-Json; Invoke-RestMethod -Uri $url -Method Post -Body $body— typowy duet: serializujesz dane i strzelasz nimi do API.
Częste błędy i pułapki
Domyślny -Depth różni się między wersjami. W Windows PowerShell 5.1 (tym z pudełka Windowsa) domyślny depth to 2 — głębsze obiekty zostaną spłaszczone do napisów typu System.Object[] bez ostrzeżenia. W PowerShell 7.3+ domyślny depth podniesiono do 100, więc te same dane wyjdą inaczej. Jeśli widzisz ucięty JSON, prawie zawsze winny jest za niski depth — dodaj jawnie -Depth.
Za duży depth na obiektach z cyklami (np. żywych obiektach systemowych) potrafi wyprodukować gigantyczny output albo zalać Cię ostrzeżeniami. Serializuj tylko te pola, których naprawdę potrzebujesz — wcześniej przepuść dane przez Select-Object.
Pamiętaj też, że ConvertTo-Json serializuje aktualny stan obiektu, a nie metody — z powrotem do obiektu PowerShell odtworzysz tylko dane, nie zachowania.
Powiązane komendy: ConvertFrom-Json (droga powrotna z JSON do obiektu), ConvertTo-Csv, ConvertTo-Xml, Select-Object oraz Out-File do zapisu wyniku.