Привет! Я Дмитрий Сипаков, ведущий разработчик в Госсервисах Т-Банка. Расскажу про относительно новую фичу .NET — Interceptors: как они работают вместе со Source Generators и как с их помощью можно избавиться от бойлерплейта без IL-инъекций и сторонней магии.
Задача: автоматизировать шаги в Allure
Разберем кейс. Допустим, мы пишем автотесты и хотим формировать отчет для Allure TestOps. Помимо тестовых методов, в отчет нужно добавлять промежуточные шаги для отладки или передачи дополнительной информации.
Allure TestOps — Test Management System (TMS) для управления тестами приложения. Отчеты по тестам строятся на основании Allure reports. Основные возможности:
управление тест-кейсами;
планирование тестирования;
анализ результатов и отчетов (allure reports);
интеграция с CI/CD;
выявление flaky-тестов.
Если решать задачу в лоб, код выглядит примерно так:
[Fact] public async Task Test() { await Step1(123); } public async Task Step1(int i) { var parameters = new List<Allure.Net.Commons.Parameter>(); parameters.Add(new Allure.Net.Commons.Parameter { name = "defined", value = i.ToString() }); Allure.Net.Commons.ExtendedApi.StartStep("Step1", step => step.parameters = parameters); try { await Task.Yield(); Allure.Net.Commons.ExtendedApi.PassStep(); } catch(Exception) { Allure.Net.Commons.ExtendedApi.FailStep(); throw; } }
На небольшом примере — терпимо. Но если шагов становится много, копировать одинаковый код в каждый метод уже неудобно.
Почему в задаче напрашивается AOP
Иногда приходится многократно повторять один и тот же шаблон: начать шаг, собрать параметры, обработать успех, обработать ошибку. Это классический случай для аспектно-ориентированного программирования.
Аспектно-ориентированное программирование (АОП) — парадигма программирования, основная идея которой — разделение функциональности для улучшения разбиения программы на модули.
Аспект — это модуль, который реализует сквозную функциональность (в нашем примере это логирование шага в отчет), не затрагивая основную логику.
Идея проста: мы хотим повесить на метод атрибут вроде AllureStep, а дальше чтобы код автоматически «оборачивался» в нужное логирование и отправлялся в TestOps.
Посмотрим на пример:
public class AsyncStepsTest { [Fact] public async Task Test() { await Step1(123); } [AllureStep("Step1")] private static async Task Step1([Name("defined")] int i) { await Task.Yield(); } }
В отчете мы хотим увидеть шаг Step1 с параметром defined=123. Пример фрагмента JSON может выглядеть так:
{ "name": "Step1", "status": "passed", //...остальные поля "stage": "finished", "steps": [], "attachments": [], "parameters": [ { "name": "defined", "value": "123", "excluded": false } ], "start": 1771570531445, "stop": 1771570531446 }
Мы хотим, чтобы при компиляции AllureStep оборачивал метод в готовую обертку с логированием шага. Это уже очень похоже на AOP.
Почему IL-инъекции могут быть неудобны
Когда говорим о реализации АОП в разрезе .NET, то можно выделить две библиотеки: AspectInjector и PostSharp, они основаны на подходе IL-инъекций.
IL (Intermediate Language) Injection — низкоуровневая техника внедрения логики программы в скомпилированный IL-код. Мы собираем приложение и после этого в IL внедряется необходимый аспект.
К примеру, в PostSharp есть аспект OnMethodBoundaryAspect, который имеет методы OnEntry и OnExit.
Создаем атрибут аспекта:
[Serializable] public class LogAttribute : OnMethodBoundaryAspect { public override void OnEntry(MethodExecutionArgs args) { Console.WriteLine($"Вход в метод: {args.Method.Name}"); } public override void OnExit(MethodExecutionArgs args) { Console.WriteLine($"Выход из метода: {args.Method.Name}"); } }
Затем навешиваем атрибут на метод:
class Program { [Log] static void DoWork() { Console.WriteLine("Выполняется работа..."); } static void Main(string[] args) { DoWork(); } }
Если скомпилировать проект и открыть сборку через ILSpy, увидим, что вызовы OnEntry и OnExit внедрены в IL. Именно это и называется IL-инъекцией.
Проблема в том, что такой код не виден в исходниках и появляется только после компиляции. Это усложняет сопровождение и диагностику.
Недостатки IL-инъекций:
внедренный код не видно в исходниках, только после компиляции;
стек вызовов может быть искажен;
ReSharper, Roslyn, SonarQube не видят внедренный код и могут пропустить уязвимости или ошибки;
сложность с поддержкой новых версий .NET или с сохранением обратной совместимости;
проблемы с JIT-оптимизациями.
Source Generators решают часть проблем
Чтобы уйти от перечисленных ограничений, в .NET 5 появились Source Generators. В отличие от IL-инъекций, Source Generators создают код на этапе компиляции. После этого сгенерированные файлы можно открыть, отрефакторить и проверить их поведение. Они видны в IDE и доступны всем инструментам анализа кода.
Эта технология стала очень популярной в экосистеме .NET. На ней строят решения не только Microsoft, но и множество независимых разработчиков. Многие проекты уходят от Reflection в сторону Source Generators, что помогает повысить производительность.
В статье я не буду акцентировать внимание на том, как сделать свой Source Generator, сосредоточимся на решении проблемы: как сделать аспект.
Source Generator по-настоящему стала важной фичей, но она имеет один существенный недостаток, который кроется в самом названии: мы не можем менять существующий код.
Разберем на примере, что это значит. У нас есть исходный код:
public class AsyncStepsTest { [Fact] public async Task Test() { await Step1(123); } [AllureStep("Step1")] private static async Task Step1([Name("defined")] int i) { await Task.Yield(); } }
А вот что мог бы сгенерировать Source Generator:
public static async Task Step1([Name("defined")] int i) { var parameters = new List<Allure.Net.Commons.Parameter>(); parameters.Add(new Allure.Net.Commons.Parameter { name = "defined", value = i.ToString() }); Allure.Net.Commons.ExtendedApi.StartStep("Step1", step => step.parameters = parameters); try { await Task.Yield(); Allure.Net.Commons.ExtendedApi.PassStep(); } catch(Exception) { Allure.Net.Commons.ExtendedApi.FailStep(); throw; } }
Логика аспекта сгенерирована, но оригинальный метод остался нетронутым. И дальше возникает ключевой вопрос: как заставить тесты вызывать именно сгенерированный код, а не оригинал?
На первый взгляд может показаться, что поможет partial class. Но это не решает проблему. Метод нельзя просто «перекрыть» через partial так, чтобы компилятор начал подставлять новую реализацию вместо старой. Оригинальный и сгенерированный метод начнут конфликтовать.
Interceptors: недостающий элемент
Получается, что Source Generator не АОП, возвращаться к IL-инъекциям больно. И вот здесь появляются Interceptors. В .NET 8 эта возможность пришла как preview, а в .NET 9 стала полноценной частью платформы.
Идея Interceptors простая: можно указать, какой метод должен быть перехвачен другим методом. В результате компилятор перепишет вызов так, чтобы вместо оригинала вызывался нужный interceptor. Это уже очень похоже на то, что нам нужно.
В .NET 8 фича была доступна в preview, поэтому в проекте нужно было явно включить соответствующий флаг:
<PropertyGroup> <TargetFramework>net8.0</TargetFramework> <ImplicitUsings>enable</ImplicitUsings> <Nullable>enable</Nullable> <IsPackable>false</IsPackable> <Features>InterceptorsPreview</InterceptorsNamespaces> </PropertyGroup>
Дальше нужно создать атрибут перехвата:
[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] sealed class InterceptsLocationAttribute(string filePath, int line, int column) : Attribute { }
Здесь filePath указывает на файл, где расположен перехватываемый метод, а line и column задают его координаты в файле. Затем создается static class с методом-перехватчиком:
static class Interception { [InterceptsLocation(@"C:\ConsoleApp\TestProject\UnitTest1.cs", line: 4, column: 5)] public static void Step1([Name("defined")] int i) { await Task.Yield(); // здесь пишем уже наш аспект } }
При сборке компилятор подставит вызов перехватчика вместо оригинального метода. Но здесь есть важный нюанс: сигнатура interceptor-метода должна полностью совпадать с сигнатурой перехватываемого метода. Кроме того, перехватчик должен находиться в правильном namespace.
Если изменить оригинальный файл, например добавить отступы, переносы строк или новые строки, координаты могут съехать, и все сломается. Это одна из причин, почему в .NET 9 API был переработан.
В .NET 9 Interceptors вышли из preview, и способ подключения стал удобнее. Теперь в проекте достаточно указать namespace, где находятся методы, которые мы хотим перехватывать:
<PropertyGroup> <TargetFramework>net9.0</TargetFramework> <ImplicitUsings>enable</ImplicitUsings> <Nullable>enable</Nullable> <IsPackable>false</IsPackable> <InterceptorsNamespaces>$(InterceptorsNamespaces);TestProject1</InterceptorsNamespaces> </PropertyGroup>
Теперь нам нужен Source Generator, который будет искать методы с атрибутом AllureStep, определять их местоположение и генерировать перехватчики автоматически.
Как генератор создает атрибут перехвата
Сначала сгенерируем сам атрибут перехватчика:
[global::System.Diagnostics.Conditional("DEBUG")] [global::System.AttributeUsage(global::System.AttributeTargets.Method, AllowMultiple = true)] sealed file class InterceptsLocationAttribute : global::System.Attribute { public InterceptsLocationAttribute(int version, string data) { _ = version; _ = data; } }
Сигнатура упростилась: появились version и data. Не нужно вычислять их вручную — это делает сам генератор. Дальше генератор ищет все вызовы нужного метода в дереве синтаксиса.
private List<InvocationExpressionSyntax> GetInvocationsForMethod( Compilation compilation, IMethodSymbol methodSymbol, CancellationToken ct) { var result = new List<InvocationExpressionSyntax>(); foreach (var tree in compilation.SyntaxTrees) { var model = compilation.GetSemanticModel(tree); foreach (var node in tree.GetRoot(ct).DescendantNodes()) { if (node is InvocationExpressionSyntax invocation) { var invokedSymbol = model.GetSymbolInfo(invocation, ct).Symbol as IMethodSymbol; if (invokedSymbol != null && SymbolEqualityComparer.Default.Equals(invokedSymbol, methodSymbol)) { result.Add(invocation); } } } } return result; }
Из Compilation мы получаем все места вызова метода. Затем берем список invocation-выражений и строим обертку:
var invocationExpressions = GetInvocationsForMethod(compilation, method, context.CancellationToken); var model = compilation.GetSemanticModel(methodSyntax.SyntaxTree); foreach (var invocation in invocationExpressions) { // Получаем позицию вызова var location = model.GetInterceptableLocation(invocation); if (location != null) { var wrapped = WrapMethod(methodSyntax, method, location.Version, location.Data); methodsBuilder.AppendLine(wrapped); } }
Метод GetInterceptableLocation возвращает полную информацию о месте вызова, включая Data и Version. Именно эти значения и используются в атрибуте перехвата. Если вызов не может быть перехвачен, метод вернет null, поэтому проверка обязательна.
Внутри WrapMethod добавляем атрибут к сгенерированному методу:
return $@" {attributes} [System.Runtime.CompilerServices.InterceptsLocation({version}, ""{locationData}"")] public static {returnType} {method.Identifier.Text}({classSignatureOriginal}{methodParameters}) {{ {newBody} }}";
Метод-перехватчик должен полностью повторять сигнатуру оригинального метода, поэтому мы сохраняем все параметры и передаем их в генератор.
Что получилось в итоге и ограничения подхода
Исходный код:
public class AsyncStepsTest { [Fact] public async Task Test() { await Step1(123); } [AllureStep("Step1")] private static async Task Step1([Name("defined")] int i) { await Task.Yield(); } }
Сгенерированный код:
namespace System.Runtime.CompilerServices { [global::System.Diagnostics.Conditional("DEBUG")] [global::System.AttributeUsage(global::System.AttributeTargets.Method, AllowMultiple = true)] sealed file class InterceptsLocationAttribute : global::System.Attribute { public InterceptsLocationAttribute(int version, string data) { _ = version; _ = data; } } } namespace TestProject1 { public static class AsyncStepsTestGenerated { [AllureStep("Step1")] [System.Runtime.CompilerServices.InterceptsLocation(1, "E8F6MzL5PEiXqlbd94aMNh0BAABVbml0VGVzdDEuY3M=")] public static async Task Step1([Name("defined")] int i) { var parameters = new List<Allure.Net.Commons.Parameter>(); parameters.Add(new Allure.Net.Commons.Parameter { name = "defined", value = i.ToString() }); Allure.Net.Commons.ExtendedApi.StartStep("Step1", step => step.parameters = parameters); try { await Task.Yield(); Allure.Net.Commons.ExtendedApi.PassStep(); } catch(Exception) { Allure.Net.Commons.ExtendedApi.FailStep(); throw; } } } }
После запуска тестов в allure-results мы увидим шаг Step1 с параметрами. Из примеров видно, что в атрибуте InterceptsLocationAttribute мы указываем AllowMultiple = true — это нужно для множественных перехватов, если у вас Step1 вызывается в нескольких местах.
Если посмотреть на результат через ILSpy, будет видно, что сгенерированный код почти не изменился, а вот в оригинальном классе вызов был подменен:
public static class AsyncStepsTestGenerated { [AllureStep("Step1")] [<AsyncStepsTest_AllureGenerated>F6685BD4543E2AFCFA3025AAB3D6BC3426E6F4A6FDC825606995182F7112E28E8__InterceptsLocation(1, "E8F6MzL5PEiXqlbd94aMNh0BAABVbml0VGVzdDEuY3M=")] public static async Task Step1([Name("defined")] int i) { List<Parameter> parameters = new List<Parameter>(); parameters.Add(new Parameter { name = "defined", value = i.ToString() }); ExtendedApi.StartStep("Step1", delegate(StepResult step) { step.parameters = parameters; }); try { await Task.Yield(); ExtendedApi.PassStep(); } catch (Exception) { ExtendedApi.FailStep(); throw; } } }
public class UnitTest1 { public class AsyncStepsTest { [Fact] public async Task Test() { await AsyncStepsTestGenerated.Step1(123); } [AllureStep("Step1")] private static async Task Step1([Name("defined")] int i) { await Task.Yield(); } } }
То есть компилятор подставляет перехватчик в Test, а не вызывает оригинальный метод напрямую. Это возможно потому, что класс с перехватчиками должен быть static.
Ограничения подхода:
Можно перехватывать только код, который виден на этапе компиляции. Методы из зависимых библиотек таким способом не перехватить, потому что это все еще генерация кода, а не runtime-подмена.
Если метод вообще не вызывается внутри проекта, он не будет перехвачен.
Например, такой код не сработает, и шаги не попадут в отчет:
public class UnitTest1 { public class AsyncStepsTest { [Fact] [Allure("Step1")] public async Task Test() { await Task.Yield(); } [Fact] [AllureStep("Step2")] public async Task Test2() { await Task.Yield(); } } }
Итоги
Несмотря на ограничения, Interceptors оказались для меня очень полезными. Они позволяют реализовать аспектное поведение без IL-инъекций, без сторонних runtime-хаков и без потери контроля над кодом.
Source Generators отвечают за генерацию логики, а Interceptors — за перенаправление вызова. Вместе они дают именно тот уровень гибкости, который нужен для аккуратной автоматизации шагов в отчетах.
Надеюсь, статья была полезной и помогла лучше понять, как Interceptors и Source Generators решают задачу, которую раньше приходилось закрывать через IL-инъекции.