The Surly Admin

How to Create HTML Reports

Find yourself creating reports in Powershell and wished they looked a little more presentable than a CSV file?  Send regular reports to your manager and want it to look professional?  Here are some technique’s I’ve developed that produce some pretty sharp reports in HTML using standard Powershell cmdlets (plus one function to pretty up your tables).

ConvertTo-HTML Limitations

By itself, the ConvertTo-HTML cmdlet is a good tool for taking our custom Objects and turning them into simple HTML tables.  I talked in more detail about objects in this post, Building PSObject Performance.  Assuming you’ve built a PSObject full of wonderful data, how do you output it so it looks nice?  The first step is ConvertTo-HTML, here’s an example:

$MyObject | ConvertTo-HTML | Out-File C:\MyReport.HTML

And here’s an example of the output:

Not a bad report, but from an aesthetics standpoint it leaves a lot to be desired.  One problem, of course, is the fields are all in the wrong order.  We can solve that by using the Select-Object cmdlet but how do we make our page look a little better?  The thing to remember is that this table is HTML, that means if you could get a custom style sheet (CSS) in there we could go a long way towards prettying this up.  As it turns out, ConvertTo-HTML allows us to do this with the -Head parameter.  Using that parameter we can insert whatever we want into the Header node of our output.  Here’s an example of putting some CSS into a here-string.

<br />$Header = @"
<style>
TABLE {border-width: 1px;border-style: solid;border-color: black;border-collapse: collapse;}
TH {border-width: 1px;padding: 3px;border-style: solid;border-color: black;background-color: #6495ED;}
TD {border-width: 1px;padding: 3px;border-style: solid;border-color: black;}
</style>
"@

$MyObject | Select 'Folder Name',Owner,'Created On','Last Updated',Size | ConvertTo-HTML -Head $Header

And here’s the output:

Now, that looks a lot better.  In fact, I’d say for most reports this would be pretty good and you could walk away.  But I like to do a little more.  Now, I’ll be the first to admit my HTML and CSS foo is pretty low, so while I’ll be showing you some techniques for making this report look better someone with mad CSS skills could take it much further.  What I can show you is how to apply those mad skills to your Powershell reporting repertory.

One thing any good report needs is a header that shows you what the report is all about, and if we have it, you may want to add some information at the bottom summing up.  I’m also going to add a tag to the $Header string to change the heading in your browser.  We accomplish this by using the -PreContent parameter, which adds your data before the table and the -PostContent parameter, which adds data after the table.

$Header = @"
<style>
TABLE {border-width: 1px;border-style: solid;border-color: black;border-collapse: collapse;}
TH {border-width: 1px;padding: 3px;border-style: solid;border-color: black;background-color: #6495ED;}
TD {border-width: 1px;padding: 3px;border-style: solid;border-color: black;}
</style>
<title>
Title of my Report
</title>
"@
$Pre = "Heading before the report"
$Post = "Footer after the report"

$MyObject | Select 'Folder Name',Owner,'Created On','Last Updated',Size | ConvertTo-HTML -Head $Header -PreContent $Pre -PostContent $Post

And our example would now look like this:

And, since the $Pre and $Post variables are simple strings you can insert any information into them that you want.  So this report is looking pretty darn good, if you ask me.  But one thing I’ve always liked, and maybe this harkens back to my days as a Computer Operator on IBM Mainframes (who remembers DOS/VSE?), but I like reports that have alternating row colors.  Especially on a report with a lot of rows in it, and as you can see from our example if we change that directory to a large folder tree we’re going to have a ton of lines!

All we need to do is tell ConvertTo-HTML to us specific CSS class names on its rows and that should take care of it, right?  And that’s the problem.  ConvertTo-HTML doesn’t have anything like that in it.  I solved this problem on my DFS Monitor Report by simply constructing the HTML myself, but honestly that’s a pain and I’d rather avoid that for simple reporting.

The first solution is to use the Set-AlternatingCSSClasses function developed by Don Jones, a Microsoft MVP that can be found over at Powershell.org.  Don wrote an interesting e-book called Creating HTML Reports in Powershell that goes into a lot of detail, covering a lot of the ground I’ve written about here so I highly recommend reading it.

But I had a problem with the function he created.   It works well for what he did, but when using it you have to use the -Fragment parameter on ConvertTo-HTML.  This parameter leaves out all of the and tags and just creates the HTML table from your objects.  That means if you want all of those tags in your final report you have to manually put them together.  Now, in fairness, that’s not super difficult as you can create multiple here-strings and just put them together.

But it’s not easy, is it?  I want things to be simple for anyone to plug into their script and produce a great report.  So I wrote my own function and called it Set-AlternatingRows.  This accepts input from the pipeline and does a simple string replacement of the tags it finds.  You do have to provide your own CSS and tell the function what they are but in your CSS you can customize the colors to anything you want–you can even customize the class names to anything you want.  Here’s what it looks like:

$Header = @"
<style>
TABLE {border-width: 1px;border-style: solid;border-color: black;border-collapse: collapse;}
TH {border-width: 1px;padding: 3px;border-style: solid;border-color: black;background-color: #6495ED;}
TD {border-width: 1px;padding: 3px;border-style: solid;border-color: black;}
.odd  { background-color:#ffffff; }
.even { background-color:#dddddd; }
</style>
<title>
Title of my Report
</title>
"@
$Pre = "Heading before the report"
$Post = "Footer after the report"

$MyObject | Select 'Folder Name',Owner,'Created On','Last Updated',Size | ConvertTo-HTML -Head $Header -PreContent $Pre -PostContent $Post | Set-AlternatingRows -CSSEvenClass even -CSSOddClass odd

Since Set-AlternatingRows accepts information from the pipeline, you don’t have to specify anything for Set-AlternatingRows, but we do have to tell it which classes in the CSS are for our even rows and what class to use for the odd rows.  That’s where the -CSSEvenClass and CSSOddClass come in.  Here’s are final report:

And that’s it, a final report.  With more HTML and CSS combinations there’s a lot you could do to make things even better but this will give you the basis to work from.  Next post I will actually break down how the function works and how to create functions that accept pipeline information.

Update 8/14/2014: And just to make things even more interesting, I recently ran across a simple one line addition to the CSS that will create the alternating rows with no additional effort!  One line!!  Both psyched because it’s cool, and a little sad at seeing the death of such a useful little reporting function.  Here’s the CSS magic:

TR:Nth-Child(Even) {Background-Color: #dddddd;}

That’s it.  Another fun CSS to add to that is a hover where the row will highlight with another color when you pass the mouse over:

TR:Hover TD {Background-Color: #C1D5F8;}

 

Source code to Set-AlternatingRows

Update 2/27/2014: If you liked reading about this, you might want to take a look at my new advanced function ConvertTo-AdvHTML.  It allows for far greater control over your HTML table!

Update 3/3/2014: So want to change the color of a cell, but don’t want to go through the hassle of ConvertTo-AdvHTML?  Here’s another advanced function that might be up your alley:  Set-CellColor.

Update 3/8/2019: Whew, 5 years later!  I have gathered my most useful HTML scripts into a module that’s been published to PowerShellGallery:  PSHTMLTools.  You can find the source on Github.

January 21, 2013 - Posted by Martin9700 | PowerShell - HTML Reporting | ConvertTo-HTML, html, Reporting, Set-AlternatingRows