If you’re supervising a network, at some point you may have had the same thought that I did: I wish I could take two commands in PowerShell and somehow merge them into one report in PowerShell. That way, I won’t have to refer to multiple outputs of data to look at something meaningful. That is something I desired when I first started to learn PowerShell. And when I first stumbled across custom PowerShell Objects, I discovered it’s entirely possible!
Welcome to PowerShell
PowerShell is a command-line object-oriented scripting environment based off the Microsoft .Net Framework. It operates through verb-noun commands that return data as an object. With Custom PowerShell Objects, you can combine the data provided via various commands/objects and report on them together in one object.
Let’s take, for instance, an Active Directory Forest that contains two Domains with one Domain Controller in each:
Shudnow.net (Forest Root)
- Domain Controller: HTPC.shudnow.net
Child.Shudnow.net (Child Domain)
- Domain Controller: 2016ChildDC.child.shudnow.net
We can run the following code to put all Domains into a variable called $ADForestDomains using the following code:
If we report on $ADForestDomains, our results would look like this:
We then want to cycle through each Domain and store all Domain Controllers within that Domain into another variable using a Foreach Loop.
Now, we have a list of all Domain Controllers within a specific Domain. We want to start putting specific Domain Controller properties into a Custom PowerShell Object. To do that, we must create another for each loop to cycle through every Domain Controller in the $DomainControllers variable and store it in a custom PowerShell Object.
Building a Custom PowerShell Object
When creating a custom PowerShell Object, we must create the object and then feed data into it. We then have an array ($DomainControllersReport) where the PowerShell Object feeds data into it at the end of the loop. This array must be declared outside of the loop, which we do by specifying $DomainControllerReport = @()
At the very end of the script, we can report on the custom PowerShell Object by reporting on $DomainController.
For example, I include a $DomainControllerReport at the very end of the script, which is the array containing the Custom PowerShell Object we pushed into our $DomainController Report Array.
The results are as follows:
But the beauty of Custom PowerShell Objects is that we can run other commands in the loop to get additional data from other commands and feed them into the Custom PowerShell Object so they are included in the array item. For example, let’s say we wanted to do a ping test on each Domain Controller and include the results as a new column in our Custom PowerShell Object.
I will include a function that allows you to ping a server and include the results, add a variable called $PingTest within the loop to do the ping test against the Domain Controller, and add a new line within the Custom PowerShell Object to add the results to the array.
If we execute the script and look at the $DomainControllerReport output, we will see there is a new column in our Custom PowerShell Object and Array data that includes the results of a ping test.
If we didn’t create a Custom PowerShell Object, there would be no way to include Domain Controller data and a ping test all in one set of results.
And because this is a Custom PowerShell Object, we can export the data using any Export- command we want, whether using Export-CSV, Export-HTML, Export-Clixml, etc.
For example, if we wanted to export the results to a CSV, we could take the $DomainControllerReport at the very bottom and change it to:
Once executed, we can navigate to C:\temp and open the DomainControllerReport.csv and it will look like this:
One Report to Rule Them All
That’s amazing, in my opinion. Now, when your boss asks you to create an Active Directory report, an Exchange Report, a Skype for Business Report or whatever other kind of report, you don’t have to give him or her a bunch of different Excel files containing various pieces of data. You can provide him or her one Excel file with fancy tables, filters, pie charts and whatever else you decide to conjure up.