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 -
LoggingBehaviorlogs 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 (OperationCanceledExceptionwhile 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 writeAn unhandled exception has occurred while executing the request.at Error level and does not add theerror.typetag to thehttp.server.request.durationmetric. The exception is logged at Debug level, in theTailoredApps.Shared.ExceptionHandlingcategory. 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()andWithValidation<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 byForkForward.Mediator.IMediatorand the other way round - they are different types. After the migration no reference to theMediatRpackage should remain in the application. Mediatoris now also a namespace. Code whose own namespace starts withTailoredApps.Shared.and names the classMediatorof ForkForward.Mediator by its short name stops compiling (CS0118); writeForkForward.Mediator.Mediatorthere.IMediator,ISenderand 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.Mediatorbefore 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.Mediatoris 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 inPaymentGatewayException.InnerException(theStripeException); for a refusal Stripe's message is inPaymentResponse.ResponseObject. - Your own types in
CashbillHttpClient.MakeFormRequest<T>()are no longer supported (NotSupportedException) - read the answer as aJsonElementor 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