EfCore.Interceptors 1.0.5

EfCore.Interceptors

Библиотека production-ready перехватчиков (interceptors) для Entity Framework Core 10 (.NET 10). Покрывает все 7 типов интерсепторов EF Core типовыми сценариями: аудит, soft delete, доменные события, логирование SQL, детект медленных запросов, query hints, read-only guard, session-init, транзакции, дерево запросов, штамп материализации и разрешение коллизий идентичности.

dotnet add package EfCore.Interceptors   # либо ссылка на проект src/EfCore.Interceptors

Быстрый старт

using EfCore.Interceptors;

optionsBuilder
    .UseSqlServer(connectionString)
    .UseEfInterceptors(s => s
        .WithAuditing(users)                                  // Created*/Updated* колонки
        .WithSoftDeletes(users)                               // DELETE -> UPDATE IsDeleted=1
        .WithDomainEvents(dispatcher)                         // публикация событий после коммита
        .WithSlowQueryWarning(TimeSpan.FromSeconds(2))        // WARN на медленные запросы
        .WithSqlLogging()                                     // лог всех SQL-команд
    );

Регистрация через DI:

services.AddEfInterceptors(s => s.WithAuditing().WithSoftDeletes());
services.AddDbContext<AppDbContext>((sp, options) =>
    options.UseSqlServer(cs).UseEfInterceptorsFrom(sp));

Если интерсептору нужны scoped-зависимости (например, текущий пользователь из IHttpContextAccessor), зарегистрируйте сам интерсептор как Scoped и резолвьте вручную:

services.AddScoped<AuditSaveChangesInterceptor>();
services.AddDbContext<AppDbContext>((sp, options) =>
    options.UseSqlServer(cs).AddInterceptors(sp.GetRequiredService<AuditSaveChangesInterceptor>()));

Состав библиотеки

1. ISaveChangesInterceptor

2. IDbCommandInterceptor

3. IDbConnectionInterceptor

4. IDbTransactionInterceptor

5. IQueryExpressionInterceptor

6. IMaterializationInterceptor

7. IIdentityResolutionInterceptor

9. Хелперы модели (не интерсепторы, но завершают картину)

modelBuilder.ApplySoftDeleteFilters();          // !IsDeleted всем ISoftDeletableEntity
modelBuilder.ApplyTenantFilters(tenantProvider); // TenantId == current всем ITenantEntity

Фильтры сливаются с существующими через AndAlso (анонимный) или добавляются отдельными именованными фильтрами EF 10 (EfCoreInterceptors.SoftDelete / .Tenant) — ничего не затирается.

10. Наблюдаемость (System.Diagnostics.Metrics)

Все метрики публикуются в метре EfCore.Interceptors — подключите MeterListener/OTLP-экспортёр.

Пример чтения метрик в тестах/консоли:

using var listener = new MeterListener();
listener.InstrumentPublished = (instr, l) =>
{
    if (instr.Meter.Name == "EfCore.Interceptors") l.EnableMeasurementEvents(instr);
};
listener.SetMeasurementEventCallback<long>((inst, value, tags, _) => Console.WriteLine($"{inst.Name}: {value}"));
listener.Start();

Контракты сущностей

public interface IAuditableEntity      { DateTimeOffset CreatedAtUtc { get; set; } string? CreatedBy { get; set; } DateTimeOffset UpdatedAtUtc { get; set; } string? UpdatedBy { get; set; } }
public interface ISoftDeletableEntity  { bool IsDeleted { get; set; } DateTimeOffset? DeletedAtUtc { get; set; } string? DeletedBy { get; set; } }
public interface ILoadTimestamped      { DateTime? LoadedAtUtc { get; set; } }

public interface IDomainEvent          { DateTimeOffset OccurredAtUtc { get; } }
public interface IHasDomainEvents      { IReadOnlyList<IDomainEvent> DomainEvents { get; } void AddDomainEvent(IDomainEvent e); void ClearDomainEvents(); }
public interface IDomainEventDispatcher{ void Dispatch(IEnumerable<IDomainEvent> events); Task DispatchAsync(IEnumerable<IDomainEvent> events, CancellationToken ct = default); }
public interface ICurrentUserProvider  { string? UserName { get; } }   // + StaticCurrentUserProvider
public interface ITenantEntity         { string? TenantId { get; set; } }
public interface ITenantProvider       { string? CurrentTenantId { get; } }  // + StaticTenantProvider

Свойства контрактов должны быть замаплены в модели.

Доменные исключения библиотеки: CrossTenantAccessException, MassOperationException, ConcurrencyConflictException, QueryPolicyViolationException, MissingTransactionException, ReadOnlyContextException.

Готовые сущности для маппинга (namespace EfCore.Interceptors.Entities): ChangeLogEntry (аудит-трейл) и OutboxMessage (outbox) — добавьте их в модель:

modelBuilder.Entity<ChangeLogEntry>();
modelBuilder.Entity<OutboxMessage>();

Типовой связкой: soft delete целиком

// 1. Сущность
public class Order : ISoftDeletableEntity, IAuditableEntity { /* ... */ }

// 2. Глобальный фильтр читающей стороны
modelBuilder.Entity<Order>().HasQueryFilter(o => !o.IsDeleted);

// 3. Регистрация пишущей стороны
.UseEfInterceptors(s => s.WithSoftDeletes(users))

Доменные события end-to-end

public class Order : IHasDomainEvents
{
    private readonly List<IDomainEvent> _events = [];
    [NotMapped] public IReadOnlyList<IDomainEvent> DomainEvents => _events;
    public void AddDomainEvent(IDomainEvent e) => _events.Add(e);
    public void ClearDomainEvents() => _events.Clear();

    public void MarkPaid()
    {
        IsPaid = true;
        AddDomainEvent(new OrderPaid(Id, Total));
    }
}

class OrderPaid(int orderId, decimal total) : IDomainEvent
{
    public DateTimeOffset OccurredAtUtc { get; } = DateTimeOffset.UtcNow;
}

API регистрации

На options builder (работает везде, DI не обязателен): UseEfInterceptors(Action<EfInterceptorsSetup>) — fluent: WithAuditing, WithSoftDeletes, WithDomainEvents, WithSqlLogging, WithSlowQueryWarning, WithQueryHints, WithReadOnlyGuard, WithSessionInit, WithConnectionLogging, WithTransactionLogging, WithQueryTreeLogging, WithLoadStamping, WithIdentityResolution(overwriteExisting), WithChangeLog, WithOutbox, WithMultiTenancy(provider), WithMassOperationGuard(...), WithConcurrencyTranslation(), WithSecondLevelCache(ttl), WithNPlusOneDetection(threshold), WithCommandMetrics(meterName), WithTransactionalWrites(), WithDynamicConnectionString(resolver), WithForcedIsolationLevel(level), WithStrictQueryPolicy(...), WithNullMergingIdentityResolution(), WithDeleteGuard(), WithImmutableGuard(), WithSaveChangesMetrics(), WithTransactionMetrics(), WithConnectionMetrics(), WithLongRunningTransactionDetection(threshold), WithCommandTimeout(...) / WithCommandTimeoutByTags(...), WithInitialization(), WithPropertyEncryption(encryptor), WithCommandSourceBlocker(...), WithRawSqlUsageDetection(...), WithVersionCounter(), WithNewestWinsIdentityResolution(), WithMaterializationMetrics(), WithRequiredQueryTags(...) / WithRequireAnyQueryTag(), WithValidation(), WithSlowSaves(threshold), WithConstructorFactories(map), WithConcurrencyRetry(policy, maxRetries), WithCustomValidation(...), WithCommandsPerSaveDiagnostics(n)

• Add(IInterceptor) для своих.

Со стороны модели: modelBuilder.ApplySoftDeleteFilters() и modelBuilder.ApplyTenantFilters(provider).

Через DI: services.AddEfInterceptors(...) + .UseEfInterceptorsFrom(serviceProvider).

Готовый рабочий пример: ASP.NET Core (samples/WebApiSample)

Запуск и проверка вживую:

dotnet run --project samples/WebApiSample
# в другом терминале:
curl -X POST http://localhost:5000/products -H "X-User: alice" \
     -H "Content-Type: application/json" -d '{"name":"Keyboard","price":49.9}'
curl http://localhost:5000/outbox        # процессор уже доставил события (ProcessedAtUtc != null)

Ключевой приём — scoped-интерсепторы для per-request состояния (текущий пользователь из заголовка):

builder.Services.AddHttpContextAccessor();
builder.Services.AddScoped<ICurrentUserProvider, HttpContextCurrentUserProvider>(); // читает X-User
builder.Services.AddScoped<AuditSaveChangesInterceptor>();                          // сам интерсептор тоже scoped

builder.Services.AddDbContext<ProductDbContext>((sp, options) => options
    .UseSqlite(cs)
    .AddInterceptors(sp.GetRequiredService<AuditSaveChangesInterceptor>())   // ← из контейнера
    .UseEfInterceptors(s => s
        .WithSoftDeletes()                              // stateless — можно прямо так
        .WithOutbox()                                   // события -> таблица той же транзакцией
        .WithSlowQueryWarning(TimeSpan.FromMilliseconds(300))
        .WithSqlLogging(sampleRate: 0.25)               // 25% SQL-логов, ошибки — всегда
        .WithCommandMetrics()
        .WithNPlusOneDetection(5)));

// фоновая доставка outbox-сообщений:
builder.Services.AddScoped<IOutboxMessageHandler, ProductCreatedHandler>();
builder.Services.AddOutboxProcessor<ProductDbContext>(pollInterval: TimeSpan.FromSeconds(1));

Эндпоинты демки: GET/POST/DELETE /products, POST /products/{id}/restore (корзина), GET /outbox (очередь и статусы доставки).

Экосистема проекта

MediatR-интеграция (src/EfCore.Interceptors.MediatR)

Мост между доменными событиями и MediatR-пайплайном:

builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssemblyContaining<Program>());
builder.Services.AddMediatRDomainEventDispatcher();   // IDomainEventDispatcher -> IMediator

// обработчики подписываются на обёртку:
public class ProductCreatedHandler
    : INotificationHandler<DomainEventNotification<ProductCreated>>
{
    public Task Handle(DomainEventNotification<ProductCreated> n, CancellationToken ct) { ... }
}

Бенчмарки (benchmarks/EfCore.Interceptors.Benchmarks)

Оверхед полного набора интерсепторов на SaveChanges против чистого контекста:

dotnet run -c Release --project benchmarks/EfCore.Interceptors.Benchmarks --filter *SaveChanges*

CI

.github/workflows/ci.yml: restore → Release-build → tests → dotnet pack → артефакт .nupkg.

Пакет

dotnet pack src/EfCore.Interceptors -c Release -o artifacts
# artifacts/EfCore.Interceptors.<version>.nupkg (+ snupkg), README внутри пакета

Нюансы и рекомендации

• Времена жизни. Интерсепторы регистрируются на каждый DbContext; сами классы stateless и потокобезопасны (кроме документированных буферов доменных событий/outbox, ключуемых по экземпляру контекста). Один экземпляр можно шарить между контекстами — так работает инвалидация кэша (WithSecondLevelCache + общий CachingCommandInterceptor).
• Soft delete не фильтрует чтения. Обязательно добавляйте глобальный query filter; иначе удалённые строки будут видны. IgnoreQueryFilters() также покажет их (удобно для корзины) — а WithStrictQueryPolicy может такие вызовы запрещать.
• Доменные события диспетчеризуются строго после коммита (at-least-once внутри процесса). Хендлер упал — получите InvalidOperationException; данные уже сохранены. Для гарантированной доставки используйте WithOutbox(): события попадают в таблицу в той же транзакции.
• ChangeLog/Outbox требуют замапленных сущностей ChangeLogEntry/OutboxMessage. Дифф пишется по всем свойствам Added/Deleted и по изменённым для Modified.
• Кэш второго уровня — in-memory, на процесс. Включите invalidateOnWrites: true, чтобы записи автоматически чистили кэш, либо зовите Invalidate*() после внешних изменений. Внутри явных транзакций кэш по умолчанию обойдён.
• QueryHints модифицируют текст SQL — тестируйте на целевом провайдере (хинт SQL Server на SQLite даст синтаксическую ошибку; используйте комментарии как в примере).
• ReadOnlyGuard / StrictQueryPolicy — эвристики. Guard смотрит на текст SQL (комментарий со словом DELETE даст ложное срабатывание — передайте свой isWriteCommand); policy проверяет формы запросов при компиляции, т.е. один раз на каждый уникальный shape.
• Шифрование [Encrypted] хранит в колонке шифротекст: поиск по равенству/LIKE по зашифрованным колонкам невозможен (nonce случайный). AesGcmPropertyValueEncryptor — стартовая точка; для продакшена берите envelope-шифрование с внешним KMS. Шифрование выполняется на клиенте.
• ForcedIsolationLevel применяется ко всем транзакциям контекста, включая неявные SaveChanges — оценивайте влияние на блокировки.
• Аудит доверяет ICurrentUserProvider. В веб-приложении реализуйте его поверх IHttpContextAccessor и регистрируйте интерсептор как Scoped.
• Interceptor'ы выполняются синхронно в горячем пути запросов — избегайте тяжёлой работы.

Структура решения

src/EfCore.Interceptors/         # библиотека (net10.0)
  Abstractions/                  # контракты сущностей, маркеры, шифрование
  Entities/                      # ChangeLogEntry, OutboxMessage
  Saving/ Commands/ Connections/ # интерсепторы по типам
  Transactions/ Queries/
  Materialization/ Tracking/
  Observability/                 # метрики и watchdog'и
samples/SampleApp/               # демо всех сценариев (SQLite): dotnet run --project samples/SampleApp
tests/EfCore.Interceptors.Tests/ # xUnit: 70 тестов

Проверка

dotnet build EfCoreInterceptors.sln
dotnet test  tests/EfCore.Interceptors.Tests
dotnet run --project samples/SampleApp     # консольный прогон всех сценариев