PowerPacks
From PowerGUI Wiki
Introduction
A PowerPack is an add-in for the PowerGUI platform. It is a document (.powerpack file) that defines extensions to one or more of the PowerGUI products. That definition, which is stored in XML format, is used by PowerGUI to determine what it should display in its extensible user interface, how it should be displayed, and how those user interface extensions should function within PowerGUI. At this time PowerPacks may contain any or all of the following:
1. Nodes that appear in the PowerGUI Administrative Console.
2. Actions that appear in the PowerGUI Administrative Console.
3. A shared script that defines functions used by the nodes and actions in the PowerPack.
PowerPacks may vary in complexity, from a simple PowerPack containing a single node or action to a complex PowerPack that provides dozens of nodes and actions coupled with a function library containing custom functions providing management support for a platform that may not come with PowerShell cmdlets. There is no minimum requirement for the number of nodes or actions that should be in a PowerPack other than that a PowerPack must contain at least one node or action.
Core PowerPacks
Out of the box, PowerGUI comes with four core PowerPacks:
These PowerPacks are not required to use PowerGUI, but they contain a lot of useful functionality for managing your network infrastructure. They also are great examples of what you will find in PowerPacks, using most of the latest features in the PowerGUI platform. When you install PowerGUI you can select which PowerPacks that you want installed with it. If you don't install one or more of the core PowerPacks with PowerGUI (maybe because you were missing a prerequisite snapin or module), you can install them later from within the PowerGUI Administrative Console.
Additional PowerPacks
You can also download additional PowerPacks from the PowerPack Library. This library contains many different categories with dozens of PowerPacks. Categories include Unified Communications, Active Directory, Windows Server, Virtualization, SharePoint, SQL Server, and many more. The additional PowerPacks provide a lot of very useful functionality, some of it designed to facilitate management of a particular platform (such as the Hyper-V PowerPack) and others designed to provide a useful set of features (such as the Org Chart PowerPack). The core PowerPacks are available in the PowerPack Library as well, however unless you are looking to install a fix for an issue you are facing between PowerGUI releases you don't really need to download and install those.
Each PowerPack in the PowerPack Library has a document page that describes what the PowerPack can be used for and that includes documentation that the PowerPack author wanted to share, such as requirements, a list of features, screenshots, screencasts, version history, and more. It is important to note that some PowerPacks require specific PowerShell modules or snapins, and you need to make sure that you have those requirements installed before you install the PowerPack you are interested in.
Managing PowerPacks
When working with PowerPacks, you need to know how to manage them. Management of PowerPacks includes installing prerequisite modules or snapins, downloading PowerPack files from the PowerPack Library, importing PowerPacks, customizing PowerPacks for your environment, upgrading PowerPacks you have installed, and removing PowerPacks. Each of these are described in more detail below.
Installing prerequisites
PowerPacks may be dependent on specific PowerShell modules or snapins for them to work properly. These modules or snapins must be installed on the local machine before you install the PowerPack. Most of the PowerPacks that require a specific module or snapin indicate where it comes from in the requirements section, so it is recommended that you download any files that are required and install them before installing a PowerPack. If they don't indicate where a required module or snapin is located, then most likely it is installed by enabling a feature on the local machine. If you're not sure where to find a prerequisite, you can ask the PowerPack author directly by posting your question on the appropriate PowerPack page.
Loading required modules and snapins
Once you have the modules and/or snapins you require installed on the local machine, you need to configure PowerGUI to load the appropriate modules and/or snapins by default. In the PowerGUI Administrative Console (or the PowerGUI Script Editor -- it functions the same way), all you need to do is the following:
1. Select File | PowerShell Libraries. This will open the modules/snapins management dialog.
2. Scroll down the list to find the modules or snapins that are required for the PowerPack you want to use.
3. Check the checkbox beside any modules or snapins that are required and click on OK to close the modules/snapins management dialog.
Satisfying other requirements
Some PowerPacks may have additional requirements that require special attention. Additional requirements may come in the form of additional files that need to be installed on the local machine, specific requirements for features that are not enabled by default (such as STA, or Single-Threaded Apartment, mode), or firm requirements for 32-bit PowerGUI even if you're on a 64-bit system. Be sure to review all requirements in the documentation for any PowerPack that you want to install and make sure that those requirements are met.
Opening 32-bit versions of PowerGUI
Aside from copying files to your local machine, some requirements can be met by controlling which version of PowerGUI you open and how you open it. On 64-bit systems, PowerGUI installs with both 32-bit and 64-bit versions of the Admin Console and the Script Editor. If you want to use a PowerPack that requires 32-bit support, you should open the 32-bit version of PowerGUI. This can be found in the x86 subfolder of your PowerGUI folder in the start menu.
Opening PowerGUI in STA Mode
Other PowerPacks may require that STA mode be enabled when you open PowerGUI. You can enable STA mode in the Admin Console by invoking the executable from PowerShell (or cmd.exe if you're more comfortable there) with the -sta switch. You can enable STA mode in the Script Editor by modifying the ScriptEditor.xml file that is stored in the "$([System.Environment]::GetFolderPath('ApplicationData'))\Quest Software\PowerGUI" folder.
Downloading PowerPack files from the PowerPack Library
Once you have met the PowerPack requirements, you can download the PowerPack file that you want from the PowerPack Library.
To download a PowerPack, do the following:
1. Open the PowerPack Library in your web browser (or go to PowerGUI.org and click on the PowerPacks tab at the top of the page.
2. Choose the subcategory you are interested in and locate the PowerPack you want to download, or search for the PowerPack using the search box.
3. Click on link for the PowerPack that you want to download to open the web document that describes the PowerPack.
4. If there is a Download button in the PowerPack, click on download button to download the PowerPack. Otherwise, find the Downloads area (in red on the right side) and click the link for the PowerPack file. You can see the two locations in the image below. This will show you the XML document that defines the PowerPack.
5. Select File | Save As and save the PowerPack on your local hard drive.
NOTE: make sure to save the powerpack using the .powerpack file extension. If you don't do this right away, you will have to change the extension to .powerpack before you can import the PowerPack into PowerGUI.
Importing PowerPacks into the Administrative Console
Once you have downloaded the PowerPacks you want to use in PowerGUI, you need to import them into PowerGUI before you can use them.
To import a PowerPack in the Admin Console, do the following:
1. Select File | PowerPack Management to open the PowerPack Management dialog.
2. Click on the Import... button.
3. Browse to the location of the PowerPack you downloaded and select it. Note that the required modules and snapins as well as a description of the PowerPack appear on the right-side of the dialog where you select the PowerPack file.
4. Double-click on the PowerPack file or click the Open button while the PowerPack file is selected to import the PowerPack into PowerGUI.
5. Click on the Close button in the PowerPack Management dialog to return to the Admin Console and start using the new PowerPack.
Upgrading PowerPacks
In addition to importing PowerPacks, you may have some PowerPacks that you want to upgrade. With PowerGUI 1.9.5 or later, PowerPack upgrades are automatically detected if you have internet access and you can easily upgrade them through the user interface. If you don't have internet access though, or if you are working with PowerPacks that don't have links to the online version of their files, you may need to manually upgrade. To upgrade a PowerPack, simply import the new version on top of the existing version of the PowerPack, as follows:
1. Select File | PowerPack Management to open the PowerPack Management dialog.
2. Click on the Import... button.
3. Browse to the location of the .powerpack file for the PowerPack you want to upgrade select it. Note that the required modules and snapins as well as a description of the PowerPack appear on the right-side of the dialog where you select the PowerPack file.
4. Double-click on the PowerPack file or click the Open button while the PowerPack file is selected to upgrade the PowerPack in PowerGUI.
5. Click on the Close button in the PowerPack Management dialog to return to the Admin Console and start using the upgraded PowerPack.
You can also force PowerGUI to check for an upgraded version of a PowerPack at any time, as follows:
1. Select File | PowerPack Management to open the PowerPack Management dialog.
2. Select the PowerPack that you want to upgrade.
3. Click on the Check for Update button. At this point, PowerGUI will check the online location of the PowerGUI file to see if a new version is available. If a new version is found, PowerGUI will ask you if you want to upgrade that version and then go through the upgrade process automatically if you accept the upgrade.
4. Click on the Close button in the PowerPack Management dialog to return to the Admin Console and start using the upgraded PowerPack.
Important PowerPack upgrade considerations
There are a few very important considerations that you should be aware of when upgrading PowerPacks.
1. During the upgrade process you may be asked if you want the nodes and actions in the PowerPack to appear where the PowerPack author intended to. This question will appear under two circumstances: if you manually modified the layout of the items in the PowerPack after installing/upgrading it last time, or if the author changes the layout of the PowerPack since the last update. It is recommended that you allow the PowerPack to install with the layout as designed by the PowerPack author, and then customize your layout if necessary afterwards. That allows you to see the user experience of the PowerPack as designed by the author.
2. If you have customized a PowerPack for your environment, you should make a backup of your customizations before you upgrade the PowerPack. Some customizations may be overwritten during the upgrade process depending on what changes the author made to the PowerPack, so having a backup on hand is essential to preserve your changes. To backup any customizations you have made, either export your version of the PowerPack to a .powerpack file using the Export button in the PowerPack Management dialog (this approach is strongly recommended) or make a copy of the config.xml file and the Scripts folder (this folder contains any shared scripts for the PowerPacks) located in the "$([System.Environment]::GetFolderPath('ApplicationData'))\Quest Software\PowerGUI" folder (this will backup your PowerGUI Administrative Console, and therefore all PowerPacks, at the point in time that you backup the files).
Rolling back an upgrade
After upgrading a PowerPack, you may decide that you want to roll back the upgrade to the previous version. This can happen for a few different reasons (defects were introduced by the PowerPack author, you had some customizations that you prefer to continue to use, etc). In order to be able to roll back a PowerPack upgrade, you must have a backup to roll back to (see the comments in the section above, titled "Import PowerPack upgrade considerations"). How you revert to the previous version depends on how you backed up your PowerPack beforehand. If you exported the PowerPack file, then you can simply remove the PowerPack you want to roll back and then import your backed up version of the PowerPack using the PowerPack Management dialog. If you backed up your config.xml and Scripts folder, you need to do a little more work to revert to the previous configuration, as follows:
1. Close the PowerGUI Administrative Console.
2. Navigate to the "$([System.Environment]::GetFolderPath('ApplicationData'))\Quest Software\PowerGUI" folder.
3. Rename your current configuration file (config.xml). For example, change config.xml to config.xml.temp.
4. Rename your current Scripts folder. For example, change Scripts to Scripts.temp.
5. Copy your backed up configuration file (config.xml) and Scripts folder into the current folder.
6. Open the PowerGUI Administrative Console and your previous version should be restored.
7. At this point if you are satisfied with the restore you can delete the temporary files created in steps 3 and 4.
Modifying the PowerGUI Administrative Console functionality for your environment
All of the content in PowerPacks that you install in your environment is completely customizable. The PowerShell commands and scripts that drive the functionality inside the PowerPack are open source, so you can modify PowerPacks you use however you like for your environment. The layout and configuration of PowerPack nodes and actions can be changed, and you can add new functionality on your own that does not belong to any PowerPack. Also, there are features in place to allow you to lock down the PowerGUI console and prevent users from being able to modify the PowerPacks, allowing you to build out customized consoles for junior administrators or help desk staff without worrying about them modifying the contents of the console and introducing problems.
One of the most common modifications you can make to PowerPacks can very easily be used as the foundation for brand new PowerPacks that you can share with the community as well. The modification I'm referring to is the addition of actions for objects already returned by PowerPacks you have installed. Many times when users download a PowerPack and start using it, they come across some functionality (typically an action) that they would like to see, and they find out how to create that action themselves. This type of modification, and others, are described in more detail below.
Changing the layout
Changing the layout of the nodes in the navigation tree or the actions in the action pane is the easiest modification you can make to a PowerPack. Layout changes are performed through basic drag and drop operations.
Modifying node layout
To change the layout of one or more nodes in the tree, simply drag the node you want to move to the container node where you want it stored. If you want to keep it in the current container but you want to change the order, drag the child nodes into the same parent in the order in which you want them to appear (each time you drag a node onto another node, that node is added to the bottom so moving them all in the order in which you want them to appear will create that layout).
Modifying action layout
To change the layout of one or more actions in the actions pane, simply drag the action you want to move to the location where you want it to appear. If you want to keep the action in the same category, drag it within the same category while pointing at the space between the two actions where you want it stored (or before the first action or after the last action if you want it to appear at the top or bottom of the list).
Changing the category for an action
If you want to move an action to a different category, either drag it to the new location in the new category if the category is visible (as described above) or, if the category you want either isn't visible in the actions pane or doesn't exist yet, do the following:
1. Right-click on the action and select Properties to view the properties for the action.
2. Click on the Display Configuration button to view the display configuration for the action.
3. In the Category section of the Action: Display Configuration Properties dialog, select the category you want to move the action to from the sorted list of categories or, if it does not exist yet, click on the Use Custom button and type in the category name you want to create the new category.
Changing the functionality
There are circumstances where the canned functionality included with a PowerPack may not be enough to run in your environment. Network environments have infinite configurations and some PowerPack authors may not support all configurations out of the box. Fortunately, since the PowerShell commands and scripts are open source, you can customize them to work in your environment. Note that if you are changing any PowerPack functionality, you should make sure you back up your PowerPack before you upgrade it so that you preserve any customizations you have made. To learn more about this, see the section entitled " Important PowerPack upgrade considerations".
Adding parameter values to a basic node or action
Basic nodes and actions are simply nodes and actions that are directly associated with one PowerShell command. Instead of showing a script that contains only one command, basic nodes and actions show the command they are associated with as well as the parameters for that command (and any values for those parameters that were defined by the PowerPack author). To view and modify the parameters used in a basic node or action, do the following:
1. Right-click on the node or action for which you want to modify the parameters and select Properties.
2. In the Properties dialog, use the parameter grid to assign values to the parameters that you want changed. In the screenshot below I'm showing how I could modify a basic a Background Jobs node to retrieve only failed jobs. Note that I could also check the Prompt field if I wanted to be prompted for which type of background jobs I wanted to retrieve.
3. Click on the OK button to save your changes and close the Properties dialog.
Modifying the script in a script node or action
Script nodes and actions are nodes and actions that are associated with a PowerShell script. The PowerShell script in script nodes and actions range from the very simple, using a short pipeline or a few simple commands, to the very complicated, using a long PowerShell script to do the heavy lifting. There really is no limit in terms of what you might want to do when modifying a script node or script action. To modify a script node or script action, do the following:
1. Right-click on the node or action for which you want to modify the script and select Properties.
2. In the Properties dialog, use the embedded script editor to modify the script as required for your environment.
3. Click on the OK button to shave your changes and close the Properties dialog.
Adding new functionality
In addition to being able to modify existing functionality in PowerPacks, you can also add new functionality. The most common modification users make to PowerPacks is the addition of new functionality. When something is missing in a PowerPack, you can request it on the PowerGUI Forums. This practice is highly recommended because most of the functionality in PowerGUI and the PowerPacks are added because users requested them. In addition to requesting it on the PowerGUI Forums, you can also add the functionality yourself and then later share it as part of your own PowerPack. The following sections will define how you go about adding functionality to PowerGUI.
Creating a folder
To create a new folder in the Admin Console, do the following:
1. In the navigation tree, right-click on the node under which you want to create a new folder. If this folder is the starting point for a brand new PowerPack, it is recommended that you create it by right-clicking on the root PowerGUI node.
2. Select New | Folder in the context menu that appears.
3. In the New Node dialog (a folder is just a node without any association to a PowerShell command or script), enter the name for your new folder and optionally provide a description and a custom icon.
4. Click on the OK button to create the folder and close the dialog.
Creating a new node
To create a new node in the Admin Console, do the following:
1. In the navigation tree, right-click on the node under which you want to create a new node. If this node is the starting point for a brand new PowerPack, it is recommended that you create it by right-clicking on the root PowerGUI node.
2. Select New | Node to create a basic node (a basic node is one that is associated with a single PowerShell command) or New | Script Node to create a script node (a script node is one that is associated with a PowerShell script).
3. In the New Node dialog, enter the name for your new node and optionally provide a description and a custom icon. If you are creating a basic node, select the command to associate to your node from the list in Commands. If you are creating a script node, enter the script for your node in the embedded script editor. You can also modify the PowerPack to which the node will be assigned. If the node you create is a child node of a node that belongs to one or more PowerPacks, that node will automatically be assigned to the same set of PowerPacks, but you can modify this as required as well.
4. Click on the OK button to create the node and close the dialog.
Creating a new category
To create a new category in the Admin Console, do the following:
1. In the action pane, right-click on one of the categories (or anywhere in the action pane if there are no categories) and select New | Category.
2. In the New Category dialog, enter the name for your new category.
3. Click on the OK button to create the category and close the dialog.
Creating a new action
To create a new action in the Admin Console, do the following:
1. In the action pane, right-click on the category under which you want to create a new action.
2. Select New | Action to create a basic action (a basic action is one that is associated with a single PowerShell command) or New | Script Action to create a script action (a script action is one that is associated with a PowerShell script).
3. In the New Action dialog, enter the name for your new action and optionally provide a description and a custom icon. If you are creating a basic action, select the command to associate to your action from the list in Commands. If you are creating a script action, enter the script for your action in the embedded script editor. You can also modify the PowerPack to which the action will be assigned. If the action you create is from the results of a node or action that belongs to one or more PowerPacks, that action will automatically be assigned to the same set of PowerPacks, but you can modify this as required as well.
4. Click on Display Configuration to define the behaviour that determines when the action will be displayed as well as how the action will show results. If you have been using PowerGUI for a while and are wondering how to create a link, you create an action and configure its display results as "Display the results in a nested view".
5. Click on the OK button to create the action and close the dialog.
Removing functionality
Removing a node
To remove a node from the PowerGUI Administrative Console, simply right-click on the node you want to remove and select Delete. You will be prompted to verify you want to delete the node you selected.
WARNING: If you delete a node, all child nodes will be deleted with that node so make sure to move any child nodes you want to keep around first.
Removing an action
Just like removing a node, you can remove any action by right-clicking on the action and selecting Delete from the context menu that appears. You will be prompted to verify you want to delete the action you selected.
Removing a category
At this time, there is no support for removing a category through the user interface. If you create categories that you no longer need, removal of those requires manual modification of the config.xml or .powerpack files. It is recommended that you contact the PowerGUI team through the Forums if you want to remove categories.
Removing PowerPacks from the Admin Console
Occasionally you might want to remove a PowerPack from the PowerGUI Administrative Console. For example, if you just imported a PowerPack to see what it offers, you might decide you're not interested in it and want to remove it right away.
To remove a PowerPack from the Admin Console, do the following:
1. Select File | PowerPack Management to open the PowerPack Management dialog.
2. Select the PowerPack you want to remove from the list of PowerPacks that are installed.
3. Click on the Remove... button. This will prompt you to verify that you want to remove the PowerPack. Click Yes in the verification dialog to remove the PowerPack from your system. Note that any unexported PowerPack changes will be lost if you do this.
4. Click on the Close button to close the PowerPack Management dialog and return to the Admin Console.
WARNING: If you have nodes in your navigation tree that are child nodes of the PowerPack you are removing and that do not belong to the PowerPack you are removing, the PowerGUI Administrative Console will ask you if you want those nodes automatically moved to the root of the navigation tree. If you don't have those nodes moved to the root of the navigation tree, they will be removed from the Admin Console along with the PowerPack.
Creating a PowerPack
The PowerGUI platform allows you to easily share your automation and management scripts with other users in the PowerPack Library. As mentioned earlier, a PowerPack is a document that defines a user interface extension to PowerGUI. At this time, user interface extensions are only possible in the PowerGUI Administrative Console. They range from the very small, containing only one node or action, to the very large, containing dozens upon dozens of nodes and actions and functions in a shared script library.
This section will walk you through the PowerPack creation process from start to finish so that you can create your own PowerPacks. If you prefer to watch a demo than to read the documentation, jump down to the PowerPacks#Tutorial: Create a PowerPack from start to finish in 10 minutes
Brainstorming the initial PowerPack idea
The first step in the PowerPack creation process is to come up with the initial idea. Most of the time, this comes from a business need to do something via script. For the Org Chart PowerPack, the initial idea was to have a script that gave me a generated org chart as defined by the information in Active Directory. Other PowerPacks, such as the Advanced (HTML) Reporting PowerPack, the initial idea was simply that I wanted to generate rich HTML reports in a generic manner for any set of data in PowerGUI.
For your first PowerPack the best approach is to start small and then grow it based on your needs and feedback from users that use your PowerPack. Small really means small in this case. If you have used the Admin Console and added even one action to it that you felt was missing or that you find useful, that's all you need to create a PowerPack and share it with others. Or if you have any scripts in your own environment that are useful enough to share, pick one of those scripts and think about exposing that functionality in a node on its own. Once you have that idea you're ready to go on with the creation of the PowerPack.
Creating the PowerPack entity within PowerGUI
Once you have the general PowerPack idea in mind, you're ready to start creating your PowerPack. It's a good idea to create the PowerPack within PowerGUI regardless of what it will contain. To do this, there are a few simple steps you should follow:
1. Right-click on the root PowerGUI node and select New | Folder. Even if you don't want a folder, follow these steps just to set the PowerPack up in PowerGUI.
2. In the New Folder dialog, enter any text for your new folder name. If you want to keep this folder and include it in your PowerPack, choose a meaningful name for the root of the PowerPack. Otherwise, if you don't need a folder in your PowerPack, call the New Folder "temp".
3. Once you have provided a name for the folder, click in OK to create it.
4. At this point you should see the new folder you just created in the navigation tree. Right-click on that folder and select Create New PowerPack... from the context menu that appears.
5. In the New PowerPack dialog, provide a meaningful name for your PowerPack and optionally a description and a custom icon. If your new PowerPack requires any modules or snapins, make sure they are checked in the Requirements list; otherwise, clear all the checked items in that list. The other fields will be assigned later.
6. Click on OK to create the PowerPack and close the dialog. At this point you have just created a new PowerPack with the folder you created in step 1 included in it.
7. If you only want an action in your PowerPack or if you simply don't want the folder you created in step 1 included in your new PowerPack, right-click on that folder and select Delete. This will delete the folder, not the PowerPack.
Adding functionality to your PowerPack
At this point, you should have a PowerPack that you can export and share with the community, although the most it will contain is one folder (if you actually wanted to keep that folder). Now you need to start adding the actual functionality to your PowerPack. Adding functionality to a PowerPack is almost
Adding a folder to your PowerPack
To add a new folder to your PowerPack, do the following:
1. In the navigation tree, right-click on the node under which you want to create a new folder.
2. Select New | Folder in the context menu that appears.
3. In the New Node dialog (a folder is just a node without any association to a PowerShell command or script), enter the name for your new folder and optionally provide a description and a custom icon.
4. Click on the More >> button to view the PowerPacks to which the folder is assigned. Use the Add... button to add it to your new PowerPack if necessary.
5. Click on the OK button to create the folder and close the dialog.
Adding a node to your PowerPack
If you want to add a node to your PowerPack, you need to do the following:
1. In the navigation tree, right-click on the node or folder under which you want to create a new node.
2. Select New | Node to create a basic node (a basic node is one that is associated with a single PowerShell command) or New | Script Node to create a script node (a script node is one that is associated with a PowerShell script).
3. In the New Node dialog, enter the name for your new node and optionally provide a description and a custom icon. If you are creating a basic node, select the command to associate to your node from the list in Commands. If you are creating a script node, enter the script for your node in the embedded script editor.
4. Click on the More >> button to view the list of PowerPacks and to which this node is assigned. Use the Add button to add the node to your new PowerPack.
5. Click on the OK button to create the node and close the dialog.
Adding a category to your PowerPack
To add a new category to your PowerPack, you need to do the following:
1. In the action pane, right-click on one of the categories (or anywhere in the action pane if there are no categories) and select New | Category.
2. In the New Category dialog, enter the name for your new category.
3. Click on the OK button to create the category and close the dialog. This category will now be included in your PowerPack.
Adding an action to your PowerPack
If you want to add an action to your PowerPack, you need to do the following:
1. In the action pane, right-click on the category under which you want to create a new action.
2. Select New | Action to create a basic action (a basic action is one that is associated with a single PowerShell command) or New | Script Action to create a script action (a script action is one that is associated with a PowerShell script).
3. In the New Action dialog, enter the name for your new action and optionally provide a description and a custom icon. If you are creating a basic action, select the command to associate to your action from the list in Commands. If you are creating a script action, enter the script for your action in the embedded script editor.
4. Click on the More >> button to view the list of PowerPacks and to which this action is assigned. Use the Add button to add the action to your new PowerPack.
5. Click on Display Configuration to define the behaviour that determines when the action will be displayed as well as how the action will show results. If you have been using PowerGUI for a while and are wondering how to create a link, you create an action and configure its display results as "Display the results in a nested view".
6. Click on the OK button to create the action and close the dialog.
Modifying your shared PowerPack script
As you add more and more to your PowerPack you may hit a point where you want to share common functionality between nodes and actions. Shared scripts have been created for this purpose, allowing you to store functions and variables in one location that you use in various nodes and actions in your PowerPack. A shared script for a PowerPack is executed the first time that a user clicks on a node or action belonging to a PowerPack.
To view and/or modify the shared script for your PowerPack, do the following:
1. Right-click on any script node or script action and select Properties.
2. Once you have the Properties dialog open, click on the Shared Scripts button and select your PowerPack from the list of PowerPacks that appears to open the shared script in the standalone PowerGUI Script Editor.
3. Make any modifications you want to your shared script and select File | Save to save the changes.
4. Close the PowerGUI Script Editor when you have finished modifying your shared script file and return to the PowerGUI Admin Console to continue working on your PowerPack.
There are a few important things to consider when working with shared scripts:
1. All functions and variables you define in a PowerPack are visible only to that PowerPack unless you use the global: scope specifier prefix on your function and variable declarations.
2. When you modify a shared script, clicking on any node or action in the appropriate PowerPack will cause the Admin Console to dot-source the shared script.
Working with Dynamic Nodes
Script nodes can do a lot more than just return objects that are displayed in the results grid. The PowerGUI Administrative Console includes support for dynamically creating script nodes from other script nodes. This allows you to do things such as create one node that lets you walk through a file system or registry that is dynamically created in the navigation tree, or create a node that shows you all of the event logs in the navigation tree and shows you the content of the event logs when you click on one of the dynamically generated nodes. You can see examples of dynamically generated nodes in all four of the core PowerPacks, as well as the Org Chart PowerPack, the Hyper-V PowerPack, and the VMware PowerPack, among others.
Creating dynamic nodes can be a little complicated, but to make things easier if your PowerPack is designed to work in PowerShell versions 1 and 2 you can copy the region labelled "Admin Console functions" the shared script in any of the PowerPacks mentioned earlier. It contains a function called Add-AdminConsoleDynamicScriptNode that masks a lot of the complexity involved in the creating of dynamic script nodes. If your PowerPack only needs PowerShell version 2 support though, using dynamic nodes is even easier. For PowerPacks based on PowerShell 2.0 you can download and install the AdminConsole module, which contains a collection of advanced functions to facilitate things like creating dynamic nodes. If you want to see what your PowerPack might look like with a PowerShell 2.0 requirement and dynamic node support, take a look at the "Create a PowerPack in 10 minutes" screencast that shows just how easy dynamic nodes are when you use PowerShell 2.0 and the AdminConsole module.
Exporting your PowerPack
Once you have finished adding your functionality to your PowerPack, you can export it and share it with the community.
To export your PowerPack, do the following:
1. Select File | PowerPack Management to open the PowerPack Management dialog.
2. In the PowerPack Management dialog, select the PowerPack you want to export and click on the Edit... button. This will display the PowerPack Properties dialog.
3. Using the fields and buttons in the PowerPack Properties dialog to specify the name, version (note: this is auto-incremented when you export the PowerPack), description, requirements, and icon for your PowerPack.
4. If required, click the Advanced button to select the specific nodes or actions to include in the PowerPack.
5. Once you have configured your PowerPack the way you want, click on the OK button to save the properties for your PowerPack. This will return you to the PowerPack Management dialog.
6. Click on the Export... button in the PowerPack Management dialog to export the PowerPack.
7. In the dialog that appears, modify the path and version as desired and click on the Export button to create the PowerPack file.
Posting your PowerPack in the PowerPack Library
If you've made it this far, congratulations, you've created your first PowerPack that can be shared with the community. You can post your PowerPack on internal file shares or SharePoint sites, but if you really want to contribute you should share it with the PowerGUI community by posting it in the PowerPack Library.
To post a PowerPack in the PowerPack Library, do the following:
1. Open your web browser and navigate to http://powergui.org.
2. Click on the PowerPacks header at the top of the page to go to the PowerPack Library.
3. Log in to the PowerGUI site (you must be logged in to post any content).
4. On the far right side, click on the Add Document hyperlink to add a new document.
- Go to the PowerGUI.org site, and upload the PowerPack to the library.
5. Provide a title, description (body) and summary for your new PowerPack and select PowerPack for the document type.
6. Click on the Attach Files button to upload your PowerPack and use the Browse button beside the Attachment #1 field to upload your PowerPack file. Upload any additional required files in attachments 2 through 6. When you have finished uploading your PowerPack files, click on the Back to Document button.
7. Click on the Preview button to preview the document or Post Document to post the PowerPack.
Once you have completed all of those steps, users will be able to discover and download your PowerPack.
Adding your PowerPack to multiple categories
When you create a PowerPack document in the PowerPack Library, it will only be visible in the category in which you created it. It is a good idea to create PowerPacks in the top category (the root of the PowerPack Library), and then to add them to other relevant categories.
To add a PowerPack to additional categories, do the following:
1. Open the document containing your PowerPack details.
2. Click on Manage Document in the list of options on the far right side of the window.
3. Click on Manage Categories at the top of the window above the PowerPack.
4. In the Categories tree, expand PowerGUI Library and click on each of the categories you want to add your PowerPack to.
5. Click on Back to Document to return to the PowerPack document. At this point the PowerPack should be visible in each of the categories you selected.
Enabling auto-update for your PowerPack
There is one other modification you need to make before you can truly consider your PowerPack a finished product. PowerPacks support auto-updating in PowerGUI as long as the PowerPack has a property set on it indicating where the .powerpack file can be found and where the PowerPack details page can be found. These pieces of information can only be set after you have published your PowerPack in the PowerPack Library.
To enable auto-update for your PowerPack, you must do the following:
1. In the PowerGUI Administrative Console, select File | PowerPack Management to open the PowerPack Management dialog.
2. Select the PowerPack for which you want to enable auto-update and click on the Edit button.
3. In the PowerPack Properties dialog, set the PowerPack File Link to the location of your .powerpack file. This could be the address on a SharePoint site, a UNC path to a file share, or the URL to download the .powerpack file on the PowerPack Library.
4. Also in the PowerPack Properties dialog, set the Home Page value to the web address for the PowerPack document you created in the PowerPack Library.
5. Click on OK to save the changes.
6. Export the PowerPack again as described in the Export steps, above.
7. Open your web browser and browse to your PowerPack document in the PowerPack Library.
8. Click on Edit in the Downloads header on the right side of the window to modify the PowerPack file.
9. Click on the icon under the Update column and provide the required information in the window that appears to update the PowerPack with a new version.
At this point your PowerPack should be configured to automatically update when a new version has been posted.
Tutorial: Create a PowerPack from start to finish in 10 minutes
Now that you've read through how you can create a PowerPack from scratch (or even if you haven't), you should take a little time read a blog post that comes with a screencast video demonstrating not only how you can create a PowerPack, but how you can do so from start to finish including posting it to the PowerPack Library in 10 minutes time, complete with dynamic nodes, a shared script library, script nodes and regular nodes and actions. You can find that blog post here: "PowerGUI Quick Tip: Create a PowerPack from start to finish in 10 minutes".
PowerPack FAQ
Click here to see the list of frequently asked questions about PowerPacks.
