RossWright.MetalNexus.Server 1.0.0-alpha6.6

MetalNexus

by Ross Wright

Copyright 2023 Pross Co. All Rights Reserved.

Description

MetalNexus makes it as simple as posible to have MediatR requests sent within a Blazor Client handled by request handlers on an ASP.NET server via automatically generated API endpoints that can also be used by other API clients and are documented using Open API.

Licensing

To use this library you must attain and embed a license file from RossWright.com. Simply include the file in a project with Build Action to Embedded Resource.

Project setup

The recommended pattern to use MetalNexus is to create a shared project referenced by both your server and blazor client project with a reference to RossWright.MetalNexus.Abstractions (to get reference to the attributes) and define your Request and Response objects there.

Define your requests with the ApiRequest attribute that has the following optional parameters:

• protocol - values are:
  • Auto - defaults to HttpProtocol.Auto which will pick a protocol and request transmission method that best fits the request.
  • Get - uses the HTTP GET Verb and serialize the request as query parameters on the URL.
  • PostViaBody - uses the HTTP POST Verb and serialize the request as json in the request body.
  • PostViaQuery - Should almost never be used, but uses the HTTP POST Verb and serialize the request as query parameters on the URL.
  • PutViaBody - uses the HTTP PUT Verb and serialize the request as json in the request body.
  • PutViaQuery - Should almost never be used, but uses the HTTP PUT Verb and serialize the request as query parameters on the URL.
  • PatchViaBody - uses the HTTP PATCH Verb and serialize the request as json in the request body.
  • PatchViaQuery - Should almost never be used, but uses the HTTP PATCH Verb and serialize the request as query parameters on the URL.
  • Delete - uses the HTTP DELETE Verb and serialize the request as query parameters on the URL. Note serializing the request as query parameters limits the allowable complexity of the Request object considerably.
• path - the full path of the API Endpoint on the server. Such as /api/vc1/Controller/Action
• swaggerTag - the tag used for grouping in the generated swagger document. In normal ASP.NET this would be the controller name
• httpClientName - the HttpClient connection name to be used on the client for this API. This is to support defining endpoints across different servers without having to manage what server an endpoint is found on at the time of invocation.

The Anonymous and Authenticated attributes are also provided on MetalNexus Requests for use with MetalGuardian for Authentication and Authorization.

It is also recommended to derive a class from MetalNexusConfiguration or DefaultMetalNexusConfiguration in the shared project and use this class for both the AddMetalNexusClient and AddMetalNexusServer calls to ensure both the client and server shape the API paths and protocols the same way.

Client Setup

Reference the RossWright.MetalNexus package in your project and in your program.cs call builder.Services.AddMetalNexusClient() There are many overloads to provide or configure a configuration object to specify what assemblies will be scanned for [ApiRequest] attributes.

To invoke a request on the client, simply send the request through MediatR like any other request. It will be marshalled to the server and the matching RequestHandler invoked on the server-side.

Server Setup

Reference the RossWright.MetalNexus.Server package in your project and in your program.cs call builder.Services.AddMetalNexusServerServer() before the call to builder.Build. There are many overloads to provide or configure a configuration object to specify what assemblies will be scanned for [ApiRequest] attributes.

Then add app.UseMetalNexusServer() after the builder.Build call but before the app.Run call.

To enable Swagger generation of the MetalNexus endpoints, call UseMetalNexus on the AddSwaggerGen options object. For example: builder.Services.AddSwaggerGen(options => options.UseMetalNexus());

To handle the requests, simply define RequestHandlers for your Requests in your server project and they will be handled via MediatR as normal.