info@teknoedu.com
PowerShell

PowerShell’de JSON ile Çalışmak: ConvertTo-Json, ConvertFrom-Json ve -Depth Tuzağı

Yapılandırma dosyalarını okumak, API'lere veri göndermek ya da nesneleri saklamak için JSON vazgeçilmezdir. ConvertTo-Json ve ConvertFrom-Json'ı, sinsi -Depth sorununu ve sürümler arası farkları örneklerle inceledik.

PowerShell'de JSON ile Çalışmak: ConvertTo-Json, ConvertFrom-Json ve -Depth Tuzağı

JSON (JavaScript Object Notation), bugün yazılım dünyasının en yaygın veri değişim biçimidir. REST API’ler JSON konuşur, VS Code ve Windows Terminal ayarları JSON’dur, birçok bulut hizmeti yapılandırmayı JSON ile alır. PowerShell’de JSON ile çalışmak iki cmdlet etrafında döner: ConvertTo-Json ve ConvertFrom-Json. Basit görünürler ama birkaç tuzakları vardır. Bu yazıda hepsini örneklerle ele alıyoruz.

JSON’un yapısı ve PowerShell karşılıkları

JSON’da yalnızca birkaç veri türü vardır ve her birinin PowerShell’de doğal bir karşılığı bulunur:

JSON Örnek PowerShell karşılığı
Nesne {"ad": "Ali"} PSCustomObject (veya hashtable)
Dizi [1, 2, 3] Object[]
Metin "Ankara" String
Sayı 42, 3.14 Int64, Double vb.
Mantıksal true $true
Boş null $null

JSON dosyası okumak: ConvertFrom-Json

Bir betiğin ayarlarını kodun içine gömmek yerine bir JSON dosyasında tutmak iyi bir alışkanlıktır. Örnek bir ayarlar.json:

{
  "OrtamAdi": "Uretim",
  "LogKlasoru": "D:\\Logs",
  "SaklamaGun": 30,
  "Bildirim": {
    "Aktif": true,
    "Alicilar": ["bt@okul.k12.tr", "mudur@okul.k12.tr"]
  }
}

JSON’da ters eğik çizginin \\ şeklinde kaçırıldığına dikkat edin. Dosyayı okumak için:

$ayar = Get-Content -Path .\ayarlar.json -Raw | ConvertFrom-Json

$ayar.OrtamAdi                 # Uretim
$ayar.SaklamaGun + 5           # 35 (sayı olarak gelir)
$ayar.Bildirim.Alicilar[0]     # bt@okul.k12.tr

Burada -Raw parametresi önemlidir. Get-Content normalde dosyayı satır satır gönderir; -Raw ise tamamını tek bir metin olarak verir. JSON tek bir bütün olarak ayrıştırılması gereken bir yapı olduğu için -Raw kullanmayı alışkanlık hâline getirin.

CSV’den farklı olarak JSON’daki sayılar ve mantıksal değerler doğru türde gelir. Bu, yapılandırma dosyaları için JSON’u CSV’den daha uygun kılar.

Nesneyi JSON’a çevirmek: ConvertTo-Json

$sunucu = [pscustomobject]@{
    Ad      = 'SRV-DOSYA01'
    IP      = '10.0.0.15'
    Roller  = @('Dosya', 'Yazdırma')
    Aktif   = $true
}

$sunucu | ConvertTo-Json
$sunucu | ConvertTo-Json -Compress   # tek satır, boşluksuz

Ayar dosyasını güncelleyip geri yazmak da aynı kolaylıktadır:

$ayar.SaklamaGun = 60
$ayar | ConvertTo-Json -Depth 5 | Set-Content -Path .\ayarlar.json -Encoding UTF8

-Depth tuzağı

ConvertTo-Json‘ın en bilinen tuzağı varsayılan derinliğin 2 olmasıdır. Daha derin iç içe yapılar sessizce metne dönüştürülür:

$veri = @{
    Okul = @{
        Bina = @{
            Kat = @{ No = 3; Sinif = '9-A' }
        }
    }
}

$veri | ConvertTo-Json

Çıktıda Kat özelliğinin değeri bir nesne yerine "System.Collections.Hashtable" gibi bir metin olur. Windows PowerShell 5.1 bu kesmeyi sessizce yapar; PowerShell 7.1 ve sonrası en azından bir uyarı gösterir. Çözüm basittir:

$veri | ConvertTo-Json -Depth 10

Pratik kural: İç içe veri yazıyorsanız her zaman -Depth belirtin. Çok büyük bir değer vermek yerine verinizin gerçek derinliğinin biraz üzerinde bir sayı seçin; çünkü bazı .NET nesneleri çok derin ve döngüsel özelliklere sahiptir, büyük derinlik devasa çıktılar üretebilir.

Bu yüzden Get-Process | ConvertTo-Json gibi komutlarda önce Select-Object ile gerekli özellikleri seçmek en iyi yoldur:

Get-Process | Select-Object Name, Id, WorkingSet64 | ConvertTo-Json

Tek elemanlı dizi sorunu

PowerShell pipeline’ı tek elemanlı dizileri “açar”. Bu yüzden bir API tek elemanlı bir dizi beklerken nesnenin kendisini gönderebilirsiniz:

@('tek') | ConvertTo-Json                         # "tek"  (dizi değil!)
ConvertTo-Json -InputObject @('tek')              # ["tek"]
@('tek') | ConvertTo-Json -AsArray                # ["tek"]  (PowerShell 7)

-InputObject ile doğrudan vermek veya PowerShell 7’de -AsArray kullanmak bu sorunu çözer. Bir nesnenin içindeki dizi özellikleri bu sorundan etkilenmez; sorun yalnızca en üst seviyede pipeline kullanırken ortaya çıkar.

Hashtable olarak okumak: -AsHashtable

PowerShell 6 ve sonrasında ConvertFrom-Json -AsHashtable ile sonucu PSCustomObject yerine hashtable olarak alabilirsiniz. Bu üç durumda işe yarar:

  • Anahtarları dinamik olarak eklemek veya silmek istediğinizde.
  • JSON’da yalnızca büyük/küçük harfle ayrışan anahtarlar olduğunda ("id" ve "Id" gibi). PSCustomObject bunu kabul etmez ve hata verir.
  • Çok büyük dosyalarda performans gerektiğinde.
$h = Get-Content .\ayarlar.json -Raw | ConvertFrom-Json -AsHashtable
$h['YeniAnahtar'] = 'deger'
$h.ContainsKey('OrtamAdi')

Sürüm farkları özet tablosu

Özellik Windows PowerShell 5.1 PowerShell 7
ConvertTo-Json -Depth varsayılanı 2 (sessiz kesme) 2 (uyarı verir)
-AsHashtable Yok Var
-AsArray Yok Var
-EnumsAsStrings Yok Var
Test-Json cmdlet’i Yok Var
JSON içinde yorum satırı Desteklenmez Okurken tolere edilir

-EnumsAsStrings parametresi, Status gibi enum değerlerini 1 yerine "Running" şeklinde yazmanızı sağlar; insan tarafından okunacak çıktılarda çok kullanışlıdır:

Get-Service -Name Spooler | Select-Object Name, Status | ConvertTo-Json -EnumsAsStrings

JSON’u doğrulamak: Test-Json

PowerShell 7’deki Test-Json, bir metnin geçerli JSON olup olmadığını kontrol eder. İsterseniz bir JSON şemasına göre de doğrulama yapabilirsiniz:

$metin = Get-Content .\ayarlar.json -Raw
if (-not (Test-Json -Json $metin -ErrorAction SilentlyContinue)) {
    throw 'ayarlar.json geçerli bir JSON değil.'
}

Bu kontrol, elle düzenlenen yapılandırma dosyalarında unutulan bir virgülün betiği yarıda kesmesini önler ve kullanıcıya anlamlı bir hata mesajı vermenizi sağlar.

Uygulama: Envanter dosyası tutmak

Bir klasördeki bilgisayarların temel bilgilerini JSON olarak saklayan basit bir örnek:

$envanter = foreach ($pc in 'PC-101','PC-102') {
    [pscustomobject]@{
        Ad        = $pc
        Kontrol   = (Get-Date).ToString('o')
        Erisilebilir = Test-Connection -ComputerName $pc -Count 1 -Quiet
    }
}

ConvertTo-Json -InputObject @($envanter) -Depth 3 |
    Set-Content -Path .\envanter.json -Encoding UTF8

Tarihi ToString('o') ile ISO 8601 biçiminde yazmak, dosyanın farklı dillerdeki araçlarla sorunsuz okunmasını sağlar.

Sık yapılan hatalar

  • -Raw unutmak: Windows PowerShell 5.1’de satır satır gelen JSON, bazı durumlarda ayrıştırma hatası verir veya beklenmedik sonuç üretir. Dosyadan okurken her zaman Get-Content -Raw kullanın.
  • Ters eğik çizgiyi kaçırmamak: Elle yazılan JSON dosyalarında Windows yolları "D:\\Logs" biçiminde, yani çift ters eğik çizgiyle yazılmalıdır; tek ters eğik çizgi geçersiz bir kaçış dizisi oluşturabilir. Dosyayı PowerShell ile üretirseniz bu kaçırma otomatik yapılır.
  • Tarihleri metin sanmak: PowerShell 7’de ConvertFrom-Json, ISO biçimindeki tarih metinlerini otomatik olarak DateTime türüne çevirir. Metin olarak karşılaştırma yapıyorsanız bu davranış sürpriz olabilir.
  • Kodlama: Türkçe karakter içeren JSON dosyalarını UTF-8 olarak yazın ve okuyun. Windows PowerShell 5.1’de Set-Content için -Encoding UTF8 belirtmeyi unutmayın.
  • API gövdesinde derinlik: Invoke-RestMethod ile gönderdiğiniz gövdeyi ConvertTo-Json -Depth ile oluşturun; iç içe bir istek gövdesinin sessizce kesilmesi, sunucudan anlaşılması zor hatalar almanıza yol açar.

Sonuç

JSON, PowerShell betiklerinizi daha esnek ve dış dünyayla uyumlu hâle getirir. Okurken Get-Content -Raw | ConvertFrom-Json kalıbını, yazarken Select-Object ile sadeleştirip ConvertTo-Json -Depth kalıbını kullanın. Tek elemanlı dizilere ve sürüm farklarına dikkat ettiğinizde, yapılandırma dosyalarından REST API’lere kadar JSON ile ilgili işlerin büyük çoğunluğunu birkaç satırla çözebilirsiniz.