Цель: написать, протестировать и развернуть простейший плагин для R#, содержащий пользовательские Quick-Fix и Context Action.

План статьи:

1. Настройка среды разработки
2. Пример №1: простейшее расширение-заглушка
3. Установка плагина
4. Отладка, полезные советы
5. Пример №2: модификация кода с помощью R# API
6. Функциональное тестирование плагинов средствами R# API

В ролях:

Visual Studio 2015
ReSharper Ultimate 10

Заинтересовавшихся приглашаю под кат.

1. Настройка среды разработки

Чтобы не мешать работе основного экземпляра Visual Studio, в котором мы будем писать код, лучше всего сразу подготовить отдельную «экосистему» для нашего будущего плагина. Начинаем со скачивания т.н. «checked build» — сборки R# Ultimate с расширенной диагностической информацией, а в остальном — идентичной натуральной.
Также нам понадобится Visual Studio Experimental Instance — в некотором роде «профиль», содержащий все пользовательские настройки от расположения окон до установленных расширений (ага!). Профили изолированы друг от друга именно на уровне настроек, а исполняемые файлы Студии никуда не копируются. Для VS2015 управлять профилями возможно при помощи утилиты CreateExpInstance.exe, но у нас есть способ еще проще. Запускаем скачанный ранее установщик checked build'а, переходим в Options — Experimental Hive и вводим имя нового профиля, который впоследствии будет использоваться для установки разработанного плагина, а умница R# сам этот профиль создаст и установится туда же. Именно так, в каждый профиль возможно установить свой набор расширений, в том числе — свою версию R#, что облегчает тестирование плагинов под несколько версий сразу. Как уже говорилось, профили независимы друг от друга, поэтому ваш рабочий профиль Visual Studio не пострадает.

Для запуска Студии с новым профилем потребуется ярлык вида:

«X:\Microsoft Visual Studio 14.0\Common7\IDE\devenv.exe» /rootSuffix YourHive /ReSharper.Internal

Здесь YourHive — имя ранее созданного профиля, а параметр /ReSharper.Internal запускает R# в режиме разработки, тем самым включив полезные фичи, такие как уведомления о исключениях, сгенерированных внутри плагинов.

2. Пример №1: простейшее расширение-заглушка

R# предлагает различные способы модификации и генерации кода, среди которых Quick-Fix, Context Action, Refactoring и т.д. Как мне показалось, самым простым для реализации является Quick-Fix, поэтому с него мы и начнем. Quick-Fix'ы — это известные любому пользователю R# команды с иконками в виде желтой/красной лампочки во вплывающем по Alt+Enter меню, такие как «Remove unused variable», «Initialize property from constructor» и т.д.:



Итак, открываем наш основной экземпляр студии (не экспериментальный), и создаем новый проект Class Library. Устанавливаем R# SDK:

Install-Package JetBrains.ReSharper.SDK

Разместим в нашем проекте следующий класс:

[QuickFix]
public class SimpleFix : QuickFixBase
{
	public SimpleFix(NotInitializedLocalVariableError error)
	{
	}
	
	protected override Action<ITextControl> ExecutePsiTransaction(ISolution solution, IProgressIndicator progress)
	{
		return null;
	}
	
	public override string Text => "SimpleFix";
	
	public override bool IsAvailable(IUserDataHolder cache)
	{
		return true;
	}
}

Обратите внимание, любой Quick-Fix обязан иметь минимум один подобный конструктор с входным параметром типа SomeError/SomeWarning. Тип параметра и определяет, для какой ошибки в коде Quick-Fix будет доступен в выпадающем меню. Наш Quick-Fix будет доступен в случае использования неинизиализированной локальной переменной:


В R# SDK определено несколько сотен классов ошибок, доступных в пространстве имен JetBrains.ReSharper.Daemon.CSharp.Errors. Классы, соответствующие ошибкам компиляции, имеют в имени постфикс Error, различные некритические улучшения — постфикс Warning. Весь следующий раздел мы будем мучаться с развертыванием нашего Quick-Fix.

3. Установка плагина

Добавим в наш проект еще один класс:

[ZoneMarker]
public class ZoneMarker { }

Зоны — это новая функциональность R# SDK, появившаяся в версии 9.0, и дорабатываемая до сих пор. В том числе, с помощью зоны указывается, для какого продукта из состава R# Platform предназначено разрабатываемое расширение. К счастью, на данный момент нам достаточно ограничиться классом-заглушкой.

Важно: ZoneMarker должен находиться в одном пространстве имен с созданным ранее классом SimpleFix, либо выше.

Следующий нюанс — распространение и установка плагина в R# 9+ производится только через NuGet-пакеты. Для создания правильного пакета, в состав проекта добавим файл с расширением .nuspec и следующим содержимым:

<?xml version="1.0"?>
<package>
	<metadata>
		<id>PaperSource.ReSharper.HelloWorld</id>
		<version>1.0.5</version>
		<authors>You</authors>
		<owners>You</owners>
		<requireLicenseAcceptance>false</requireLicenseAcceptance>
		<description>Не забывайте, что id пакета должен содержать точку!</description>
		<tags>habrahabr.ru</tags>
		<dependencies>
			<dependency id="Wave" version="4.0" />
		</dependencies>
	</metadata>
	<files>
		<file src="bin\Debug\PluginV10.dll" target="dotFiles\" />
		<file src="bin\Debug\PluginV10.pdb" target="dotFiles\" />
	</files>
</package>

Важные моменты:
1. Зависимость от пакета «Wave» обязательна. Wave — новая модель распространения R# Platform, в которую, помимо R#, входят dotPeek, dotTrace и т.п… Не вдаваясь в подробности:

ReSharper 9.0 — Wave 1.0;
ReSharper 9.1 — Wave 2.0;
ReSharper 9.2 — Wave 3.0;
ReSharper 10.0 — Wave 4.0;

Для версий R#, не перечисленных в теге <dependency>, плагин будет отсутствовать в Extention Manager'е — следовательно, недоступен для установки. Чтобы указать несколько версий, необходимо использовать запись вида [A, B), при этом "[" — значит «включительно» и т.д.

2. Имя плагина, указанное в тэге <id>, обязано содержать в себе точку. Вот просто обязано, и всё! Рекомендуемый формат — “Company.Package”.

После установки NuGet.exe открываем Package Manager Console и выполняем команду:

nuget pack «PaperSource.ReSharper.HelloWorld\package.nuspec»

Готовый .nupkg файл появится в папке вашего solution (либо воспользуйтесь параметром -OutputDirectory для создания пакета в нужной вам папке). На предупреждения вида «Issue: Assembly outside lib folder.» можно не обращать внимания. Для установки плагина, в нашем экспериментальном экземпляре Visual Studio идем ReSharper — Options — Extention Manager и указываем путь до папки с .nupkg файлом.

Момент истины: открываем ReSharper — Extention Manager, ищем наш плагин по имени через поиск, устанавливаем. Если всё сделано правильно — SimpleFix будет доступен:


Известные проблемы при установке:

• плагина нет в Extention Manager;
• плагин удается установить, но Quick-Fix не появляется в нужном месте.

В обоих случаях я бы посоветовал начать с проверки .nuspec файла, а затем — с чтения официального руководства по поиску ошибок. Кстати, т.н. installer logs по примерному адресу %LOCALAPPDATA%\JetBrains\Shared\v02\InstallerLogXXX для меня каждый раз оказывались бесполезными. Даже в случае успешной установки в логи пишется масса информации о каких-то выброшенных исключениях, а уж понять, что приводит к ошибке установки — и вовсе затруднительно.

4. Отладка, полезные советы

Для того, чтобы пройтись отладчиком по коду расширения, достаточно через Debug — Attach to Process присоединиться к процессу denenv.exe экспериментального экземпляра.

Любой плагин должен быть установлен через Extension Manager. При внесении правок в код, гарантированным способом развернуть эти изменения является аналогичное обновление/переустановка. Однако, из этого правила существует исключение: если в код не добавлялись новые файлы/классы, и не было изменений точек интеграции со студией (например, не изменялся тип ошибки для уже существующего quick-fix), то переустанавливать плагин необязательно. Достаточно подменить сборку плагина новой версией. R# хранит сборки с плагинами глубоко в своих недрах, и чтобы лишний раз в них не погружаться, стоит использовать MSBuild target, копирующий сборку «куда надо» после компиляции. Для этого в .csproj файле размещаем следующий код:

<PropertyGroup>
	<HostFullIdentifier>ReSharperPlatformVs14YourHive</HostFullIdentifier>
</PropertyGroup>

Тег <HostFullIdentifier> заполняется вручную и имеет следующий формат: {Host}{Visual Studio version}{Visual Studio instance name}. Приведенный в листинге вариант сработает для R# Ultimate, VS 2015 и профиля с названием YourHive. Если указать некорректный HostFullIdentifier, при сборке проекта в Output будут выведены все возможные варианты HostFullIdentifier.

5. Пример №2: модификация кода с помощью R# API

«Что нам всякие заглушки? Реальный код давай, код!» — в этом разделе напишем простой плагин, по-честному читающий и модифицирующий синтасическое дерево кода R#. Хотелось показать вам что-то, не дублирующее функционал R#, при этом как достаточно простое, так и применимое на практике. И вот что удалось придумать. Пусть у нас есть метод, возвращающий тип List, и по каким-то причинам мы хотим быстро заменить в инструкции return значение null на пустую коллекцию, соответствующую сигнатуре метода. Например:


Было:

public List<object> FooText()
{
	return null;
}

Стало:

public List<object> FooText()
{
	return new List<object>();
}

Мы получили частный случай паттерна Null Object. Конечно же, я согласен, что null и пустая коллекция различаются семантически и о плюсах/минусах такого подхода можно было бы поговорить, но это не входит в задачи данной статьи. Поэтому перейдем к технической реализации. Можно заметить, что исходный код корректен (using'и опустим) — с точки зрения компилятора и R# здесь незачем выдавать даже warning. Поэтому рассмотренный выше механизм Quick-Fix нам не подойдет, и мы используем Context Action — намного более гибкое средство, позволяющее назначить пользовательские действия на практически любой участок кода:

[ContextAction(Group = "C#", Name = "Empty Collection Action", Description = "something new")]
public class EmptyCollectionContextAction : ContextActionBase
{
	public ICSharpContextActionDataProvider Provider { get; set; }

	public EmptyCollectionContextAction(ICSharpContextActionDataProvider provider)
	{
		Provider = provider;
	}

	public override string Text { get; } = "Return empty collection";
}

Управление видимостью Context Action осуществляется аналогично Quick-Fix через переопределение метода IsAvailable:

	public override bool IsAvailable(IUserDataHolder cache)
	{
		var method = Provider.GetSelectedElement<IMethodDeclaration>();

		bool insideOfMethod = method != null;

		if (insideOfMethod)
		{
			bool returnsNull = ReturnsNullOrEmpty();

			bool isGenericList = HasCorrectReturnType(method);

			return returnsNull && isGenericList;
		}

		return false;
	}

Определить, что мы находимся внутри метода — достаточно просто (см. код). Далее, нам необходимо определить следующее:

• находимся ли мы на подходящей инструкции return;
• возвращает ли метод подходящий тип;

Проверяем return:

С возвращаемым типом метода сложнее. Проверим, является ли возвращаемый тип — generic List'ом, либо унаследованным от него (для других коллекций принцип тот же):

Есть вариант попроще, но не такой гибкий — сравнить типы по CLR имени:

Наконец, самое вкусное — замена null на new List<Foo>():

Я с умыслом не стал комментировать вышеприведенные листинги, чтобы излить всю боль в одном месте: писать или разбирать код на R# API… непросто. В документации есть пробелы, доступных примеров мало, даже XML-комментарии к коду отсутствуют. Приходится мучаться с каждым разрабатываемым методом и активно использовать отладчик. Подчеркну — отладчик при работе с R# API становится важнейшим инструментом для путешествий по синтаксическому дереву. Cерьезным подспорьем также выступает поиск по ключевым классам в GitHub — какое-то количество образцов кода удается найти.

6. Функциональное тестирование плагинов средствами R# API

Одна из замечательных фич R# API — это возможность неявно развернуть экземпляр R# в памяти, скормить ему кусок текста (применив к тексту тестируемый Quick-Fix или Context Action), а затем сравнить преобразованный текст с ожидаемым. И все это путем написания малого количества кода, сравнимого с написанием простейших юнит-тестов. Кстати, R# использует NUnit. Поехали!

Добавим в состав solution с нашим плагином еще один проект, который будет содержать тесты. Установим пакет JetBrains.ReSharper.SDK.Tests. Для создания минимального работающего примера, необходимо создать следующую структуру файлов в проекте:


Данная структура не является канонической, но проще в развертывании и ближе к традиционной структуре C# solution. Файлы nuget.config и TestEnvironment.cs обязательны:


С приготовлениями закончили, переходим непосредственно к написанию тестов. Классы, содержащие тесты Context Action, необходимо наследовать от CSharpContextActionExecuteTestBase:

[TestFixture]
public class EmptyCollectionContextActionTests : CSharpContextActionExecuteTestBase<EmptyCollectionContextAction>
{
	protected override string ExtraPath => "EmptyCollectionContextActionTests";

	protected override string RelativeTestDataPath => "EmptyCollectionContextActionTests";

	[Test]
	public void Test01()
	{
		DoTestFiles("Test01.cs");
	}
}
	

Файл Test01.cs вы уже видели на скриншоте, это исходный файл с кодом, к которому будет применяться наш Context Action. Test01.cs.gold — своего рода «expected output», ожидаемый код после применения Context Action. Тест считается пройденным, если применив Context Action к Test01.cs, мы получаем Test01.cs.gold.
При написании собственных тестов, необходимо определить значения свойств ExtraPath и RelativeTestDataPath, задав их равными названию папки, содержащей исходный и gold-файл. Нет никакой необходимости компилировать эти файлы, поэтому им необходимо смело выставлять BuildAction: None и добавлять в игнор R#, чтобы избавиться от мнимых сообщений об ошибках. Что касается содержимого исходного и gold-файлов, то для Context Action обязательно указать позицию каретки на момент вызова контекстного действия, делается это с помощью инструкции {caret}:

using System;
using System.Collections.Generic;

namespace N
{
	public class C
	{
		public List<int> FooMethod()
		{
			return {caret}null;
		}
	}
}

Соответствующий gold-файл:

using System;
using System.Collections.Generic;

namespace N
{
	public class C
	{
		public List<int> FooMethod()
		{
			return { caret}new List<int>();
		}
	}
}

Если при выполнении теста (исходный файл + Context Action) != gold-файл, то тест упадет, и в той же папке будет создан tmp-файл, содержащий актуальный результат применения Context Action.

Запускаем тест на выполнение, и… я сразу перейду к списку проблем и способам их решения:

1. Исключение «file does not exist» — самое простое, проверяем структуру папок и соответствующие значения свойств ExtraPath, RelativeTestDataPath;
2. Тест падает с исключением в SetUpFixture — проверяем месторасположение и содержимое файлов nuget.config и TestEnvironment.cs;
3. Исключение «The test output differs from the gold file» — изучаем созданный tmp-файл, запускаем тест с отладчиком;
4. Tmp-файл вместо кода содержит одну строчку «NOT AVAILABLE» — возможно, нет символа каретки {caret} внутри исходного файла, либо Context Action при работе бросил исключение;
5. Самый интересный случай — тест всегда проходит успешно, вне зависимости от содержимого исходного и gold-файлов. При этом падает — если удалить исходный файл. С таким неприятным поведением я сталкивался, когда унаследовал тест для Context Action от ContextActionTestBase и не задал свойство ExtraPath.

На этом все. Полный работоспособный пример доступен на GitHub. Надеюсь, на разработку своего первого плагина у вас теперь уйдет гораздо меньше времени, чем ушло у меня =)