Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ServiceComposer/ServiceComposer.AspNetCore/llms.txt

Use this file to discover all available pages before exploring further.

Version 2.0.0 is a significant release that modernises ServiceComposer’s integration with ASP.NET Core. The legacy RunCompositionGateway host API, route-builder extension points, and all v1 composition interfaces have been replaced with first-class ASP.NET Core endpoint routing and a new, consistent handler API. Follow the steps below to bring your application up to date.
Version 2.0.0 removes support for IHandleRequests, IPublishCompositionEvents, ISubscribeToCompositionEvents, IHandleRequestsErrors, and the IInterceptRoutes.Matches method. All of these must be replaced before upgrading.
1

Update target frameworks

Starting with v2.0.0, ServiceComposer.AspNetCore targets only net6.0 and net7.0. Ensure your project targets one of these frameworks before proceeding.
2

Replace RunCompositionGateway with MapCompositionHandlers

The RunCompositionGateway API is deprecated. Replace it with explicit ASP.NET Core endpoint configuration using UseRouting and UseEndpoints:
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    app.UseRouting();
    app.UseEndpoints(builder => builder.MapCompositionHandlers());
}
Extending IRouteBuilder to map custom routes is no longer supported. Use routing attributes on composition handlers instead (see the steps below).
3

Replace IHandleRequests with ICompositionRequestsHandler

The IHandleRequests interface has been replaced by ICompositionRequestsHandler. Implement the new interface and annotate the handler method with an HTTP routing attribute (HttpGet, HttpPost, etc.) in place of the old IInterceptRoutes.Matches method:
public class SampleHandler : ICompositionRequestsHandler
{
    [HttpGet("/sample/{id}")]
    public Task Handle(HttpRequest request)
    {
        return Task.CompletedTask;
    }
}
4

Replace ISubscribeToCompositionEvents with ICompositionEventsSubscriber

The ISubscribeToCompositionEvents interface has been replaced by ICompositionEventsSubscriber. Implement the new interface and use routing attributes to declare which routes the subscriber participates in:
public class SamplePublisher : ICompositionEventsSubscriber
{
    [HttpGet("/sample/{id}")]
    public void Subscribe(ICompositionEventsPublisher publisher)
    {
        // Use the publisher to subscribe to published events
        publisher.Subscribe<SampleEvent>((evt, httpRequest) =>
        {
            // Handle the event
            return Task.CompletedTask;
        });
    }
}
5

Replace IHandleRequestsErrors with ICompositionErrorsHandler

The IHandleRequestsErrors interface has been replaced by ICompositionErrorsHandler:
public class SampleErrorHandler : ICompositionErrorsHandler
{
    public Task OnRequestError(HttpRequest request, Exception ex)
    {
        return Task.CompletedTask;
    }
}
6

Update ICompositionContext usage

DynamicViewModel no longer implements ICompositionContext. Retrieve the composition context from the current HttpRequest:
var context = request.GetCompositionContext();
To raise an event, use the composition context:
await context.RaiseEvent(new AnEvent());
To access the current request identifier:
var requestId = context.RequestId;
7

Update IViewModelPreviewHandler implementations

In v2.0.0, IViewModelPreviewHandler exposes a single Preview(HttpRequest httpRequest) overload. Ensure any implementation matches this signature:
public class ViewModelPreviewHandler : IViewModelPreviewHandler
{
    public Task Preview(HttpRequest httpRequest)
    {
        return Task.CompletedTask;
    }
}
8

Enable write support (POST, PUT, PATCH, DELETE)

By default, ServiceComposer v2.0.0 responds only to HTTP GET requests. To handle write requests, opt in via configuration:
public void ConfigureServices(IServiceCollection services)
{
    services.AddViewModelComposition(options => options.EnableWriteSupport());
}
In v2.1.0 write support became enabled by default. If you are upgrading directly to v2.1.0 or later, you no longer need to call EnableWriteSupport().
9

Review route matching case sensitivity

When using composition over controllers, route matching is now case insensitive by default. To restore the previous case-sensitive behaviour, configure it explicitly:
public void ConfigureServices(IServiceCollection services)
{
    services.AddViewModelComposition(config =>
    {
        config.EnableCompositionOverControllers(useCaseInsensitiveRouteMatching: false);
    });
}

Build docs developers (and LLMs) love

Get started for freeTalk to us