1.4 SDK Reference (R7)

Skip to end of metadata
Go to start of metadata

Welcome to the ReSharper SDK! The SDK has been designed to make ReSharper plug-in development and testing easy and enjoyable.

Please note that this document is provided only as a brief initial guide to plug-in development. For an in-depth look at the challenges of plug-in development, please consult the ReSharper 7 Plugin Development guide.

What’s in the SDK

The following list describes all the items that are installed as part of the ReSharper SDK. Let’s start with the items installed into the ReSharper SDK folder.

  • Bin --- this folder contains all of ReSharper’s assemblies, including assemblies that ReSharper relies on. In addition, this folder contains the PDBs for the ReSharper’s assemblies, as well as the full ReSharper test infrastructure.
  • Samples --- this folder contains a sample implementation of a ReSharper plug-in, complete with corresponding tests.
  • Tools --- this folder contains the tools that are used for developing support for new languages.

In addition to the SDK folders, ReSharper also installs Visual Studio templates for quickly creating projects or individual plug-in items. These items are typically installed into Visual Studio’s own \ItemTemplates and\ProjectTemplates folders.

There’s just one more thing that gets installed: the target files for ReSharper plug-ins and corresponding test projects. Both exist under your <ProgramFiles>\MSBuild directory. These files are used by the project template to quickly add references to all ReSharper assemblies to your project.

There are 8 target files overall: four files for plugin development and four files for testing. The test files end with.Tests.Targets. Each group consists of four separate target files as follows:

  • The .Common.Targets file contains the default values for the installation path of the SDK, the location of its binaries as well as tools.
  • The .References.Targets file contains a link to each of the reference assemblies required for plugin development or testing.
  • The .NoReferences.Targets file contains only a link to the .Common.Targets files and nothing else.
  • The ‘main’ target files (Plugin.Targets and Plugin.Test.Targets) contain links to both the Common files as well as References files. These are the files that are actually used by the templates.

Getting Started

To get a feel for the way in which plug-ins are developed, open up the sample project in the Samples folder. This project illustrates the following ReSharper features:

  • A code cleanup module
  • A context action
  • A daemon stage
  • An element problem analyzer
  • A quick-fix

Of course, the SDK itself is not limited to just these items: there are many more available.

Once you’ve familiarized yourself with the sample project, go ahead and create one of your own! The project templates for ReSharper plug-ins are available for both Visual Basic and Visual C#. Corresponding test project templates are also available.

Hint: ReSharper plug-in development is a lot easier if you use the tools such as the Psi Viewer which are available in ReSharper’s Internal Mode. To enable Internal Mode, edit Visual Studio’s shortcut, adding the string/ReSharper.Internal to the end. Restart Visual Studio to see an additional Internal menu under the ReSharper top-level menu.

Samples

The SDK comes with three sets of samples, all of which demonstrate the different aspects of ReSharper that can be extended.

First, in the SamplePlugin folder, we have a plug-in that shows how a single feature -- the option to convertMaxValue integer literals into correspondingly named constants. The SamplePlugin shows how to implement the following features:

  • Action
  • Context Action
  • Quick-Fix
  • Daemon Stage
  • Problem Analyzer
  • Code Cleanup
  • Options Page
  • Settings

as well as the associated tests.

The second set of examples is the ReSharper PowerToys. The PowerToys contain several projects illustrating different features of ReSharper extensibility, as shown in the table below.

  • CyclomaticComplexity: Daemon Stage, Highlighting, Options Page, Settings
  • ExploreTypeInterface: Action, Tool Window
  • FindText: Action, Search
  • GenerateDispose: Generator
  • Gist: Action, Settings, OptionsPage
  • LiveTemplatesMacro: Live Template Macro
  • MakeMethodGeneric: Refactoring
  • MenuItem: Action
  • OptionsPage: Settings, Options Page
  • Xml and Html: Context Action
  • ZenCoding: Action, Options Page

The third set of examples involves the Psi language plugin contained in the PsiPlugin and PsiPluginTest folders. This set of examples illustrate the concepts used in developing support for new languages for ReSharper. Further details are outlined in the following section.

Tools

The SDK comes with extensive infrastructure and samples for developing support for new languages. The Toolsfolder of the SDK contains several tools which can be used for new language development, including:

  • CsLex --- a tool for creating lexical analysers for different languages.
  • Java --- contains IKVM infrastructure which permits the running of the Java-based parser generator.
  • MSBuild --- contains build tasks that can be used to automate lexer and parser construction.
  • parserGen --- a tool for creating ReSharper-compatible parsers.

In addition to the tools, the SDK also comes with a full language plugin example located in the Samples\PsiPluginfolder. This sample is a full implementation of a language plugin for supporting PSI files, which are parser definition files used by parserGen. As a result, plugin developers interested in using parserGen for new language development are advised to compile and install PsiPlugin, which can greatly simplify the process of working with parser definition files.

Manually Creating/Porting Existing Projects

In some cases, you might not want to use a project template – for example, if you already have a plug-in project for ReSharper 5 and you want it to convert it to ReSharper 6 or 7. In this case, the first thing you need to do is remove all existing references to ReSharper assemblies. Then, simply unload the project and edit it manually. Add the following lines to the end of the project file:

  • For a plug-in project, add the following line:
  • For a plug-in test project, add the following line:
    Reload the project for the targets to take affect.

In case you’re wondering why the MSBuild instructions are so convoluted, this is done in order to make the SDK work well with continuous integration servers. See the Continuous Integration section for more information.

Note: the above .Targets files do not reference every single assembly that is shipped with the SDK. References to some assemblies, such as DevExpress 7.1, are omitted. If you really need these references in your project, simply edit the project file and use the ReSharperSdkBinaries variable to reference the required assemblies. This variable is defined in the original SDK .Target files.

Important note: it is highly recommended that you remove all existing project references to ReSharper before adding one of these targets file. Visual Studio is very sensitive to duplicated references and is likely to freeze if those occur.

Debugging Your Project

To debug your project, simply set Visual Studio (devenv.exe) as the debug target. In the parameter string, you will need to specify the key /ReSharper.Plugin "full_path_to_your_plugin", providing the full path to the location of your plug-in (if you have several plug-ins, you can specify a folder here instead).

Testing Your Project

ReSharper contains project templates to create test projects. Test projects differ from plug-in projects in that they reference a different target file, which in turn references the assemblies related to ReSharper’s test infrastructure.

ReSharper’s tests follow a ‘convention over configuration’ approach. The following assumptions are made:

  • Test data is kept in a folder relative to the folder where the compiled test assembly resides. This location can be specified individually in different fixtures, but the default assumption is that, if the solution files (i.e., the.sln file itself as well as the corresponding projects) are kept in an \src folder, then the test data files are kept in a nearby \test folder.
  • Tests which require the ‘before’ and ‘after’ states are always named such that, if the initial state is namedSomeName.cs, the final expected state is always named SomeName.gold.

Test files also support control identifiers. For example, to indicate the placement of the caret, one can use the {caret} indentifier right in the input/gold files.

Important note: in order for tests to run, the version of the SDK must be strictly less than the version of ReSharper that you have installed. This is a technical limitation that will be overcome in future versions of the SDK.

Continuous Integration

Installation of the ReSharper SDK is not required in order to build a ReSharper plug-in. In fact, what you can do is simply keep the ReSharper SDK binaries and target files in the same folder (or nearby) folder as your plug-in in the source control system. Then, all you have to do at compilation time is set the ReSharperSdkTargets andReSharperSdk properties to point to the location of the .Targets files.

Where to Get Help

If you are interested in learning more about plug-in development, the first place you should check out is the ReSharper 7 Plugin Development area. This area covers a large number of topics.

In addition, you might want to look at the in-depth sample projects that have been written for ReSharper. To do that, take a look at either the projects in the Samples folder, or some of the publicly available ReSharper Plugins (most of them are open-source).

Finally, if you have a problem, don’t hesitate to contact us – we are always happy to help! You can write a comment under one of the Confluence pages, write an SDK-related feature requires in our YouTrack tracker, tweet us @jetbrains or leave a message at the ReSharper Discussion Forums. The choice is yours!