Skip to content

Upgrading to 3.0 (test phase)

Test phase

The 3.0 line is released as pre-releases (3.0.0-preview.N). The API may still change before 3.0.0. Production applications stay on 2.1.x (branch release/2.1, fixes) until 3.0 leaves the test phase.

This page collects what has to be done in application code when moving from 2.x to 3.0.


What changes

The mediator libraries no longer depend on the MediatR package and use ForkForward.Mediator - a community fork of MediatR 12.5.0, the last version under the Apache-2.0 licence (MediatR is commercially licensed from version 13). The fork has the same types, members and behaviour, but its own namespace and assembly: ForkForward.Mediator instead of MediatR.

The mediator libraries are renamed

With the MediatR package gone, the libraries drop its name as well. The packages, the assemblies and the namespaces change together:

2.x 3.0
TailoredApps.Shared.MediatR TailoredApps.Shared.Mediator
TailoredApps.Shared.MediatR.Caching TailoredApps.Shared.Mediator.Caching
TailoredApps.Shared.MediatR.Email TailoredApps.Shared.Mediator.Email
TailoredApps.Shared.MediatR.PagedRequest TailoredApps.Shared.Mediator.PagedRequest
TailoredApps.Shared.MediatR.ML (namespace TailoredApps.Shared.MediatR.ImageClassification) TailoredApps.Shared.Mediator.ML (namespace TailoredApps.Shared.Mediator.ImageClassification)

Every namespace below them follows (TailoredApps.Shared.MediatR.DI → TailoredApps.Shared.Mediator.DI and so on). Types, members and configuration keys keep their names.

The old package ids stay on nuget.org with their 2.x versions and get no 3.0 release. The pre-releases 3.0.0-preview.1 and 3.0.0-preview.2 were still published under the old names.

The libraries depend on ForkForward.Mediator 13: line 13 is published for net10.0 and net11.0 only (as these libraries are), its net11.0 asset is compiled with runtime async and it works in applications published with NativeAOT. Application code sees no difference from 12.x; an application that references ForkForward.Mediator itself raises it to 13.

Stripe reports gateway errors the way the other providers do

In 2.x the Stripe provider let every API error through as the StripeException of the Stripe.net SDK. From 3.0 it follows the same rules as the other eight providers:

Situation 2.x 3.0
RegisterPayment: Stripe could not handle the call (5xx, 408, 429, no answer) StripeException PaymentGatewayException (an HttpRequestException), with the StripeException as InnerException
RegisterPayment: Stripe refused it (4xx - invalid parameters, a payment method not enabled, a wrong key) StripeException PaymentStatus = Rejected, Stripe's message in ResponseObject
GetStatus: any error, a 404 included StripeException PaymentGatewayException

An application that already catches HttpRequestException around RegisterPayment and GetStatus (recommended since 2.0) now handles Stripe with the same block. Stripe webhook handling does not change.

Refused requests are no longer logged as errors

  • Mediator - LoggingBehavior logs a request refused by validation (ValidationException) at Information level: Request GetProduct rejected by validation …; invalid: Id, with the property names only (validation messages can quote the values the client sent). A request cancelled by its caller (OperationCanceledException while the request's token is cancelled) is Information too. Every other handler exception is Error, as before.
  • ExceptionHandling - ConfigureExceptionHandler() no longer treats an exception the provider answers with a 4xx status as an error: the middleware does not write An unhandled exception has occurred while executing the request. at Error level and does not add the error.type tag to the http.server.request.duration metric. The exception is logged at Debug level, in the TailoredApps.Shared.ExceptionHandling category. 5xx answers do not change.

Before, one validation failure produced two Error entries with stack traces.

Removed obsolete members

The members marked [Obsolete] in 2.x are gone. The 2.x compiler warned about every use of them (CS0618).

Removed Use instead After the upgrade, unchanged code
IDateTimeProvider.UtcTimeOfDaty, DateTimeProvider.UtcTimeOfDaty (typo) UtcTimeOfDay Compile error (CS1061)
FilterCollection.AddExceptionHAndlingFilterAttribute() (typo) AddExceptionHandlingFilterAttribute() Compile error (CS1061)
PayNowServiceOptions.ApiUrl, the Payments:Providers:PayNow:ApiUrl key ServiceUrl Code: compile error. Configuration: the host does not start, with 'Payments:Providers:PayNow:ApiUrl' is no longer read (removed in 3.0): rename it to 'ServiceUrl'.
TpayServiceOptions.ApiUrl, the Payments:Providers:Tpay:ApiUrl key ServiceUrl as above, for Tpay

The old configuration key is detected on purpose: if it were only ignored, a sandbox setup (ApiUrl holding the sandbox address) would, after the upgrade, silently connect to the production default of ServiceUrl.

New packages for minimal APIs

Two new packages of their own - they change nothing in the existing ones and nothing has to be migrated:

  • ExceptionHandling.MinimalApi - WithExceptionHandling() and WithValidation<TRequest>() as endpoint filters, with the same error model as the middleware and the MVC filter; NativeAOT-compatible.
  • EntityFramework.UnitOfWork.MinimalApi - WithUnitOfWorkTransaction(): commit after a success, rollback after an exception or a result with a status ≥ 400, the rules of the MVC filter.

Trimming and NativeAOT

DateTime, Querying, Email, Email.Models, ExceptionHandling, WebApi, Payments and the eight HTTP providers (all but Stripe) declare in 3.0 that they are safe for trimming and NativeAOT (in a Web API: with minimal APIs, not controllers): options are bound by code generated at compile time and the gateways' JSON is serialized through generated metadata. Nothing changes for an application - request bodies and signatures are identical. Details and the list of libraries: Trimming and NativeAOT.

The same goes for Mediator, Mediator.Caching, Mediator.Email and Mediator.PagedRequest (on ForkForward.Mediator 13). An ordinary application changes nothing: scanning and RegisterPipelineBehaviors() work as before. An application that is trimmed or published with NativeAOT registers handlers, behaviors and policies by name with the new methods of PipelineRegistration (AddPipelineBehaviors<,>(), AddCachePolicy<,,>(), AddFallbackHandler<,,>(), AddRetryPolicy<,,>(), AddCacheSerialization(...)) - see Mediator: Trimming and NativeAOT. RegisterPipelineBehaviors(assembly) now carries RequiresUnreferencedCode / RequiresDynamicCode: a project with the trimming analyzers on gets an IL2026 / IL3050 warning at the call.

One behaviour change: CashbillHttpClient.MakeFormRequest<T>() reads answers only as types the library has JSON metadata for - the CashBill models (Payment, PaymentStatus, List<PaymentChannels>) and built-in types. For a type of your own it throws NotSupportedException before the request is sent.

Apart from that, the libraries have no change in 3.0 that requires code modifications.


Checklist

# What to do If skipped
1 Remove the MediatR package (and MediatR.Contracts) from the application and add ForkForward.Mediator - or rely on the transitive dependency of TailoredApps.Shared.Mediator Two different sets of IRequest / IRequestHandler types; handlers are not found
2 Replace using MediatR; with using ForkForward.Mediator; (also MediatR.Pipeline → ForkForward.Mediator.Pipeline and so on) Compile errors (CS0246) or type mismatches
3 Replace AddMediatR(...) with AddMediator(...), and MediatRServiceConfiguration with MediatorServiceConfiguration Compile error (CS1061)
4 Replace the package references TailoredApps.Shared.MediatR* with TailoredApps.Shared.Mediator* The old packages stop at 3.0.0-preview.2: the restore fails or quietly keeps the old pre-release
5 Replace using TailoredApps.Shared.MediatR with using TailoredApps.Shared.Mediator (every sub-namespace) Compile error (CS0234)
6 Raise every TailoredApps.Shared.* package to the same 3.0 version Mixing 2.x and 3.0 puts two mediators in one process
7 Stripe: handle an outage with catch (HttpRequestException) and a refusal with PaymentStatus == Rejected; remove catch (StripeException) around RegisterPayment and GetStatus A Stripe outage bypasses the old catch (StripeException) block, and a refusal is no longer an exception and goes unhandled
8 Review alerts and queries that count Error entries or error.type for 4xx answers An alert on "validation errors" stops firing
9 Replace UtcTimeOfDaty with UtcTimeOfDay, AddExceptionHAndlingFilterAttribute with AddExceptionHandlingFilterAttribute, and the ApiUrl key of the PayNow and Tpay configuration with ServiceUrl A compile error, or a host that does not start

Example

// 2.x
using MediatR;
using TailoredApps.Shared.MediatR.DI;

builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

var pipeline = new PipelineRegistration(builder.Services);
pipeline.RegisterPipelineBehaviors();
pipeline.RegisterPipelineBehaviors(typeof(Program).Assembly);

public record GetProduct(int Id) : IRequest<ProductDto>;

public class GetProductHandler : IRequestHandler<GetProduct, ProductDto>
{
    public Task<ProductDto> Handle(GetProduct request, CancellationToken cancellationToken) => /* … */;
}
// 3.0
using ForkForward.Mediator;
using TailoredApps.Shared.Mediator.DI;

builder.Services.AddMediator(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

var pipeline = new PipelineRegistration(builder.Services);     // the TailoredApps registration - the same type and methods
pipeline.RegisterPipelineBehaviors();
pipeline.RegisterPipelineBehaviors(typeof(Program).Assembly);

public record GetProduct(int Id) : IRequest<ProductDto>;

public class GetProductHandler : IRequestHandler<GetProduct, ProductDto>
{
    public Task<ProductDto> Handle(GetProduct request, CancellationToken cancellationToken) => /* … */;
}

Only the using directives and the name of the method that registers the mediator change. IRequest<>, IRequestHandler<,>, IPipelineBehavior<,>, IMediator, ISender, INotification and the other types keep their names and members.

In a large project three replacements across the solution are enough: TailoredApps.Shared.MediatR → TailoredApps.Shared.Mediator (source files and project files), using MediatR → using ForkForward.Mediator and AddMediatR( → AddMediator(.

A working example on ForkForward.Mediator - the whole pipeline (validation, caching, retry, fallback) together with the other libraries - is the demo application.


Things to watch

  • Do not mix the two mediators. A handler that implements MediatR.IRequestHandler<,> is not called by ForkForward.Mediator.IMediator and the other way round - they are different types. After the migration no reference to the MediatR package should remain in the application.
  • Mediator is now also a namespace. Code whose own namespace starts with TailoredApps.Shared. and names the class Mediator of ForkForward.Mediator by its short name stops compiling (CS0118); write ForkForward.Mediator.Mediator there. IMediator, ISender and the other types are not affected, and neither is code in any other namespace.
  • Third-party libraries built on MediatR (your own packages with handlers, for example) have to be rebuilt on ForkForward.Mediator before they work with 3.0.
  • The behaviour is that of MediatR 12.5.0 - the order of behaviours, notification publishing and registration from an assembly work the same way.
  • ForkForward.Mediator is a young package. That is why 3.0 is in a test phase: try it in one application before moving the others.
  • The details of a Stripe error (StripeError.Code, Type) are still there: for an outage in PaymentGatewayException.InnerException (the StripeException); for a refusal Stripe's message is in PaymentResponse.ResponseObject.
  • Your own types in CashbillHttpClient.MakeFormRequest<T>() are no longer supported (NotSupportedException) - read the answer as a JsonElement or use an HTTP client of your own.
  • An exception the provider answers with a 4xx no longer shows in the log at Error level. If the application maps exceptions that are really server errors to 4xx, have the provider give them a 5xx.

The libraries: Mediator. Upgrading from 1.x: Upgrading to 2.0.


🤖 AI Agent Prompt

## Upgrading TailoredApps.Shared.* from 2.x to 3.0 (preview) - instructions for an AI agent

You are upgrading a .NET 10 or .NET 11 application from the TailoredApps.Shared.* 2.x packages to 3.0.0-preview. The changes that need code modifications: the mediator and the new names of its libraries, Stripe error handling and the removed obsolete members.

### Registration
- Raise every TailoredApps.Shared.* package to the same 3.0.0-preview.N version
- Remove references to the MediatR and MediatR.Contracts packages; add ForkForward.Mediator where needed
- Replace the package references TailoredApps.Shared.MediatR, .MediatR.Caching, .MediatR.Email, .MediatR.PagedRequest and .MediatR.ML with TailoredApps.Shared.Mediator, .Mediator.Caching, .Mediator.Email, .Mediator.PagedRequest and .Mediator.ML
- Replace builder.Services.AddMediatR(...) with builder.Services.AddMediator(...)

### What needs code changes
- using TailoredApps.Shared.MediatR... -> using TailoredApps.Shared.Mediator... (every sub-namespace, e.g. .DI, .PipelineBehaviours, .ImageClassification)
- using MediatR; -> using ForkForward.Mediator; (and MediatR.Pipeline -> ForkForward.Mediator.Pipeline and so on)
- MediatRServiceConfiguration -> MediatorServiceConfiguration
- The names and members of IRequest, IRequestHandler, IPipelineBehavior, IMediator, ISender, INotification do not change
- Stripe: replace catch (StripeException) around RegisterPayment/GetStatus with catch (HttpRequestException) (outage) and a check of PaymentStatus == Rejected (refusal)
- Alerts that count Error entries for validation failures stop working: validation is logged at Information level
- UtcTimeOfDaty -> UtcTimeOfDay; AddExceptionHAndlingFilterAttribute -> AddExceptionHandlingFilterAttribute; in appsettings*.json, environment variables and secrets: Payments:Providers:PayNow:ApiUrl and Payments:Providers:Tpay:ApiUrl -> ServiceUrl (the old key stops the host from starting)

### Configuration
- No new configuration keys

### Rules
- After the migration no reference to the MediatR package or namespace may remain in the solution, TailoredApps.Shared.MediatR* included
- Only package ids and namespaces are renamed: do not rename types or members of the TailoredApps libraries
- In code whose namespace starts with TailoredApps.Shared. write ForkForward.Mediator.Mediator for the Mediator class (CS0118 otherwise)
- Do not mix TailoredApps.Shared.* packages of versions 2.x and 3.0 in one application
- 3.0 is a pre-release: do not deploy it to production without an explicit decision of the application owner