In this post I want to share with all of you my last experiences I had working with the killer feature from powershell and explain how we can work with powershell JSON file formats.

The JSON format has been used more and more across the internet, especially for Websites. REST Api can be found everywhere nowadays; Microsoft Azure, office 365, Sharepoint Online (Actually almost every ‘big’ web site). JSON is very popular, and is by far the prefered method to get information back from a REST API endpoint, since it compact, light, and easy to work with, as opposed to XML which requires a bit more ‘bandwith’ when transiting through your RJ45 cables.

Some people say that JSON will replace XML soon (Or has it already?). With the integration of Invoke-Webrequest / invoke-restMethod in PowerShell 3.0, and the other possibilities that PowerShell offer’s today,  we keep getting more and more possibilities to work with REST API end points, thus potentially with JSON file formats. (Especially with the ‘online’ technologies in the cloud.)

This post will tackle what JSON is, how it actually is similar to XML, and finally how do we use it in PowerShell JSON.

1-What is JSON, and what does JSON stands for?

For those who don’t know, JSON is a “Object format” that comes from the ‘Javascript world’. JSON actually stands for “Java Script Object Notation”.  The format is actually pretty old, since it has been created in 2005. It has been widley used around the internet, and it is about time that we start to also ;).

Some people say that it will surpass XML, and JSON will become the reference. We can write the exact same JSON structure in a JSON file then a XML structure in a XML file.

One of the reasons that JSON has become more famous is that it is less verbose then XML. This means that in order to hold equivalent information, you will need less writing in JSON, then in XML.

I also had a conversation with a friend who is a web developer, who pointed out that it is not that easy in some languages to work with the XML format. Very often they need to use Xpath to select specefic parts of code.Using JSON simplifies  things a lot, since the format is actually already an object (Especially for JavaScript developers).

We are lucky. Us, the powershell scripters. We can actually create a rich and easy to use object of XML simply by using the following two lines:

The JSON format is actually not that complicated. But we will need a short time to assimilate it if you are new to i. (Just like anything else in life).

2-JSON vs XML

The JSON file format, just like XML can be,is simple to understand when you read through it. If for example, you want to represent two different urls for a a specific site type, lets say, external and internal, you would write it like this in XML.

XML JSON example

XML example

The exact same information would be represented as followed in the JSON file format:

As you can see in this very basic example, XML and JSON actually looks very similar. But notice that the JSON example is slightly shorter in number of text / letters that has actually been written. It is not much, I agree. But when the data scales up, this could have an impact when the data will need to travel through the Internet.

On the prompt side, there is actually no difference in manipulating data that comes from an XML file, or from a JSON file as demonstrated in the example below.

PowerShell JSON vs XML

JSON vs XML

When data is the same, importing the data from XML or from a JSON file really doesn’t change our way of handling the data at the end.

2.1-The JSON format

Let’s take a short step back and go through the very basics of JavaScript Object.

An object in Javascript, is actually called an “Object Literal”.

The object literal in this example is composed of a unique property named External with a value  that is equal to “HTTP://External.PowerShellDistrict.com”.

Now, let’s take our example from above and use it as a base in order to understand the format.

Whe have SiteType, that can be either External, or Internal. I guess that you all understood that in either case, the value of the WebSite URL will be different. One important thing to know, is that in Javascript each end of data information, or object,  is ended by a coma. In this example thus, we have one object litteral, that is composed of two properties.

Notice the coma that is located at the end of the line “External”(Which was not present when we had only “External” property). It marks the separation between the two different properties External and Internal.

In JavaScript an object literal is delimited by it’s curly braces. In order to separate two objects, you will have to use a coma ,“.

Let’s illustrate this by adding a bit more information to our first object, like for example, information concerning the Author of the web pages. The JSON code will at the end, look like this:

We now have two objects: SiteType and Author.Each object literal is separated by a coma. In this example, we have thus two object literals.

2.2- JSON Arrays

Now let’s say, I am not the only Author on my blog. Imagine I have friend called “Wappi”, which is 69 years old, who comes from Strasbourg / France and who’s favorite color is Transparent, and that helps me to maintain this blog.

Let’s complete our example with his information.

As you can see above, we have added Wappi in our JSON file, and actually changed the Author: object into an Array of objects by adding the “[” and “]”. Also, the two objects contained in the Author object are separated by a coma.

If we simply this to just empty objects, it would look like this:

One object named “Author” which contains an array (delimited by the “[“ and “]”)  of two objects literals (delimited by the two “{ and }”) and are separated by a coma.

If I summarize our complete JSON file we have the following in it:

  • One object called SiteType with two properties
    • Internal
    • External
  • One object called Author which contains two author objects.
    • Stephane van Gulick
    • Wappi

3-PowerShell JSON

If I tell you that the hardest part of all of this was to understand the Javascript object literals so that you can understand the JSON format, would you believe me? Well, working with JSON in PowerShell has been made extremely simply and straight forward.

Let’s continue with our same example:

There are two cmdlets in PowerShell that works with JSON:

  • ConvertFrom-JSON
  • ConvertTo-JSON

3.1) ConvertFrom-JSON

As it’s names implies it, it will let you convert JSON data into a PowerShell object. using this cmdlet is pretty straight forward. There is one thing I noticed, is that when I had my JSON object in a file, I needed to import it using the Get-Content cmdlet with the option -RAW

ConvertFrom-JSON

Once loaded into the shell using the ConvertFrom-JSON cmdlet, we can clearly see in the image that we have two object literals: SiteType (green) and Author (Red). and that Author object actually contains  two distinct objects separated by a coma.

 One thing to keep in mind is that ConvertFrom-JSON cmdlet expects a unique single string (thus not an array of several lines of string, but one single string).

3.2) ConvertTo-JSON

The ConvertTo-Json cmdlet is pretty neat, since it allows us to convert existing data from PowerShell directly into the JSON format. Using the Get-Date cmdlet and piping it to the ConvertTo-Json cmdlet we have the following results

ConvertTo-JSON

ConvertTo-JSON-

A JSON object that contains three properties:

  • Value
  • DisplayHint
  • DateTime

This actually works with any object passed through the pipeline. Another example with Get-VHD

Get-vhd

Get-vhd in JSON format

Voila, that’s actually all that is about to know about JSON and PowerShell (Or if you have something extra to share that is missing in this article, please leave a comment :))

4-PowerShell JSON – Gottchas

There are a few gottchas when you are trying to use JSON for the first time. I will be listing them here under (And do not hesitate to add more by writing in the comment section below).

When you are working with UNC paths, you might face some errors such as “Unrecognized escape sequence. (41):” or “Unrecognized escape sequence. (43) following your JSON syntax and ending with “(raised by: ConvertFrom-Json)”

This is actually related to any UNC paths you have in your powershell json file.

Althout it looks totally correct, the following example is wrong:

and would result in the following error message when importing it with ImportFrom-Json:

Unrecognized escape sequence. (41): { “Environment”: { “VMFolder”: “E:VMRepository3”, } } (raised by: ConvertFrom-Json)

Each “” needs to be escaped to be valid in a JSON format.

The previous example would be correct like this:

5-Digg more into it (External references)

If you want to digg more into it, I would recommend the following links:

Videos:

Two VERY cool presentations on JSON made by Bob Tabor. from http://www.Learnvisualstudio.net

JSON for Begginers –> https://channel9.msdn.com/Series/Windows-Store-apps-for-Absolute-Beginners-with-C-/Part-11-Working-with-JSON-Data

Advanced JSON example –> http://channel9.msdn.com/Series/Javascript-Fundamentals-Development-for-Absolute-Beginners/Organizing-and-Simplifying-JavaScript-with-Object-Literals-12

Some Text / blogs:

Microsoft.Com JSON tutorial –> https://msdn.microsoft.com/en-us/library/bb299886.aspx

W3C Schools short introduction –> http://www.w3schools.com/json/

CopterLabs explanation on JSON file format –> http://www.copterlabs.com/blog/json-what-it-is-how-it-works-how-to-use-it/