Академический Документы
Профессиональный Документы
Культура Документы
5
User Guide
TRADEMARKS
Quest, Quest Software, the Quest Software logo, Simplicity at Work are trademarks and registered trademarks of Quest Software, Inc. For a complete list of Quest Software's trademarks, please see http://www.quest.com/legal/trademark-information.aspx. Other trademarks and registered trademarks are property of their respective owners.
DISCLAIMER
The information in this document is provided in connection with Quest products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Quest does not make any commitment to update the information contained in this document.
Contents
About This Guide..................................................................................................... 5
Overview ............................................................................................................................ 5 Conventions ............................................................................................................... 5
Passing Script Parameters .............................................................................................. 33 Viewing Definition of Functions ....................................................................................... 34 Compiling Scripts ............................................................................................................. 34 Executable File from Script ...................................................................................... 34 Windows Service from Script ................................................................................... 35 Executing Scripts Remotely............................................................................................. 37 Working with Version Control .......................................................................................... 38 Integrating TortoiseSVNSCC with PowerGUI Script Editor .................................... 39 Customizing the PowerGUI Script Editor ........................................................................ 40 Creating a PowerGUI Script Editor Add-On ............................................................ 40 Searching for PowerGUI Script Editor Add-Ons Online .......................................... 41 Running PowerGUI Script Editor in Multithreaded Apartments Mode ............................ 42
Conventions
In order to help you get the most out of this guide, we have used specific formatting conventions. These conventions apply to procedures, icons, keystrokes and crossreferences.
ELEMENT CONVENTION
This word refers to actions such as choosing or highlighting various interface elements, such as files and radio buttons. Interface elements that appear in Quest products, such as menus and commands. Used for comments. Introduces a series of procedures. Indicates a cross-reference. When viewed in Adobe Acrobat, this format can be used as a hyperlink. Used to highlight additional information pertinent to the process being described. Used to provide Best Practice information. A best practice details the recommended course of action for the best result. Used to highlight processes that should be performed with care.
+ |
A plus sign between two keystrokes means that you must press them at the same time. A pipe sign between elements means that you must select the elements in that particular sequence.
Introduction
PowerGUI is a comprehensive solution helping you get the most of Windows PowerShell. The product has two components: Administrative Console Script Editor and debugger
The PowerGUI Administrative Console is designed to: Streamline PowerShell-based administration tasks by providing ready-made tools through a unified interface Make the extensive capabilities of PowerShell accessible to users who are not comfortable with the text console environment Help establish administration tiers by making specific tools available to specific groups of users, such as Active Directory administrators, help desk staff, and end users
The PowerGUI Script Editor is a complete PowerShell IDE with advanced code editing, debugging and customization capabilities, and a built-in PowerShell prompt.
PowerGUI Setup
System Requirements
HARDWARE
CPU: 1GHz 32-bit or 64-bit Memory: 1GB Disk space: about 70MB for the setup and extra disk space for user profiles and PowerPacks that are not included in the setup
OPERATING SYSTEM
One of the following: Windows Vista Service Pack 1 Windows 7 Windows Server 2008 Windows Server 2008 R2 Windows XP Professional Service Pack 3 Windows Server 2003 Service Pack 2 Windows Server 2003 R2 Service Pack 2
For successful installation, the Windows Management Instrumentation service must be running on the target system.
ADDITIONAL SOFTWARE
All of the following: Microsoft .NET Framework 3.5 Service Pack 1 or Microsoft .NET Framework 4.0 (Full) Microsoft PowerShell 2.0 or Microsoft PowerShell 3.0 Community Technology Preview (CTP) Any software for which you are installing additional PowerPacks. For example, Exchange 2007 Management Shell must be installed if you select the Exchange 2007 PowerPack, and so on. If you are going to use VMware vSphere Client integration, VMware vSphere Client 4.0 version or later and VMware vSphere PowerCLI 4.1 version or later are required. If you are going to use source control in the PowerGUI Script Editor, a source control client that supports the MSSCCI provider is required. The following version control systems have been verified to work with the PowerGUI Script Editor: Microsoft Visual SourceSafe Microsoft Team Foundation Server Other version control systems should work if their providers fully support MSSCCI (for example, Subversion with the TortoiseSVNSCC provider), but they have not been tested with the PowerGUI Script Editor.
Installing PowerGUI
To start the installation, run the PowerGUI.3.5.x.x.msi installation package provided. On the Select Features step, specify the following: The PowerPacks and other components that you want to install
Setup tries to detect the software that is already installed, and suggests a selection of features based on this information. The Local System, Export Actions, Network and HTML Reporting PowerPacks are available for any configuration. The installation folder
Once you have configured these options, complete the installation wizard.
Silent Installation
To install PowerGUI in silent mode (without user interaction), from the command line, run the following command:
msiexec /quiet /i <Installation package location>\PowerGUI.3.5.x.x.msi PF_POWERGUI=<Installation folder> To specify whether PowerGUI can automatically collect anonymous product usage data, set the USAGE_INFO_COLLECTING_OPTIONS property to Collect (default value) or DontCollect, respectively.
g)
For example, running the following command from the command line installs PowerGUI Administrative Console, PowerGUI Script Editor and Local System PowerPack:
msiexec /quiet /i <Installation package location>\PowerGUI.3.5.x.x.msi ADDLOCAL=PowerGUI,ScriptEditor,PowerPack_LocalSystem PF_POWERGUI=<Installation folder>
2. 3.
4.
5.
The script starts the PowerGUI installation, or if it has not found any USB flash drives connected to your computer, the script prompts you for a folder where to install PowerGUI. After installation, you can safely remove your USB flash drive.
To use PowerGUI installed on the USB flash drive: 6. Insert the USB flash drive into a USB port on a computer with PowerShell 2.0 and .NET Framework version 3.5 installed.
10
7. 8.
Navigate to a folder on the USB flash drive where PowerGUI is installed. Launch PowerGUI Administrative Console or PowerGUI Script Editor by running PowerGUI AdminConsole.exe or PowerGUI ScriptEditor.exe respectively.
By default, the 64-bit version of PowerGUI is launched on 64-bit versions of Microsoft Windows. To launch the 32-bit version of PowerGUI, run PowerGUI AdminConsole_x86.exe or PowerGUI ScriptEditor_x86.exe.
11
12
PowerShell Scripts The additional PowerShell Script tab in the output pane allows you to view the underlying PowerShell code at any time. If required, you can copy the displayed code and reuse it on the command line or in your scripts. Messages This optional dockable window lets you view errors that occurred during script execution, or information about PowerPack installations and upgrades. Where possible, links to the underlying PowerShell code are provided.
Creating Nodes
You can create basic nodes and script nodes. To create a basic node 1. 2. 3. Right-click the node under which you want to create a new node, and select New | Node. Select the required cmdlet from the Command drop-down list or search for it. Optionally, specify cmdlet parameters, and select the parameters you want to be prompted for. The list of cmdlets available to you is defined by the set of libraries installed on your computer (to list them, select File | PowerShell Libraries in the main menu).
13
To create a script node 1. 2. Right-click the node under which you want to create a new node and select New | Script Node. Leave the Custom script option selected in the Command drop-down list and type or paste your script in the field below.
The type of node can be selected not only during node creation, but also at any time for any existing node. For that, use the Command drop-down list in the node's properties dialog box.
Before you edit the contents of an existing node, consider turning off filters in the output pane, especially if your changes can affect the type of the returned data.
You can load a team SharePoint site or intranet Web page, or create any other custom page for specific PowerPack users.
14
To customize the Details tab 1. 2. 3. Click Customize at the top of the details toolbar. In the dialog box that opens, select the previously created Web page. Click Open, and your custom HTML page will be displayed.
If there are problems with graphics loading, try using a Web archive file (*.mht).
All Web links on the HTML page will be valid if the PowerGUI client is connected to the Internet.
15
To make jumping to node in the navigation tree or executing action available by one click you can insert to your custom page hyperlink to node or to action you want. Examples: Creating hyperlink to node a) Using node address
This hyperlink jumps to node in the navigation tree with the specified node address. b) Using node GUID (Globally Unique Identifier)
<a href="powergui://navigation/{a2475c22-a617-44c5-8287373941e2ae38}">Jump to node</a>
This hyperlink jumps to node in the navigation tree with the specified node GUID. Creating hyperlink to action
<a href="powergui://action/{3780b4ca-12e9-4151-b3c36004dca70c75}">Execute action</a>
This hyperlink executes action with the specified action GUID (Globally Unique Identifier)
Currently the only way to get action or node GUID is to open PowerPack file and find the GUID (the same as container id tag value) you want.
16
You can also clear all filter settings or save the filter configuration as a new script node.
When you select Save As, the filter is saved under the selected node as a child node.
18
Here is an example of creating a preset for local system disk drives node: 1. 2. 3. 4. 5. 6. 7. 8. Select the Local System | Drives | File system node in the navigation tree. Click the Create New Preset button (icon representing a blank sheet of paper) at the top of the chart toolbar. Type your chart name(e.g., DiskCapacity). Select your chart type (e.g., Stacked column). Select the Show all properties check box. In the list of check boxes that appears, select the Used and Free check boxes. Click the Appearance tab and change the Legend Visible value to true. Click OK, and your chart, similar to the chart above, will be displayed.
To customize a previously created chart preset 1. 2. 3. 4. Select the preset to customize from the Preset drop-down list. Click Customize to open the Customize Preset dialog box. Perform the necessary customization. Click OK to apply the changes.
You can define custom colors for chart elements in addition to predefined colors. To do it, perform the following: 1. Select setting that defines color of the chart element you want to change. 2. Expand color selection dialog of the selected setting. 3. On the Custom tab, right-click one of the empty white boxes to open the Define Color dialog box. 4. Select desired custom color for the chart element and click Add Color.
To delete a chart preset 1. 2. Select the preset to delete in the Preset drop-down list. Click the Delete Preset button (red cross icon) at the top of the chart toolbar.
19
Using Actions
The actions available for objects displayed on the Results tab are listed in the Actions pane of the PowerGUI Administrative Console. An action is basically some wrapped PowerShell code: a cmdlet or a script. PowerPacks in PowerGUI provide different action categories, which are essentially labels that help organize actions. The following are examples of action categories (marked bold) from some predefined PowerPacks: Related Information actions provide connections from the currently selected objects to their related objects (for example, users for selected mailboxes, or permissions for selected files). In general, actions from this category do not affect objects; they allow you to gather more information and explore the system. General actions are procedures applied to the selected objects in the table. Common actions are available for all object types, while actions from other categories are executed by default for the specific types of objects.
In addition to these categories of actions, you can introduce your own categories.
All tasks described below in this section except for viewing property of an action can be performed only when PowerGUI Administrative Console is running in Authoring mode. For more information, see the Launching Admin Console in Authoring Mode section of this document.
Creating Actions
You can create basic actions and script actions. First, decide on the category (such as Links, Actions: Common, or some custom category) that your action belongs to. If it does not fit into any existing categories, create a new category by right-clicking in the Actions pane of the PowerGUI Administrative Console and selecting New | Category. To create a basic action 1. 2. Right-click the category and select New | Action. Select the required command from the Command drop-down list or search for it, and then specify predefined parameters and select the parameters you want to be prompted for. The list of commands available to you is defined by the set of libraries installed on your computer (File | PowerShell Libraries). Click Display Configuration to configure action properties:
The category to contain the action How to display results Whether this action affects selected objects so the view needs to refresh. Whether this action requires a selection (and pipeline input) or works without any incoming objects (for example, creating a new user does not need user objects to be piped in) Object types associated with the action
3.
20
To create a script action 1. 2. 3. Right-click the category and select New | Script Action. Leave the Custom script option selected in the Command drop-down list and type or paste your script in the field below. Click Display Configuration to configure action properties: a) b) c) d) The category to contain the action How to display the results Whether this action affects selected objects so the view needs to refresh. Whether this action requires a selection (and pipeline input) or works without any incoming objects (for example, creating a new user does not need user objects to be piped in) Object types associated with the action
e)
You can drag-and-drop actions both within and among available categories.
Other Options
To view or edit the property of an action, right-click it and select Properties. Click Display Configuration to configure action properties, set up a category to locate the action, select how to display results, and specify whether this action affects groups of objects. You can also change the type of objects associated with this action. To delete an action, right-click it and select Delete. To rename an action, right-click it and select Rename.
An action can be made the default action for selected objects. Default actions are performed when you double-click an object on the Results tab. To set an action as a default action, right-click it in the Actions pane and use the Make Default toggle.
For a full list of available PowerPacks, refer to the PowerPacks section of the PowerGUI website (http://powergui.org). The site organizes PowerPacks into categories, which include Active Directory, SharePoint, Virtualization, and so on.
3.
22
To import a PowerPack 1. 2. 3. 4. 5. Open the PowerPack Management dialog from the File menu. Select Import. The Open dialog box appears. Browse to the location of the PowerPack. On the right pane of the dialog box, the PowerPack description and required PowerShell snap-ins and modules will be displayed. Select the PowerPack and click Open.
To export a PowerPack
Exporting PowerPacks is allowed only when PowerGUI Administrative Console is running in Authoring mode. For more information, see the Launching Admin Console in Authoring Mode section of this document.
1. 2. 3. 4.
Open the PowerGUI Administrative Console. Open the PowerPack Management dialog box from the File menu. Select a PowerPack and click Export in the toolbar. Provide a file path to the PowerPack location and the version number, and then click the Export button.
Any node in any PowerPack can be included in any other PowerPacks or excluded from any PowerPacks it currently belongs to. This is configured on a per-node and per-action basis: open the properties of the node or action you need, click the More button, and use the PowerPacks list box to change the associations of the node or action with PowerPacks.
Creating PowerPacks
You can add your own functionality to PowerGUI to extend the PowerGUI Administrative Console.
Creating PowerPacks is allowed only when PowerGUI Administrative Console is running in Authoring mode. For more information, see the Launching Admin Console in Authoring Mode section of this document. For more detailed information about creating PowerPacks, refer to the PowerPacks section on the http://wiki.powergui.org website.
To create a PowerPack 1. 2. 3. Open the PowerGUI Administrative Console. Right-click the node that you want to make the root node of the new PowerPack, and select Create New PowerPack. If the node does not exist yet, create it first. In the New PowerPack dialog box, enter the following for the new PowerPack: a) b) c) Name Version number Description (optional)
23
d) e) f)
PowerPack requirementsrequired PowerShell snap-ins and modules (optional) PowerPack file linkthe URL or intranet location of the *.powerpack file for automatic update checks (optional) PowerPack home pagethe Web page with information about the PowerPack (optional). If the home page is set, a link to it is displayed next to the PowerPack name in the PowerPack Management dialog box.
It is recommended that you specify the optional information for your users convenience. This information helps them understand what the PowerPack does (from the description and home page), automatically check requirements, and look for updates (if a valid PowerPack link is specified).
4.
If necessary, click the Advanced button to select specific nodes, actions, and icons, and then click OK.
2. 3.
Copy the *.powerpack files to a share that is available to all future users of the customized consolefor example, \\mysrv\public. Prepare a Redirections.xml file to make the customized configuration available to authorized users. This file contains the paths to PowerPack folders and lockdown settings. A sample Redirections.xml file is created by default when you deploy the product; it can be found in your profile folder. Store the paths to the folder with the *.powerpack files in the <PowerPackFolders> element in Redirections.xml like this:
All *.powerpack files found in the specified folders will now be loaded every time the PowerGUI Administrative Console starts up. Changes since the last time are applied as follows:
If there have been updates to existing PowerPacks, these updates will be applied (unless the existing copy of the PowerPack has a later version than the shared copy). If new PowerPacks have been added, these PowerPacks will appear in the PowerGUI Administrative Console. If any PowerPacks have been removed, existing versions of these PowerPacks will remain in the PowerGUI Administrative Console.
4.
Use the lockdown feature to deactivate or hide the functionality that the users are not supposed to access (for example, disallow adding or modifying nodes in the tree, viewing the PowerShell code behind the functionality, and so on). To lock configuration items and actions, modify the Lockdown.xml file in the PowerGUI user profile folder. Save the modified file in an easily accessible location, for example, \\mysrv\public\LD1\lock.xml. For details about editing the Lockdown.xml file, see the Creating a Custom GUI for Helpdesk Users section of this document. Store the full path to the lockdown file in the <Lockdown> element in the Redirections.xml file like this: To distribute the customized configuration and lockdown settings to users across the network, use the Redirections.xml file. For that, any suitable file distribution method can be used: remote access, logon script, Group Policy, and so on. The Redirections.xml file should be stored in the PowerGUI user profile folder.
Alternatively you can distribute the Redirections.xml file to the All Users profile to make it available for all users of the computer. However, the profiles of particular users have a higher priority, so the settings in the All Users profile have an effect only in the absence of overriding settings in user profiles.
5.
<Lockdown>\\mysrv\public\LD1\lock.xml</Lockdown>
6.
For a step-by-step use scenario, see the Creating a Specialized Helpdesk Console section of this document.
25
Creating Snapshots
To create a new snapshot, open the File | Snapshots dialog box and click Take Snapshot. Now you have your current PowerGUI Administrative Console configuration saved and can revert to it any time you want.
When the PowerPack collection is changed (some PowerPacks have been added, removed or updated), a snapshot of the previous configuration is created automatically. Thus you can check what exactly has changed and revert to the previous configuration if necessary.
Comparing Snapshots
To compare two saved PowerGUI Administrative Console snapshots, you should select necessary PowerGUI Administrative Console snapshots in the Snapshots dialog box and click Compare.
If you want to compare your current configuration with a snapshot, just select the snapshot and click Compare. It will be automatically compared with your current PowerGUI Administrative Console configuration.
26
A report will be generated and automatically opened in the Web browser. To see detailed information about each change, click the entry for that change, and the information about it will be shown.
Viewing Snapshots
Select a snapshot in the Snapshots dialog box and click View to see how reverting to this snapshot will affect your PowerGUI Administrative Console configuration without making any changes to your current configuration state. A new instance of PowerGUI Administrative Console will be started using the configuration in the selected snapshot.
Removing Snapshots
To remove unnecessary snapshots, select them in the Snapshot dialog box and click Remove.
27
28
Syntax Highlighting
In the PowerGUI Script Editor, the following is highlighted in specific colors to help identify tokens in a script: Cmdlet names Alias names Statement identifiers Variables .NET types Comments Quoted strings
IntelliSense
IntelliSense provides features that make language references easy to access. When coding, you do not have to leave the edit view to perform searches on language elements. You can keep your context, find the information that you need, insert language elements directly into your code, and even have IntelliSense complete your typing for you. The PowerGUI Script Editor supports IntelliSense for: Cmdlets Parameters WMI objects .NET objects Variables File paths
IntelliSense is activated automatically when certain keys are pressed, such as when you press the dash (-) key after typing Get. IntelliSense can also be activated manually by pressing Ctrl+Space or through the Complete Word item in the Edit menu. This feature works inside remote sessions as well.
Code Snippets
Snippets are ready-made small PowerShell code templates that make it easier to create syntactically correct scripts. In addition to regular snippets, the PowerGUI Script Editor comes with VBScript snippets, which are PowerShell code templates implementing VBScript functionality.
29
Using Snippets
PowerGUI supports insertion of snippets in the PowerGUI Administrative Console and in the PowerGUI Script Editor. To insert a snippet in the PowerGUI Script Editor, select Edit | Insert Snippet (Ctrl + I) or Edit | Insert VBScript Snippet (Ctrl + B). To insert a snippet in the embedded editor in the PowerGUI Administrative Console, press Ctrl + I for a PowerShell snippet or Ctrl + B for a VBScript snippet.
Managing Snippets
Snippets can be managed using the PGSnippetPath environment variable. It provides capabilities for adding new snippets and overriding the existing ones without changing the core installation. The PGSnippetPath variable contains a semicolon-separated list of folders where PowerGUI searches for snippets (*.snippet files).
When loading a PowerShell module, PowerGUI automatically adds the path of the snippets folder placed in the root folder of the module to PGSnippetPath and removes it when the module is unloaded. Thus, if you want to add some snippets when importing a PowerShell module, you should put them in the snippets folder of the module.
The priority of each folder is determined by its position in PGSnippetPath; the first folder has the highest priority. This allows overriding snippets without changing the original ones. See the following situation for an example: PGSnippetPath equals %UserProfile%\My Documents\WindowsPowerShell\snippets;%PGInstallDir%\snippets. Both folders contain a snippet named test.snippet. If you insert test.snippet in your script, you will get the snippet from the %UserProfile%\My Documents\WindowsPowerShell\snippets folder, because it has a higher priority than the second folder.
30
Block Indent
You can increase or decrease indent of a block of code by selecting the lines you want to move and then selecting Edit | Advanced | Increase Indent or Edit | Advanced | Decrease Indent. You can also use the following shortcut keys: To increase indent of the selected block of code, press Tab. To decrease indent of the selected block of code, press Shift + Tab.
For formatting consistency, you can easily convert tab indents to space indents and the other way around. For that, use the Edit | Advanced | Convert Tabs to Spaces and Edit | Advanced | Convert Spaces to Tabs commands. In the PowerGUI Script Editor Options dialog box on the Text Editor screen, you can configure the size of tabs and whether spaces should always be used instead of tabs.
Block Comment
You can comment out a block of code by selecting the lines you want to change and then selecting Edit | Advanced | Comment Block or Edit | Advanced | Uncomment Block. You can also use the following shortcut keys: To comment out the selected block of code, press Ctrl + Shift + C. To uncomment the selected block of code, press Ctrl + Shift + U
Bookmarks
You can set bookmarks to mark the places in your script that you are working on. Bookmarks are used for making modifications in multiple places in large files when you cannot see the entire script on a page or two. For bookmark controls, click Edit | Bookmarks. These controls are not located in the toolbar by default but you can easily add them. For that, click Tools | Customize, and drag the following commands from the Customize dialog box to the toolbar: Toggle Bookmark Previous Bookmark Next Bookmark Clear Bookmarks
31
Before you close your editing session, you will be asked whether you want the currently opened scripts to be loaded automatically (with the same bookmark, breakpoint, and code folding settings) the next time you start the PowerGUI Script Editor.
AutoRecover
PowerGUI Script Editor has AutoRecover functionality. If you turn on AutoRecover, your script files are automatically saved in particular periods of time. Therefore, if you have been working for a long time without saving a script and your computer unexpectedly turned off, the recovered script contains all or at least some of the work you have done since you last saved the original script. To turn on AutoRecover, select it in the Tools | Options | Text Editor dialog box. Also you can set how often AutoRecover information should be saved (every 60 seconds by default).
If you change the frequency of AutoRecover information saves, then new value of period is applied only when previous interval is over.
Automatic Variables
The state of PowerGUI is stored in the following automatic PowerShell variables that you can use in scripts: $PGHome Full path of the installation directory for PowerGUI
32
$PGUICulture Current language of the PowerGUI user interface $PGVersionTable Hash table of PowerGUI version details. Contains versions of the following components: a) b) PowerGUI PowerGUI Script Editor SDK
Code Folding
The PowerGUI Script Editor supports code folding, outlining, and regions. This helps you to organize your script and make it more readable. You can easily hide a block of code from view. For example, user-defined regions can be created by using the #region / #endregion construct. By default, regions are collapsed every time you open a script that contains them.
33
Compiling Scripts
You can compile scripts into standalone executable files. Such files can be run by users without any specific PowerShell knowledge on any computer with Windows PowerShell 2.0 installed. Also your scripts can be compiled into Windows services. In that case PowerGUI Script Editor produces service installation files. To prevent unauthorized usage of the compiled executable files and the source script code within them, you can protect the executable files with a password. By default, compiled executable file or windows service is compatible with the same PowerShell version as the PowerGUI Script Editor that was used to create this file or service. To work with other PowerShell versions, run a compiled executable file or windows service with the -version parameter on the target computer, as follows:
<file name>.exe version <version number> When generating an executable file, the PowerGUI Script Editor creates the executable (<file name>.exe) and the corresponding configuration file (<file name>.exe.config). To work with different versions of PowerShell, you need to copy both files on the target computer.
34
3. 4. 5.
Specify the path where the target executable file should be placed after the compilation. Specify additional PowerShell Console window settings. If you want to protect the executable file and its contents with a password, select the Protect script source code with password option, then enter and confirm the password.
The source code of the script within the executable file will be encrypted using the specified password.
6.
7.
If your script relies on additional PowerShell files, then specify them in the Dependencies dialog box. These files will be compiled into the executable file as well as your script. Click OK to create the target executable file from the source script with specified settings.
35
3. 4.
Specify the path where the service installation file should be placed after the compilation. Specify service settings that will be used by default. These settings can be changed when user starts the service installation wizard.
Specified service name cannot be changed later.
5.
If you want to protect the service installation file and its contents with a password, select the Protect script source code with password option, then enter and confirm the password.
The source code of the script within the service installation file will be encrypted using the specified password.
6.
7.
If your script relies on additional PowerShell files, then specify them in the Dependencies dialog box. These files will be compiled into the service installation file as well as your script. Click OK to create the service installation file from the source script with specified settings.
4.
To uninstall the service, run the service installation file from command line with the -service uninstall parameter.
37
b)
Other version control systems should work if their providers fully support MSSCCI (for example, Subversion with the TortoiseSVNSCC provider), but they have not been tested with the PowerGUI Script Editor. For specific information about integrating TortoiseSVNSCC with PowerGUI Script Editor, see the corresponding section below.
To connect to the version control provider 3. 4. 5. 6. 7. On the Tools menu, click Options. In the Options dialog box, select Version Control. Select the source control provider from the list, or select None if you need to disable version control. Use the Advanced button to configure the settings for your source control provider. This option may not be available for some version control providers. Consider using Dont show Check In dialog box when checking in items option.
You can identify your file status in version control. If a blue check mark icon appears on the document tab, your file is under version control and checked in. The check mark becomes red when the file is checked out from version control. The following actions are available in the Version Control menu: Get Latest Version Copies the file to the local computer if you do not have it already. If the file is already there, it will be updated if it has changed. Check Out Locks the file for editing. Check In Adds the new version of the file to version control. Undo Check Out Reverts the checkout operation. Add to Version Control Places the current file under version control. Get Files from Version Control Copies files from the specified directory located in the version control database to the local computer. The dialog is supplied by the version control provider.
If version control support is configured, when you save a file, you are prompted to add it to version control. The user experience depends on the version control provider you are using.
39
Subversion (SVN) version control system is not officially supported by PowerGUI Script Editor, so its proper operation is not guaranteed.
The TortoiseSVNSCC provider, which is freeware available from http://tortoisesvnscc.tigris.org, requires version 1.3.5 of the TortoiseSVN client to be installed. Note that this version of TortoiseSVN is not current.
If you install the TortoiseSVNSCC as documented in its readme file, but SVN does not become available in the PowerGUI Script Editor, the installation procedure may require a slight variation. The readme file that comes with TortoiseSVNSCC tells you to unpack the DLL file provided and register it using the regsvr32 utility. Registration works correctly only on systems where User Account Control (UAC) is absent or disabled. UAC was first introduced in Vista, later than TortoiseSVNSCC was released. On systems where UAC is enabled, the procedure, as described in the readme file, works with a virtual registry. As a result, the source control provider is not properly registered. To fix this issue, perform the registration step on such systems as follows: 1. 2. Open the command prompt as an administrator. Use regsvr32 in the administrator command prompt to register the DLL file.
If regsvr32 fails, perform the following: 1. 2. 3. 4. 5. 6. 7. Download the http://tortoisesvnscc.tigris.org/files/documents/2074/18555/install.reg file. Change the extension of the downloaded file to *.reg if it differs. Open file with a text editor. Edit the paths in the downloaded file to match your TortoiseSVNSCC provider configuration. Run regedit with administrative privileges. In the registry editor click File | Import and open the previously downloaded file. Add the path <TortoiseSVNSCC Installation Folder>\bin to your PATH environment variable.
To create your own PowerGUI Script Editor add-on 1. 2. 3. Open the %UserProfile%\My Documents\WindowsPowerShell\Modules folder or create it if necessary. Create a subfolder for your add-on. Start the PowerGUI Script Editor and create a file containing the following add-on script code:
if ($host.Name ne PowerGUIScriptEditorHost) { return } $se = [Quest.PowerGUI.SDK.ScriptEditorFactory]::CurrentInstance # TODO: Put your actual code here write-host "Hello World"
This add-on checks that it is run under the PowerGUI Script Editor, gets access to the PowerGUI Script Editor API and outputs "Hello World" message. 4. Save this file as PowerShell module file (*.psm1) to the previously created addon folder.
The name of the PowerShell module file and the add-on folder should be the same.
5. 6.
Select your created add-on in the Snapins/Modules dialog box (File | PowerShell Libraries). When you click OK you can see that the add-on gets loaded and Hello World is displayed in the embedded PowerShell Console.
If you get an error message ensure that execution of scripts is enabled on your system using Get-ExecutionPolicy and Set-ExecutionPolicy cmdlets.
Note that because of the PowerShell 2.0 specifics some parts of add-on script code may not be executed properly. Mostly it concerns event handlers such as command scripts used in menus/toolbars and PowerGUI Script Editor DebuggerStateChanged event handler. Automatic variables like $_, $args, $input, $this and $pscmdlet may return $null instead of existing object when used in event handlers causing improper script execution. In this case try to replace constructions that contain listed automatic variables with the other PowerShell constructions (for example foreach statement instead of ForEach cmdlet, if-else statement instead of Where-Object cmdlet etc.), reduce usage of PowerShell advanced functions etc. For more information, see this Microsoft Connect page: https://connect.microsoft.com/PowerShell/feedback/details/559223.
41
Supply applicable keywords in the search box and click Search (to display all available add-ons, simply leave the search box blank). Search is performed within the PowerGUI community website.
42
Use Scenarios
This section discusses a few real-world examples, which you can adapt to your needs.
43
4.
Expand the newly-added Org Chart node and select Entire Organization. Confirm the operation in the prompt, and wait for the chart generation to complete.
The resulting chart can be viewed with as much detail as needed and exported to multiple formats.
44
2.
To focus on the administrators, create a filter. For that, click the Filters button, select Name in the Property column, Contains in the Operator column, type "admin" in the Value column, and click Apply.
3.
The list is reduced to the single Administrators group. Double-click the group to perform the default action, which in this case is View Members. It is bolded in the Actions pane. The list of group members is shown.
4.
Select all members and click the Export to CSV action. In the dialog box that opens, specify the full path to the CSV file, for example, C:\Windows\Temp\local-admins.csv.
45
Quest is not affiliated with http://poshcode.org and assumes no responsibility for the code you find in this online repository. You should always review and test publicly available code before using it in a production environment.
4.
46
5. 6.
Run the script to make the function declarations known to PowerShell. In the PowerShell Console pane, type: The IntelliSense prompt suggests auto-completion options as you go along.
7.
Execute the command you have typed, and see the results.
Take the following steps: 1. 2. Copy the code into the PowerGUI Script Editor and save it as a local file. Set a breakpoint at the $wmiServices.Add($_.Name,$_) method call location. For that, right-click this word and select Toggle BreakPoint or place your cursor on the word and press F9.
47
3.
4.
When the script stops at the breakpoint you have set, check the Variables pane in the lower left corner to view the current values of variables.
5.
Use the Debug | Step Into command again to progress one step further and check the variables again.
48
6.
7.
Remove the breakpoint from $wmiServices.Add($_.Name,$_) by right-clicking it and selecting Toggle BreakPoint or by placing the cursor on the word and pressing F9. Select Debug | Start Debugging in the main menu or press F5. See the output in the PowerShell Console pane, and note how the Count property of the $wmiServices variable has changed.
If you have multiple scripts to debug, consider whether you want to perform all your debugging activity in the same PowerShell runspace, or create a clean runspace for each debugging run. This is specified in the Options dialog box on the Debug Options screen by the Run all scripts in the same runspace (the default) and Reset PowerShell runspace each time debugging is started options.
You can manually create a clean PowerShell runspace by clicking Debug | Reset Runspace. When the Reset PowerShell runspace each time debugging is started option is on, the runspace is not cleared for text selections that you execute or
49
for commands that you enter in the PowerShell Console pane of the PowerGUI Script Editor.
The <Enabled> element specifies whether the action in <Item> is allowed. The <Visible> element specifies whether it even appears in context menus in the user interface.
50
To effectively disallow user interface customization, it is sufficient to set <Enabled> and <Visible> to False for items with display names such as the following: TreeNode: New TreeNode: Delete TreeNode: Rename TreeNode: View Properties TreeNode: Change Cmdlet TreeNode: Change Cmdlet Parameters
Depending on the purpose of your console, you may want to restrict other items as well. Save your changes and copy the file to a network share that is available to all future users of the customized console. For example, the file becomes \\mysrv\public\cfg\helpdeskui-lockdown.xml.
In the <Lockdown> elements, specify the XML file you have prepared. In the <PowerPackFolders> element, specify the folder with the custom *.powerpack file.
The Delegating Administrative Tasks section in this document contains details about PowerGUI profiles and a note about using the All Users profile.
51
2.
<WelcomePagePath>\\mysrv\public\cfg\helpdesk-welcomepage.mht</WelcomePagePath>
In the <WelcomePagePath> element, specify the MHT file you have prepared. The <WelcomePagePath> element must be inside the <Redirections> element. 3. Distribute the updated Redirections.xml file using any method approved in your environment, as described in the Distributing the Console section above.
52
Web site
Refer to our Web site for regional and international office information.
View the Global Support Guide for a detailed explanation of support programs, online services, contact information, policies and procedures. The guide is available at: www.quest.com/support.
53
Source Code and Executable Files can be used in commercial applications; Source Code and Executable Files can be redistributed; and Source Code can be modified to create derivative works. No claim of suitability, guarantee, or any warranty whatsoever is provided. The software is provided "as-is". The Article accompanying the Work may not be distributed or republished without the Author's consent This License is entered between You, the individual or other entity reading or otherwise making use of the Work licensed pursuant to this License and the individual or other entity which offers the Work under the terms of this License ("Author").
License THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CODE PROJECT OPEN LICENSE ("LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HEREIN, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE AUTHOR GRANTS YOU THE RIGHTS CONTAINED HEREIN IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS. IF YOU DO NOT AGREE TO ACCEPT AND BE BOUND BY THE TERMS OF THIS LICENSE, YOU CANNOT MAKE ANY USE OF THE WORK.
Definitions. "Articles" means, collectively, all articles written by Author which describes how the Source Code and Executable Files for the Work may be used by a user. "Author" means the individual or entity that offers the Work under the terms of this License. "Derivative Work" means a work based upon the Work or upon the Work and other pre-existing works. "Executable Files" refer to the executables, binary files, configuration and any required data files included in the Work.
54
PowerGUI 3.5 - User Guide "Publisher" means the provider of the website, magazine, CD-ROM, DVD or other medium from or by which the Work is obtained by You. "Source Code" refers to the collection of source code and configuration files used to create the Executable Files. "Standard Version" refers to such a Work if it has not been modified, or has been modified in accordance with the consent of the Author, such consent being in the full discretion of the Author. "Work" refers to the collection of files distributed by the Publisher, including the Source Code, Executable Files, binaries, data files, documentation, whitepapers and the Articles. "You" is you, an individual or entity wishing to use the Work and exercise your rights under this License. Fair Use/Fair Use Rights. Nothing in this License is intended to reduce, limit, or restrict any rights arising from fair use, fair dealing, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws. License Grant. Subject to the terms and conditions of this License, the Author hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below: You may use the standard version of the Source Code or Executable Files in Your own applications. You may apply bug fixes, portability fixes and other modifications obtained from the Public Domain or from the Author. A Work modified in such a way shall still be considered the standard version and will be subject to this License. You may otherwise modify Your copy of this Work (excluding the Articles) in any way to create a Derivative Work, provided that You insert a prominent notice in each changed file stating how, when and where You changed that file. You may distribute the standard version of the Executable Files and Source Code or Derivative Work in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution. The Articles discussing the Work published in any form by the author may not be distributed or republished without the Author's consent. The author retains copyright to any such Articles. You may use the Executable Files and Source Code pursuant to this License but you may not repost or republish or otherwise distribute or make available the Articles, without the prior written consent of the Author. Any subroutines or modules supplied by You and linked into the Source Code or Executable Files this Work shall not be considered part of this Work and will not be subject to the terms of this License. Patent License. Subject to the terms and conditions of this License, each Author hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, import, and otherwise transfer the Work. Restrictions. The license granted in Section 3 above is expressly made subject to and limited by the following restrictions: You agree not to remove any of the original copyright, patent, trademark, and attribution notices and associated disclaimers that may appear in the Source Code or Executable Files. You agree not to advertise or in any way imply that this Work is a product of Your own. The name of the Author may not be used to endorse or promote products derived from the Work without the prior written consent of the Author. You agree not to sell, lease, or rent any part of the Work. This does not restrict you from including the Work or any part of the Work inside a larger software distribution that itself is being sold. The Work by itself, though, cannot be sold, leased or rented. You may distribute the Executable Files and Source Code only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy of the Executable Files or Source Code You distribute and ensure that anyone receiving such Executable Files and Source Code agrees that the terms of this License apply to such Executable Files and/or Source Code. You may not offer or impose any terms on the Work that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute the Executable Files or Source Code with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License.
55
PowerGUI 3.5 - User Guide You agree not to use the Work for illegal, immoral or improper purposes, or on pages containing illegal, immoral or improper material. The Work is subject to applicable export laws. You agree to comply with all such laws and regulations that may apply to the Work after Your receipt of the Work. Representations, Warranties and Disclaimer. THIS WORK IS PROVIDED "AS IS", "WHERE IS" AND "AS AVAILABLE", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OR CONDITIONS OR GUARANTEES. YOU, THE USER, ASSUME ALL RISK IN ITS USE, INCLUDING COPYRIGHT INFRINGEMENT, PATENT INFRINGEMENT, SUITABILITY, ETC. AUTHOR EXPRESSLY DISCLAIMS ALL EXPRESS, IMPLIED OR STATUTORY WARRANTIES OR CONDITIONS, INCLUDING WITHOUT LIMITATION, WARRANTIES OR CONDITIONS OF MERCHANTABILITY, MERCHANTABLE QUALITY OR FITNESS FOR A PARTICULAR PURPOSE, OR ANY WARRANTY OF TITLE OR NON-INFRINGEMENT, OR THAT THE WORK (OR ANY PORTION THEREOF) IS CORRECT, USEFUL, BUG-FREE OR FREE OF VIRUSES. YOU MUST PASS THIS DISCLAIMER ON WHENEVER YOU DISTRIBUTE THE WORK OR DERIVATIVE WORKS. Indemnity. You agree to defend, indemnify and hold harmless the Author and the Publisher from and against any claims, suits, losses, damages, liabilities, costs, and expenses (including reasonable legal or attorneys fees) resulting from or relating to any use of the Work by You. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL THE AUTHOR OR THE PUBLISHER BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK OR OTHERWISE, EVEN IF THE AUTHOR OR THE PUBLISHER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Termination. This License and the rights granted hereunder will terminate automatically upon any breach by You of any term of this License. Individuals or entities who have received Derivative Works from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 6, 7, 8, 9, 10 and 11 will survive any termination of this License. If You bring a copyright, trademark, patent or any other infringement claim against any contributor over infringements You claim are made by the Work, your License from such contributor to the Work ends automatically. Subject to the above terms and conditions, this License is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, the Author reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above. Publisher. The parties hereby confirm that the Publisher shall not, under any circumstances, be responsible for and shall not have any liability in respect of the subject matter of this License. The Publisher makes no warranty whatsoever in connection with the Work and shall not be liable to You or any party on any legal theory for any damages whatsoever, including without limitation any general, special, incidental or consequential damages arising in connection to this license. The Publisher reserves the right to cease making the Work available to You at any time without notice Miscellaneous This License shall be governed by the laws of the location of the head office of the Author or if the Author is an individual, the laws of location of the principal place of residence of the Author. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this License, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent. This License constitutes the entire agreement between the parties with respect to the Work licensed herein. There are no understandings, agreements or representations with respect to the Work not specified herein. The Author shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Author and You.
56