FAQ
From PowerGUI Wiki
Contents |
PowerGUI
Q. What is PowerGUI?
PowerGUI is an extensible graphical administrative console for managing systems based on Windows PowerShell. These include Windows OS (XP, 2003, Vista), Exchange 2007, Operations Manager 2007 and other new systems from Microsoft. The tool allows to use the rich capabilities of Windows PowerShell in a familiar and intuitive GUI console.
Q. How much does it cost and is registration required?
PowerGUI is a freeware product thanks to the support we are getting from Quest Software. You can download the product and access all information on this site absolutely for free and without any registration or login. You will have to register only if you want to post information to the discussion forums or library, or subscribe to notifications by email (RSS subscription does not require registration.)
Q. What are the system requirement?
The main system requirement is Windows PowerShell 1.0 or 2.0 (which in its turn requires .net framework 2.0). If you don't have this installed on your computer PowerGUI setup will detect that and open a web page from which the system can be downloaded. In terms of operating systems we support Windows XP, 2003, Vista, and Longhorn; both 32- and 64-bit. Particular snapins may add their specific system requirements. For example the Exchange 2007 snapin we ship today naturally requires Exchange 2007 or its administrative tools.
Q. What can I do with PowerGUI?
Pretty much anything that the underlying system permits. You can browse through the system, filter/sort what you get, select the columns, perform actions on selected objects, change their properties, export data to clipboard, Excel, xml, or just html reports, and much more. And if you don't believe this is all being done by Windows PowerShell just switch to another tab and you'll see the PowerShell code behind what you've been doing.
Check out PowerGUI extensions library for the additional features you can download from the community.
Q. Can I customize PowerGUI?
Yes, if the functionality of the PowerPacks that are available is not enough you can add your own nodes and actions to the PowerGUI Administrative Console. You can also remove existing nodes or actions, modify the scripts or parameters to meet your specific environment needs, change the position (check out our search feature when adding a cmdlet-based node!), actions, or links. You can of course delete any of the ones we ship too, and do basic customization such as changing the set and order of columns the tool displays.
See PowerGUI flash demos for more information.
Q. What are Links?
Links provide the ability to get to a set of related objects. For example, if I want to get a list of members of my Managers group, and then find Exchange mailbox stores which have their mailboxes I am effectively following links between the objects to get from the group to its members, then to their mailboxes, and finally to the mailbox stores.
See PowerGUI flash demos for more information.
Q. What a difference between Actions and Common Actions?
Actions are specific to an object class. For example, changing user properties only makes sense for user objects. Common Actions work for any object classes. Natural examples here would be reporting and export functions.
See PowerGUI flash demos for more information.
Q. How can I share my nodes and actions with others?
Anything you add can be shared with other PowerGUI users. To share functionality select the export command in the shortcut menu and then share the file by uploading it to the community library. Other users will then be able to download the file and import it into the tool.
Q. What does auto update do?
Every day the first time you start PowerGUI it tries to connect to the community site to check for latest version. No personal information is transferred during this connection or download. If a newer version is found you'll be prompted to download and install the version. If your computer is not connected to the internet you need to visit the community site to download and install the latest updates manually.
You can subscribe to our blog to get notified when a new version is available.
Q. Where can I get help?
Check out the flash demos posted on the site in the Documentation section, and feel free to ask questions on the community forums.
PowerGUI Administrative Console
Startup Options
Q. How do I launch the Admin Console in 32-bit mode on a 64-bit system?
When you first install PowerGUI, on the last page of the installation there is an option to open the Admin Console. This option will open the default version of the Admin Console. The default version is the 64-bit version on 64-bit machines, or the 32-bit version on 32-bit machines. In fact, on 32-bit machines there is only one version, the 32-bit version. Some PowerPacks use functionality that is only available in 32-bit mode, so you may want to open the Admin Console in that mode to use those PowerPacks. To do this, you have a few options:
1. In the start menu, open the Programs, then PowerGUI, then x86 folders and then click on the PowerGUI x86 shortcut to open the Admin Console in 32-bit mode.
2. In PowerShell, execute the following command: & ${env:ProgramFiles(x86)}\PowerGUI\AdminConsole_x86.exe
3. In cmd.exe, execute the following command: "%programfiles(x86)\PowerGUI\AdminConsole_x86.exe"
Note that you can only have one instance of the Admin Console open at a time, so if you already opened the Admin Console in 64-bit mode you will have to close that window before opening the Admin Console in 32-bit mode. Also note that you may need to wait a few seconds after closing the Admin Console window for the process to stop completely, at which point you can re-open it in 32-bit mode.
Q. What is STA mode and do I enable it?
STA stands for Single-Threaded Apartments. It is a mode that controls how COM-based applications function. Some PowerPacks, such as the FaceBook Organizer PowerPack, require STA-mode to be enabled in order for them to function properly. You can open either the 32-bit or the 64-bit version of the Admin Console in STA mode by running the corresponding executable from the command line with the -sta parameter.
To learn more about Single-Threaded Apartments, refer to the MSDN article available here.
Navigation
Q. What happened to the "Links" and "Actions" groups in the Action pane?
In earlier versions of PowerGUI, actions were broken down into three categories: Links, Actions, and Common Actions. All items in each of these categories were still actions, they just worked differently. Links would allow you to retrieve data related to what you were looking at, or to drill down on a data set. Actions would allow you to perform some action based on the data showing in the grid. Common actions would allow you to perform some action based on the data showing in the grid as well, however these actions would be available no matter what node or link you had clicked on.
In PowerGUI 1.9.0 and later, this has changed slightly. Now, everything in the actions pane are simply referred to as actions, and every action is assigned to a category. Some PowerPacks use the predefined Links, Actions and Common Actions categories, but others define and use their own categories. Over time some of these categories may go away as PowerPacks are reorganized. This starts to become more visible in the core PowerPacks that are included in PowerGUI 1.9.6.
When working with any action, the action name itself should identify whether it is retrieving related data to show in the grid, taking action on selected items in the grid, or doing something that doesn't even affect the grid, regardless of what category they belong to.
Modifying the grid view
Q. How do I select which columns should be displayed in the grid?
When viewing data in the result grid, you can modify the column selection, order and size to get the view that you need in your environment. All PowerPacks come with predefined views for each of the nodes, however this is easily modified through the PowerGUI user interface. For more details on how you can modify the column selection, order and size, see the "Configuring the results grid view" article.
PowerPacks
General Information
Q. What is a PowerPack?
A PowerPack is an add-on for the PowerGUI Platform. At this time, PowerPacks extend the PowerGUI Admin Console by defining one or more additional nodes and/or actions that will appear in the Admin Console interface. PowerPacks can be very simple, such as a PowerPack that provides one common action that allows users to do something like export the selected items in the grid and show them in a new Excel document, or very complex, such as the Hyper-V PowerPack that provides a rich management interface for a server platform. They can be designed to support a particular feature like the AD Recycle Bin PowerPack, or they can be a collection of useful automation scripts in an administrative UI, to facilitate executing various tasks in an automated fashion. Most importantly, they are a free-form user interface designed by people like you that allow others to automate their infrastructure and learn how to use PowerShell to do the automation.
You can learn a lot more about PowerPacks in the PowerPack section of the Administrative Console article in this Wiki.
Q. Where can I find additional PowerPacks?
PowerPacks may be stored on any website, however at this time most PowerPacks are stored in the PowerPack Library on the PowerGUI site.
Q. How do I add more PowerPacks to my Admin Console?
With the Admin Console open, select File | PowerPack Management. The PowerPack Management dialog allows you to add or remove PowerPacks from the Admin Console. It also allows you to export any PowerPacks you have created so that you can share them with others.
Q. How do I create a new PowerPack?
Right now creating a new PowerPack requires at least one node, even if the PowerPack will only contain actions. To create a new PowerPack, create a new node or select a node you already created that you want included in that PowerPack. Right click that node and select "Create New PowerPack...". This will open the New PowerPack dialog where you can select a name and provide a description for your PowerPack. You can also identify any prerequisite modules or snapins in this dialog. Once you have created the new PowerPack, if all you want in your PowerPack is an action you can remove the new node that you created since it will not be needed. By default, any child nodes you create under a node that is associated with a PowerPack will automatically be associated with the same PowerPack, and any actions you create for the nodes in the PowerPack will automatically be associated with the same PowerPack. You can add/remove individual nodes or actions to/from a PowerPack by opening their properties, clicking on the More button if the properties dialog is not expanded, and using the appropriate buttons to change the PowerPack(s) that the node or action is a member of.
General Information
Q. What is a node?
A node is an element that appears in the navigation tree in the PowerGUI Administrative Console. Nodes may or may not have a PowerShell command or script associated with them. Nodes with a PowerShell command associated with them are called basic nodes. Currently basic nodes may only be associated with commands that use the verb "Get". Nodes with a PowerShell script associated with them are called script nodes. If they have a PowerShell command or script associated with them, the appropriate PowerShell command or script is invoked when a user clicks on the node. Nodes may be static (meaning they are manually created by an end user through the UI) or dynamic (meaning that they are created by PowerShell commands that are part of a script associated with another node).
Q. What is an action?
An action is an element that appears in the action pane in the PowerGUI Administrative Console. Actions always have a PowerShell command or script associated with them, and that will be invoked when a user clicks on the action. Actions with a PowerShell command associated with them are called basic actions. Actions with a PowerShell script associated with them are called script actions. Actions may or may not require items to be selected in the grid, and while the associated PowerShell script is running they will either display results in a nested view (actions that do this used to be called Links), update the results in the current view, or leave the current view as is.
Q. What is the difference between actions and common actions?
Actions are associated with a specific object types. They will only appear in the action pane when the first object in the grid is of the same type. Common actions are simply actions that are not associated with any object type. Common actions appear regardless of the type of objects that appear in the grid.
Authoring
Q. How do I create a PowerGUI node?
If the command(s) you want to use come from a snapin or module, you need to make sure that snapin or module is loaded first by opening the File | PowerShell Libraries dialog. Check the module(s) or snapin(s) you need and then create your node that uses those snapins or modules.
To create a PowerGUI node, right click on the node that you want to be the parent of your node and select New | Node from the context menu (or New | Script Node if you know you'll be invoking something other than a Get- cmdlet in your node). Then either specify the parameter values (if it's a node) or enter your script (if it's a script node).
Once you have created your node, you can customize the grid that is shown by modifying the column selection, order and size. You can also add actions that you want associated with the data that your node retrieves.
Q. What defines the set of displayed columns and actions?
The set of columns displayed in the PowerGUI result grid is determined by the type of objects that are output to that grid. Objects may be output to the grid by nodes or actions. If you change the set of columns, rearrange the columns, or resize the columns, PowerGUI will retain those settings (the only exception to this is dynamic nodes, for which the settings are not currently retained). Column selection, order and size are associated with individual nodes and links, so if you have the same type of objects output from other nodes and links, you will have to configure the column selection, order and size there as well.
The set of actions that are shown in the Actions pane also depends on the type of the first object that is shown in the grid. Actions are associated with object types, and they will appear whenever an object of the corresponding type is the first object shown in the results grid. This allows you to get the same functionality for any type of object, regardless of where you see that object in the Admin Console.
Q. What are dynamic nodes?
Dynamic nodes are nodes generated dynamically by a PowerShell script that is invoked when a node is clicked. Dynamic nodes appear as child nodes of the node whose script was invoked. Unlike static nodes (those created manually through the Admin Console user interface), you cannot modify dynamic nodes directly so if you want to change them you must make the changes in the script that generated the particular dynamic node.
Q. How do I create dynamic nodes?
The easiest way to create dynamic nodes it to follow examples where they are already being created. The simplest example is the Event Log node in the Local System PowerPack that comes with PowerGUI. It contains script that uses global functions to create dynamic nodes. If you copy that example into your own PowerPack, you should also put the global functions you use into the shared script for that PowerPack so that consumers of your PowerPack don't have to be using the Local System PowerPack for yours to work properly.
Q. I have a really useful PowerShell script and I would like to use it to create a node or action. How can I do this?
When you want to create a node from an existing PowerShell script you should be able to simply copy your script into the new script node you create. Unless it calls on functions or commands or is dependent on variables that are not available in PowerGUI, it should simply run as is without modification. Actions may be a little trickier because they are invoked as a stage in a pipeline. If you want to create an action to work with the selected items, right-click in the action pane and select New Script Action. Then paste your script inside the script block that is already included in the action and modify it as necessary to work with $_ (the objects that are selected in the grid). If this is challenging for you then don't hesitate to post a question on the forums about it...it's really easy to do and many people would be happy to help you out.
Q. How can I share variables and functions between the nodes and actions in my PowerPack?
Every PowerPack can have one shared script associated with it. You can modify the shared script for a PowerPack by opening the properties page for any script node or script action that is a member of the PowerPack, and then selecting the Shared Scripts link that appears in the properties dialog. By default any function you create in your PowerPack will only be visible to nodes and actions in your PowerPack. If you find this limiting and would prefer for the functions to be visible outside of the PowerPack, make them global by prefixing their name with global:. In practice, it is much easier to maintain the script in a PowerPack when the functions it uses are global.
Managing Configuration
Q. Where is the Admin Console configuration information stored? How can I share it with other users?
The Admin Console configuration file (config.xml) is located in the "$([System.Environment]::GetFolderPath('Application Data'))\Quest Software\PowerGUI folder. If you want to share your Admin Console configuration with other users, you should replace the configuration file (config.xml) on the respective local computers.
Click here to learn more about PowerPacks.
Click here to learn more about the PowerGUI Administrative Console.
PowerGUI Script Editor
Startup Options
Q. How do I open the Script Editor in STA mode?
STA stands for Single-Threaded Apartments. It is a mode that controls how COM-based applications function. Some COM libraries, such as the one used in the FaceBook Organizer PowerPack, require STA-mode to be enabled in order for them to function properly. You can open either the 32-bit or the 64-bit version of the Script Editor in STA mode by doing the following:
1. Execute the following command in PowerShell: notepad "$([System.Environment]::GetFolderPath('ApplicationData'))\Quest Software\PowerGUI\ScriptEditor.xml"
2. Search for the text "STAMode".
3. On the line following the text "STAMode", replace False with True.
You can then disable STAMode later by setting the same value back to False.
To learn more about Single-Threaded Apartments, refer to the MSDN article available here.
Managing Configuration
Q. How do I customize the colors used in the Script Editor?
In the folder where PowerGUI was installed you will find a file called PowerShellSyntax.xml. This XML file contains a Styles element in which the colors used in the syntax highlighting are defined. To change the colors that are used, close the PowerGUI Script Editor, change the colors to ones you prefer, and then open the PowerGUI Script Editor again.
Q. Where is the Script Editor configuration information stored? How can I share it with other users?
The Script Editor configuration file (ScriptEditor.xml) is located in the "$([System.Environment]::GetFolderPath('Application Data'))\Quest Software\PowerGUI folder. If you want to share your Script Editor configuration with other users, you should replace the configuration file (ScriptEditor.xml) on the respective local computers.
