How to Use the PowerToy

This document discusses how to install the PowerToy and how to use it to configure a tool-window and editor for a DSL.

For general information about this release, please go here.

How to Install

The PowerToy is delivered as an MSI (Windows Installer) package.
This installer installs the various files to the developer’s computer, and to the user’s program files directory by default.

Note. Before running the installer you need to make sure all instances of Visual Studio (devenv.exe), are closed and that you have installed all the pre-requisite software (found here).

WARNING: The installer will not run if any of these pre-requisites are not present on the machine.

How to Get Started

Once the PowerToy is installed, you need to open Visual Studio 2005, and either create a new, or open an existing DSL solution.

Note. A ‘DSL solution’ in this context is defined as any Visual Studio solution containing one or more DSL projects. (By default, the DSL toolkit creates a solution file (*.sln) with two projects (called: Dsl, and DslPackage) which make up a single DSL.

In order to use the PowerToy with the solution, you need to register the PowerToy’s ‘Guidance Package’ with the solution. This guidance package contains the commands and guidance to use the PowerToy. You do this by completing the following steps:
  1. Select the ‘Tools’ menu and select ‘Guidance Package Manager’
  2. Click the ‘Enable/Disable packages' button
  3. Check the ‘Dsl Editor PowerToy’ guidance package in the list
  4. Press OK, and close the ‘Guidance Package Manager’ window
Register DSL Solution.png
The PowerToy Guidance Package is now active for this solution, and you can now configure your solution with the PowerToy. (see below)

Guidance Navigator Window

Once the guidance package is registered, the ‘Guidance Navigator’ window is now activated and will display details about the guidance package.

Note. If this window is not visible, you can show it by selecting the ‘View’ menu, then ‘Other Windows’ menu, then ‘Guidance Navigator Window’.
The main tab of the ‘Guidance Navigator’ includes basic overview information about the PowerToy, such as links to documentation etc. On the ‘Available Guidance’ tab, is listed the recipes that can be executed on the solution.
Note. Each recipe in the list can be expanded to show links to other documentation and tasks you can perform.
Note. If you can't see both 'Add' and 'Remove' recipes in this view, and you have GAT (v1.1 or earlier) installed, it's because of a bug in GAT that does not show some recipes here. You need to install the newer version of GAT (v.1.2, Feb2007CTP) to fix this.

How to Configure

To get started using the PowerToy, right-click on the solution in ‘Solution Explorer’ and select ‘Add DSL Toolwindow’ from the context menu.
Solution Menu.png
A recipe runs, and the ‘Add DSL Toolwindow’ wizard appears, where you define the configuration for your tool-window.

Basic Configuration

Basic Config.png
The PowerToy needs to collect some basic information to install your tool-window, this configuration uses the defaults which are used by the DSL toolkit when your DSL solution was created.
  • Select the DSL package project of the DSL you wish to configure. (By default, this is a project with the name ‘DslPackage’)
  • Enter a title for the tool-window as you want it to appear when using your DSL. (This title will be used as the name of the tool-window and on menus that activate the tool-window.)

Advanced Configuration

Advanced Config.png
The advanced configuration page contains optional information to customize the configuration. You can use this if you don’t agree with the defaults, or you have somehow changed the structure and naming of the DSL projects created by default with your DSL solution.
  • Enter a folder path within the DSL package project to where the PowerToy will install its files. (By default, this will be a subfolder called ‘DslEditors’, under the ‘GeneratedCode’ folder).
  • Enter the full path the project CTC file. (By default, this file is located at ‘CtcComponents/Commands.ctc’)
Note. The settings you chose here will be preserved for later, should you wish to uninstall the Tool-window.
Once you have defined your configuration, press the ‘Finish’ button to complete the wizard. The wizard will configure your DSL solution with the new Tool-window.
Note. You can monitor this configuration progress in both the Output Window, and status bar of Visual Studio.

The PowerToy has added a number of files and configured your DSL project.
Generated Files.png

Press F5 to compile and run your DSL.
DSL Editor.png
Note. Detailed technical information about this recipe, and how it works can be found here

Repair

You can re-run this recipe on the same DSL package project, and it will repair and restore the tool-window configuration to its original state.

WARNING: In the repair, any customizations to the added files will be lost!

How to Remove

The PowerToy provides a recipe to remove the tool-window and its configuration. This recipe is only active on DSL package projects that have previously had a tool-window added to them.

WARNING: This recipe removes all added files, and configuration by the PowerToy. However, it only removes the files and configuration it added.

To remove the tool-window and its configuration, right-click on the DSL package project and select the ‘Remove DSL Toolwindow’ from the context menu.

Note. This recipe is initialised with the values you used to configure the tool-window.
  • Select the path to the folder where the PowerToy installed its files. (By default this will be ‘GeneratedCode/DslEditors’)
  • Select the project CTC file. (By default, this is: ‘CtcComponents/Commands.ctc’)
  • Press the ‘Finish’ button to complete the wizard. The wizard will remove all tool-window configuration from the DSL.
Note. You can monitor this configuration progress in both the Output Window, and status bar of Visual Studio.
Note. Detailed technical information about this recipe, and how it works can be found here

How to Customize

To customize the added Tool-window, see the How to Customize page.

Feedback

Please provide any feedback you have about the PowerToy release, issues, bugs, features, design etc. here

Last edited Mar 17, 2007 at 7:02 PM by jezzsa, version 14

Comments

No comments yet.