Getting Started with PowerTools for Open XML Development
There are a number of resources and guidelines that PowerTools for Open XML developers need in order to write PowerShell cmdlets for processing Open XML documents. This post presents a few tips for getting started developing PowerTools cmdlets.
Getting Started
This blog is inactive.
New blog: EricWhite.com/blog
Blog TOCThe first place to start is the Windows PowerShell Programmer’s Guide. It contains lots of general information about PowerShell, what cmdlets are, as well as lots of links to other useful information.
Another important topic is Cmdlet Development Guidelines. There is a link to this page from the Windows PowerShell Programmer’s Guide page, but it is important enough to mention separately.
Many of the guidelines are incorporated into a framework within the PowerTools, so be sure not to duplicate functionality. The AllDocuments method in OpenXmlCmdlet.cs, for example, handles most of the setup for processing a document. The "access" parameter to AllDocuments determines if the document is expected to change or not. Using read/write access tells the AllDocuments method to make the proper calls to ShouldProcess, according to PowerShell guidelines. That method also handles the creation of backup files (PowerTools for Open XML by default creates backups before modifying any documents). And finally, AllDocuments will also look for documents that are piped into the cmdlet, but only if no documents are supplied as parameters for the cmdlet.
If you are building a cmdlet that will modify documents, Accept-OpenXmlChange is a good cmdlet to use as a prototype. However, you may want to look at other cmdlets for examples of how to handle specific parameters. The parameters for Accept-OpenXmlChange are the minimum needed for a cmdlet that changes documents. The cmdlet derives from OpenXmlCmdlet and must set the member variable properly for SuppressBackups. PassThru is a simple true/false value that you must handle (this parameter is in the PowerShell guidelines). The main loop of the cmdlet the collection returned by AllDocuments. Then for each document, changes are made to the document, FlushParts is called to write out those changes and then the document is either written to the output pipe using WriteObject or it is closed, depending on the value of PassThru.
Debugging a Cmdlet
In the Debug tab of the project properties, set the Start Action to start an external program and browse to find powershell.exe. Then add these command line arguments:
-noexit -command Add-PSSnapIn OpenXml.PowerTools
It is also convenient to set the Working directory to the location of your test files.
It helps to have the Build Events set to automatically install the PowerTools after each build. Set the Post-build event command line to something like this:
c:windowsMicrosoft.NETFrameworkv2.0.50727installutil.exe "$(TargetPath)"
If you are developing for 64 bit PowerShell, you will need to adjust the path to your install utility to C:WindowsMicrosoft.NETFramework642.0.50727. Make sure that it is also set to run the post-build only "On successful build."