WART-Core 5.3.4

dotnet add package WART-Core --version 5.3.4
                    
NuGet\Install-Package WART-Core -Version 5.3.4
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="WART-Core" Version="5.3.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="WART-Core" Version="5.3.4" />
                    
Directory.Packages.props
<PackageReference Include="WART-Core" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add WART-Core --version 5.3.4
                    
#r "nuget: WART-Core, 5.3.4"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#addin nuget:?package=WART-Core&version=5.3.4
                    
Install WART-Core as a Cake Addin
#tool nuget:?package=WART-Core&version=5.3.4
                    
Install WART-Core as a Cake Tool

WART - WebApi Real Time

License: MIT Nuget NuGet Downloads issues - wart stars - wart

<img src="https://github.com/engineering87/WART/blob/develop/wart_logo.jpg" width="300">

WART is a C# .NET library that enables you to extend any Web API controller and forward incoming calls directly to a SignalR hub. This hub then broadcasts notifications containing detailed information about the calls, including both the request and the response. Additionally, WART supports JWT authentication for secure communication with SignalR.

Features

  • Converts REST API calls into SignalR events, enabling real-time communication.
  • Provides controllers (WartController, WartControllerJwt) for automatic SignalR event broadcasting.
  • Supports JWT authentication for SignalR hub connections.
  • Allows API exclusion from event broadcasting with [ExcludeWart] attribute.
  • Enables group-specific event dispatching with [GroupWart("group_name")].
  • Configurable middleware (AddWartMiddleware) for flexible integration.

Installation

You can install the library via the NuGet package manager with the following command:

dotnet add package WART-Core

How it works

WART implements a custom controller which overrides the OnActionExecuting and OnActionExecuted methods to retrieve the request and the response and encapsulates them in a WartEvent object which will be sent via SignalR on the WartHub.

How to use it

To use the WART library, each WebApi controller must extend the WartController controller:

using WART_Core.Controllers;
using WART_Core.Hubs;

[ApiController]
[Route("api/[controller]")]
public class TestController : WartController

each controller must implement the following constructor, for example:

public TestController(IHubContext<WartHub> messageHubContext, 
ILogger<WartController> logger) : base(messageHubContext, logger)
{
}

WART support JWT bearer authentication on SignalR hub, if you want to use JWT authentication use the following controller extension:

using WART_Core.Controllers;
using WART_Core.Hubs;

[ApiController]
[Route("api/[controller]")]
public class TestController : WartControllerJwt

You also need to enable SignalR in the WebAPI solution and map the WartHub. To do this, add the following configurations in the Startup.cs class:

using WART_Core.Middleware;

In the ConfigureServices section add following:

services.AddWartMiddleware();

or by specifying JWT authentication:

services.AddWartMiddleware(hubType:HubType.JwtAuthentication, tokenKey:"password_here");

In the Configure section add the following:

app.UseWartMiddleware();

or by specifying JWT authentication:

app.UseWartMiddleware(HubType.JwtAuthentication);

Alternatively, it is possible to specify a custom hub name:

app.UseWartMiddleware("hubname");

at this point it will be sufficient to connect via SignalR to the WartHub to receive notifications in real time of any call on the controller endpoints. For example:

var hubConnection = new HubConnectionBuilder()
    .WithUrl("http://localhost:52086/warthub")
    .Build();
    
hubConnection.On<string>("Send", (data) =>
{
  // data is the WartEvent JSON
});

or with JWT authentication:

var hubConnection = new HubConnectionBuilder()
    .WithUrl($"http://localhost:51392/warthub", options =>
    {
        options.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.AccessTokenProvider = () => Task.FromResult(GenerateToken());
    })
    .WithAutomaticReconnect()
    .Build();
    
hubConnection.On<string>("Send", (data) =>
{
  // data is the WartEvent JSON
});

In the source code you can find a simple test client and WebApi project.

Excluding APIs from Event Propagation

There might be scenarios where you want to exclude specific APIs from propagating events to connected clients. This can be particularly useful when certain endpoints should not trigger updates, notifications, or other real-time messages through SignalR. To achieve this, you can use a custom filter called ExcludeWartAttribute. By decorating the desired API endpoints with this attribute, you can prevent them from being included in the SignalR event propagation logic, for example:

[HttpGet("{id}")]
[ExcludeWart]
public ActionResult<TestEntity> Get(int id)
{
    var item = Items.FirstOrDefault(x => x.Id == id);
    if (item == null)
    {
        return NotFound();
    }
    return item;
}

SignalR Event Dispatching for Specific Groups

WART enables sending API events to specific groups in SignalR by specifying the group name in the query string. This approach allows for flexible and targeted event broadcasting, ensuring that only the intended group of clients receives the event. By decorating an API method with [GroupWart("group_name")], it is possible to specify the SignalR group name to which the dispatch of specific events for that API is restricted. This ensures that only the clients subscribed to the specified group ("SampleGroupName") will receive the related events, allowing for targeted, group-based communication in a SignalR environment.

[HttpPost]
[GroupWart("SampleGroupName")]
public ActionResult<TestEntity> Post([FromBody] TestEntity entity)
{
    Items.Add(entity);
    return entity;
}

By appending ?WartGroup=group_name to the URL, the library enables dispatching events from individual APIs to a specific SignalR group, identified by group_name. This allows for granular control over which clients receive the event, leveraging SignalR’s built-in group functionality.

NuGet

The library is available on NuGet packetmanager.

https://www.nuget.org/packages/WART-Core/

Contributing

Thank you for considering to help out with the source code! If you'd like to contribute, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base.

Getting started with Git and GitHub

Licensee

WART source code is available under MIT License, see license in the source.

Contact

Please contact at francesco.delre[at]protonmail.com for any details.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.3.4 108 12/11/2024
5.3.3 106 10/10/2024
5.3.2 102 9/8/2024
5.3.1 114 7/16/2024
5.3.0 112 6/17/2024
5.2.0 117 6/2/2024
5.1.0 118 4/25/2024
5.0.0 165 2/10/2024
4.0.0 194 10/16/2023
3.0.0 323 1/23/2023
2.0.0 490 4/10/2021
1.0.3 556 10/9/2020
1.0.2 538 5/24/2020
1.0.1 594 12/20/2019
1.0.0 651 12/15/2019