PowerToys Pack 3.0 User Guide

Skip to end of metadata
Go to start of metadata

PowerToys are sample R# plugins that show how to use various techniques together. Their source code can be used as a quickstart for developing a complete R# plugin with an installer.

Some of the PowerToys are pure samples demonstrating the use of basic components. Others are so complex that they require good knowledge of ReSharper OpenAPI to understand the source code, but the things they do are useful enough to make them worth installing just to add functionality to ReSharper.

The PowerToys Pack installation includes all of the PowerToys in the binary form, along with the complete source code and the installer build infrastructure.

Download

Installation

The PowerToys Pack installation package can be installed either per-machine (ALLUSERS) or per-user, and it contains the following features:

  • Binaries for all the PowerToys that are installed as R# plugins.
    You may select to skip installation of one or more plugins. Based on the ALLUSERS setting, they go either to the Plugins folder under the R# installdir, or to the local application data folder of the current user. This install location cannot be customized other than through the RESHARPERPLUGINS property.

  • The complete source code for the PowerToys and their installers.
    The source code is installed to the PowerToys directory, either under the R# installdir, or under the local application data folder of the current user, depending on the ALLUSERS setting. This directory location can be customized if you choose the Advanced installation mode.

Package Contents

The directory structure of the Source part of the package (located under the PowerToys folder by default) includes the following top-level folders:

  • Bin
    This directory is created during the build, and does not exist in a clean installation.
    The output folder for the binaries build out of the source code, and for the installers. The latter also use it as input folder for the plugin binaries to be included with the installation package.
  • Build
    Contains the central build file.
  • Doc
    Documentation on the PowerToys and ReSharper.
  • Obj
    This directory is created during the build, and does not exist in a clean installation.
    Intermediate directory for the build process temporary files (relocated from under the projects).
  • Setup
    Contains the common infrastructure for the PowerToy installers that can be reused when creating installers for custom R# plugins.
  • Src
    The source code for the PowerToy sample plugins.

Before You Compile

Before the PowerToys solution can be opened in Visual Studio and compiled, it must be provided with a path to the ReSharper assemblies folder, as needed by the assembly references in the projects.

This path is configured in the Src/PowerToys.Common.Targets file that is included into each of the projects. This way there is a singple place to specify the path for all the projects in a row, and no project file has to be modified.

This file is an MSBuild script. Open Src/PowerToys.Common.Targets in an XML editor and change the ReSharperBinariesDir property value to point to the Bin directory in the ReSharper installation location. You should not use relative paths because they're not valid across multiple project files.

Example:

Opening the Solution

After you have the R# binaries path specified, the solution may be opened in Visual Studio and compiled.

Note that a warning box may pop up when opening the solution for the first time, for the project files have been modified to include the Src/PowerToys.Common.Targets file with global settings. This warning should be ignored.

Building the solution will produce the plugin DLLs in the PowerToys top-level Bin folder, writing the intermediate files to Obj. The resulting plugins are VisualStudio-version-independent. The installers will not be built when compiling the solution.

Building the Installers

PowerToy installers are based on the Windows Installer (MSI) 2.0 technology, using the Microsoft Windows Installer XML (WiX) toolset for compilation.

A compatible WiX version is required for building the installers. The PowerToys have been developed and tested against WiX version 3.0.2420.0. Later versions may also be compatible, but that is not guaranteed.

Each PowerToy has its own installer project named PowerToyName.Setup.Proj located in the PowerToy project folder (example: Src/CsUnit/CsUnit.Setup.Proj). These files are kept as simple as possible. All they have is a group of settings personalizing the installation for the current plugin, and an include of the common installers file Setup/ReSharperPowerToySetup.Targets that defines the installer infrastructure.

An installer for a custom plugin can be based on the same infrastructure. Modifying the Name.Setup.Proj settings is the only thing needed to get a fully-functional R# plugin installer.

Before you can compile the PowerToy installers, the Setup/ReSharperPowerToySetup.Targets file has to be edited to locate the WiX toolset installation on your machine. There are two basic scenarios supported:

  • WiX is installed on each machine, and its binaries are on the %PATH% environment variable. In this case all of the WiX path definitions must be removed from Setup/ReSharperPowerToySetup.Targets.
  • WiX is included with the project (e. g. for running automated builds on multiple agents). The WiX paths must be modified to point to a proper location on your system.

Running the Central Build

The Build/Build.proj file is a central build script for the whole PowerToys project. It can be used to build the source code and installers for all of the PowerToy plugins. Being an MSBuild script, it should be run with the MSBuild.exe executable.

This script has a number of input parameters that help with customizing the build.

  • ReSharperBinariesDir
    This setting is used by the sources build (solution) for locating the R# DLL references. It overrides the value defined in Src/PowerToys.Common.Targets.
    Must be an absolute path, no relative paths allowed.

  • PowerToysBinariesDir
    Specifies the output directory for the sources build, files directory for the installer builds (PowerToys top-level Bin folder by default).
    Must be an absolute path, no relative paths allowed.

  • VsVersion
    Specifies the version of Visual Studio that the installers will be targeting. The plugin binaries are version-independent.
    Example: "9.0".

Creating a New Plugin with an Installer

There are no special requirements for the plugin projects.

It is recommended that you use the existing PowerToys infrastructure for building the custom installers. If your plugin has a single DLL to install, the only thing you have to do to get a fully-functional installer is define a setup project (e.g. ProjectName.Setup.Proj) in your plugin directory that follows the PowerToys pattern. It should define the necessary properties and include the common setup infrastructure file Setup/ReSharperPowerToySetup.Targets. For this scheme to work, the Setup directory must be included in your folder structure, and the plugin should be located in its own folder under the Src folder, Src/ProjectName.

The central build file may be used for building your plugin with an installer in an automated mode.

  • No labels