- Reference
- Module:
- Microsoft.PowerShell.Utility
Converts an object to a JSON-formatted string.
Syntax
ConvertTo-Json [-InputObject] <Object> [-Depth <Int32>] [-Compress] [-EnumsAsStrings] [-AsArray] [-EscapeHandling <StringEscapeHandling>] [<CommonParameters>] Description
The ConvertTo-Json cmdlet converts any .NET object to a string in JavaScript Object Notation(JSON) format. The properties are converted to field names, the field values are converted toproperty values, and the methods are removed.
Note
As of PowerShell 7.2, Extended Type System properties of DateTime andString objects are no longer serialized and only the simple object isconverted to JSON format
You can then use the ConvertFrom-Json cmdlet to convert a JSON-formatted string to a JSONobject, which is easily managed in PowerShell.
Many web sites use JSON instead of XML to serialize data for communication between servers andweb-based apps.
As of PowerShell 7.1, ConvertTo-Json emits a warning if the depth of the input object exceedsthe depth specified for the command. This prevents unwanted data loss when converting objects.
This cmdlet was introduced in Windows PowerShell 3.0.
Examples
Example 1
(Get-UICulture).Calendar | ConvertTo-Json{ "MinSupportedDateTime": "0001-01-01T00:00:00", "MaxSupportedDateTime": "9999-12-31T23:59:59.9999999", "AlgorithmType": 1, "CalendarType": 1, "Eras": [ 1 ], "TwoDigitYearMax": 2029, "IsReadOnly": true}This command uses the ConvertTo-Json cmdlet to convert a GregorianCalendar object to aJSON-formatted string.
Example 2
Get-Date | ConvertTo-Json; Get-Date | ConvertTo-Json -AsArray"2021-08-05T16:13:05.6394416-07:00"[ "2021-08-05T16:13:05.6421709-07:00"]This example shows the output from ConvertTo-Json cmdlet with and without the AsArray switchparameter. You can see the second portion of the output is wrapped in array brackets.
Example 3
@{Account="User01";Domain="Domain01";Admin="True"} | ConvertTo-Json -Compress{"Domain":"Domain01","Account":"User01","Admin":"True"}This command shows the effect of using the Compress parameter of ConvertTo-Json. Thecompression affects only the appearance of the string, not its validity.
Example 4
Get-Date | Select-Object -Property * | ConvertTo-Json{ "DisplayHint": 2, "DateTime": "October 12, 2018 10:55:32 PM", "Date": "2018-10-12T00:00:00-05:00", "Day": 12, "DayOfWeek": 5, "DayOfYear": 285, "Hour": 22, "Kind": 2, "Millisecond": 639, "Minute": 55, "Month": 10, "Second": 32, "Ticks": 636749817326397744, "TimeOfDay": { "Ticks": 825326397744, "Days": 0, "Hours": 22, "Milliseconds": 639, "Minutes": 55, "Seconds": 32, "TotalDays": 0.95523888627777775, "TotalHours": 22.925733270666665, "TotalMilliseconds": 82532639.774400011, "TotalMinutes": 1375.54399624, "TotalSeconds": 82532.6397744 }, "Year": 2018}This example uses the ConvertTo-Json cmdlet to convert a System.DateTime object from theGet-Date cmdlet to a JSON-formatted string. The command uses the Select-Object cmdlet to get all(*) of the properties of the DateTime object. The output shows the JSON string thatConvertTo-Json returned.
Example 5
Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-JsonDisplayHint : 2DateTime : October 12, 2018 10:55:52 PMDate : 2018-10-12 12:00:00 AMDay : 12DayOfWeek : 5DayOfYear : 285Hour : 22Kind : 2Millisecond : 768Minute : 55Month : 10Second : 52Ticks : 636749817527683372TimeOfDay : @{Ticks=825527683372; Days=0; Hours=22; Milliseconds=768; Minutes=55; Seconds=52; TotalDays=0.95547185575463; TotalHours=22.9313245381111; TotalMilliseconds=82552768.3372; TotalMinutes=1375.87947228667; TotalSeconds=82552.7683372}Year : 2018This example shows how to use the ConvertTo-Json and ConvertFrom-Json cmdlets to convert anobject to a JSON string and a JSON object.
Parameters
-AsArray
Outputs the object in array brackets, even if the input is a single object.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Compress
Omits white space and indented formatting in the output string.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Depth
Specifies how many levels of contained objects are included in the JSON representation. The valuecan be any number from 0 to 100. The default value is 2. ConvertTo-Json emits awarning if the number of levels in an input object exceeds this number.
| Type: | Int32 |
| Position: | Named |
| Default value: | 2 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnumsAsStrings
Provides an alternative serialization option that converts all enumerations to their string representation.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EscapeHandling
Controls how certain characters are escaped in the resulting JSON output. By default, only controlcharacters (like newline) are escaped.
Acceptable values are:
- Default - Only control characters are escaped.
- EscapeNonAscii - All non-ASCII and control characters are escaped.
- EscapeHtml - HTML (
<,>,&,',") and control characters are escaped.
This parameter was introduced in PowerShell 6.2.
| Type: | Newtonsoft.Json.StringEscapeHandling |
| Position: | Named |
| Default value: | Default |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InputObject
Specifies the objects to convert to JSON format. Enter a variable that contains the objects, or typea command or expression that gets the objects. You can also pipe an object to ConvertTo-Json.
The InputObject parameter is required, but its value can be null ($null) or an empty string.When the input object is $null, ConvertTo-Json returns the JSON representation of null. Whenthe input object is an empty string, ConvertTo-Json returns the JSON representation of an emptystring.
| Type: | Object |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
Inputs
Object
You can pipe any object to this cmdlet.
Outputs
String
This cmdlet returns a string representing the input object converted to a JSON string.
Notes
The ConvertTo-Json cmdlet is implemented usingNewtonsoft Json.NET.
- An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET
- ConvertFrom-Json
- Get-Content
- Get-UICulture
- Invoke-WebRequest
- Invoke-RestMethod
- NewtonSoft.Json.StringEscapeHandling
