• HowTo
• Windows PowerShell
• PowerShell HelpWriter
• Modules
• Help
• Parameters

The Rebuild feature creates a new XML help file for an existing help project. You use the Rebuild feature when the code in your module changes or a new version of the module becomes available.

Rebuild examines the code in your module, gathers the cmdlet attributes, parameters, and parameter attributes from the code and creates a new help file. When you're done rebuilding, the XML help file accurately reflects the current state of the module code.

It's really important to understand that Rebuild creates a new XML help file that replaces your existing XML help file (although we always keep a backup). It is not an update or merge (although those features are on our to-do list.).

So, before you rebuild, you need to make sure that the help file that you've been writing is added to the module that the rebuild is targeting. Want the details? See Writing XML Help for Advanced Functions.

Rebuild by Path and Rebuild by Name?

Typically, you update the help file when the code in the module changes. But, beginning in PowerShell 5.0, you can have multiple versions of the same module in the same directory or different directories on the same computer. So, "the module code changes" can mean that the same version of the module changed or you added a new version.

If you have only one version of a module on your local computer, this option has no effect.

But, if you have multiple version, you need to choose.

1. Rebuild using path: To rebuild the help file from the same version of the module that you've been working on, use Rebuild using path. Rebuild uses the module path, including any version subdirectories, to find the module.
   
   
2. Rebuild using name: To rebuild the help file from the newest version of the module that Get-Module can find on the local computer, use Rebuild by name. Rebuild uses the module name to find the module. To use Rebuild by name, the module must be in a path in $env:PSModulePath.

If you want to rebuild the help file from a different version of the module, but not the latest version, in the Properties pane for the module, change the path, and then rebuild by path.

Let's run through it...

In this example, I have two versions of a module, 1.0.0.0 and 2.0.0.0, and I want to write help for version 1.0.0.0. (Version 2 is not ready.)

PS C:\> Get-Module -ListAvailable Test-PSHelpWriter

    Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Script     2.0.0.0    Test-PSHelpWriter                   Get-CultureDate
Script     1.0.0.0    Test-PSHelpWriter                   Get-CultureDate

So, in PowerShell HelpWriter, click File, New, New Help Project (From Module).

Select version 1.0.0.0 of the module and then click Export.

And, to make sure that I get version 1.0.0.0, I select Rebuild Using Module's Path, and then click Create.

This dialog also creates my help project with a name I select (usually the module name), and saves it in the specified location. It also selects a default language folder, such as en-US.

PowerShell HelpWriter creates a help project for my module help file from version 1.0.0.0 of my module. The help project contains an XML help file for my cmdlet/function help and an About topic template for my module.

The Properties pane (on the right side of the window, by default), displays the module name, the module path, the module version, and Rebuild Using Path.

I write my help content in the designer. PowerShell HelpWriter gets the cmdlet attributes, parameters, and parameter attributes from my code and creates valid XML for my help file. I don't even need to think about it.

To copy the help files into the module directory, in the Project pane, click Deploy.

You can use the other icons in the project pane to open the module directory, open the help directory, and other useful tasks.

To enable Get-Help to find help for the functions in my module, I add the .ExternalHelp comment keyword with the name of the XML help file. (You don't need to do this for cmdlets, workflows, or CIM commands. They're automatically associated with the help file by name.) For details, see Writing XML Help for Advanced Functions.

Finally, to test my help topic, I use Get-Help.

Rebuild the same version (by path)

If the code in version 1.0.0.0 of my module changes, I can rebuild the help file for version 1.0.0.0.

For example, in version 1.0.0.0 of my .psm1 file, I changed the Date parameter from mandatory to optional. Now, I want to rebuild my help file.

Rebuilding is not required, of course. I could just uncheck the Required checkbox in the PowerShell HelpWriter designer. Typically, you rebuild when the changes are more numerous or more complex or you're working with a team.

Important!
Before rebuilding, be sure to add the ExternalHelp comment keyword with the name of the XML help file to any functions in your module. Rebuilding creates your help file from scratch. For details, see Writing XML Help for Advanced Functions.

To rebuild the help file for the same version of the module.

1. In the Properties pane, set Rebuild Using to Path.
2. On Home tab, in the Project group, click Rebuild.

 Now, you have a choice:

1. To rebuild the help file in the help project and copy the new draft help file to the module, click Deploy to and rebuild help from the module.
   
   
2. To rebuild the help file in the help project, but not copy it to the module (yet), click Rebuild help from the module. (To copy the help file to the module at any time, click Deploy. There's a Deploy icon in the Project pane and a Deploy button on the ribbon in the Project group.)

Done. Now my help file matches my function code. And, I can update my parameter description.

Rebuild the newest version (by name)

Eventually the code in version 2.0.0.0 of my module stabilizes and it's time to build a help file for it. I can create a new help project for the new version or rebuild the help file with code from the new version. In this case, I want to start with the help from version 1.0.0.0 and adjust it to work for version 2.0.0.0.

1. To start with the 1.0.0.0 version of the help file, copy the help files from version 1.0.0.0 to the language-specific subdirectory of the module directory for version 2.0.0.0.
   
   

   PS C:\ > $ModulePath = $home\Documents\WindowsPowerShell\Modules\Test-PSHelpWriter
   PS C:\ > Copy-Item $ModulePath\1.0.0.0\en-US -Recurse -Destination $ModulePath\2.0.0.0

2. Make sure that all functions in version 2.0.0.0 of the module have the ExternalHelp keyword. For details, see Writing XML Help for Advanced Functions.
   

   
   

    

3. To rebuild the help file for the newest version of the same module, in the Properties pane, set Rebuild Using to Name.

   

    

   TIP: To determine which module and version PowerShell HelpWriter will use in the rebuild process, click Refresh Module Info. This step is not required.

   If PowerShell HelpWriter finds a new version of the module, it asks you if you want to rebuild or rebuild and deploy. So, you can create and deploy your new help files right here.

   

    

4. On Home tab or in the Project group menu, click Rebuild.

The Output pane (bottom of the window) shows that PowerShell HelpWriter built the help file from the code in version 2.0.0.0 of the module.

The Properties pane shows that HelpWriter is targeting version 2.0.0.0 of the module.

And the designer has imported the newest cmdlet attributes, parameters, and parameter attributes into my help file, including the new type for the Culture parameter.

Where are my backups?

Backups are critical, because the Rebuild feature builds a new help file from scratch. It does not update your current help file. (We're working on that feature, too.)

So, if you ever need an older version of a help file, you can find them in the Help_Backup directory of the help project.

What do you need?

Now that we have help projects, we can add other help file management features. What features do you need? Let us know!

To submit a feature request for PowerShell HelpWriter, post on our Wish List & Feature Requests Forum.

 June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Microsoft Cloud & DataCenter MVP. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

{SCOpenGraph image=http://info.sapien.com/images/2017/rebuild/image009.png}

• Prev