Forem: Aleksander Parchomenko

Micropackages architecture

Aleksander Parchomenko — Mon, 02 Oct 2023 10:03:16 +0000

Microservices & Monolith

In recent years, microservices architecture has gained immense popularity in the software development world. This approach offers numerous benefits, such as scalability, agility, and ease of maintenance, making it a compelling choice for many organizations. It promotes rapid development, deployment, and scaling of services. However, there are instances where the microservices approach might not be the best fit. As an example, you can read about how and why Amazon has been dumped microservices for video monitoring. But not only Amazon, the below architectural trends figure
indicates, that modular monolith is already on early majority stage in 2023. Hmm, it seems to be a growing trend...

Understanding Micro-Packages

Nevertheless you are transferring your microservices to monolith, designing monolith from scratch or design you system according to microservices pattern, staying agile, efficient, and adaptable is key.

And here I'd like to introduce you micro-packages architecture pattern definition©.

This approach, inspired by microservices, offers a fresh perspective on how to structure and manage code in a modular and scalable way. Micro-packages can be thought of as the smaller building blocks within a software project. These are individual, self-contained pieces of code, each serving a specific function or solving a particular problem. While they share similarities with libraries and modules, micro-packages go a step further by emphasizing extreme modularity, minimalism, and a focus on doing one thing exceptionally well.

Benefits of Micro-Packages Architecture

modularity: micro-packages promote a highly modular approach to code organization. Developers can easily pick and choose the specific functionalities they need, reducing code bloat and improving maintainability.
scalability: by breaking down a project into a collection of micro-packages, it becomes easier to scale and evolve individual components independently. This means faster development and deployment cycles for specific features or improvements.
reusability: micro-packages are designed to be reusable across projects. When you create a micro-package to solve a particular problem, it can be shared across different applications, saving time and effort.
version control: managing dependencies and updates becomes simpler with micro-packages. Each micro-package can have its version control, allowing for fine-grained control over updates and backward compatibility.
collaboration: teams can collaborate more efficiently as micro-packages facilitate better code isolation and clearer interfaces. This also makes it easier to onboard new team members.
testing and maintenance: smaller, focused codebases are easier to test and maintain. When issues arise, it's often easier to locate and fix them in a specific micro-package.

Conceptually, the pattern is similar to microservices one, at least one binary package can be treated as a service but a difference is that it can be used in monolith application or reused in another service. Moreover, during package updates (keeping its API unchanged) you can transfer functionality to external services - in another words you can scale your application.

Approach

Let's assume that we designed eShop with a four microservices that communicate with each other via Event Bus and expose API throughout gateway:

The similar effect, of course in very simplification, can be achieved with monolith which is built on four packages (Identity, Catalog, Ordering and Basket). These packages need to expose contracts for communication with each other and approach for communication depends of our needs. If we'll decide to extract for instance, Identity for separate microservice, we only need to update Identity package inside an application that will order its job to new microservice, Event Bus, etc.

Conclusion

Micro-packages architecture is a promising approach for modern software development. It offers a scalable, modular, and efficient way to build and maintain software projects. While it might not be suitable for every use case, it can enhance development speed, code quality, and collaboration in the right contexts. As the software development landscape continues to evolve, micro-packages are a valuable tool for staying agile and adaptable in the face of ever-changing requirements and technologies. It is not only about commonly used utilities, it is about start packaging your organization domain logic and later easily reuse or scale using miscroservices (or scale back to monolith).

Ocelot & files download

Aleksander Parchomenko — Tue, 11 Apr 2023 14:34:04 +0000

Intro

One of the common patterns when you design your microservices based apps is an gateway pattern in opposite on client-to-microservice communication. You can write your own gateway applications or use third party solutions for it. One of the widely used solution in .NET world that Microsoft recommends is Ocelot.

It is convenient and simple solution for creation API gateways.

Problem

During of one the recent projects I've faced and interesting problem for one of the microservices that was responsible for files downloading. For files that size was greater than about 250 MB Ocelot gateway returned HTTP Content-Length Header equals to zero whereas microservice actually returned desired file content. The result of it was an empty downloaded file on client side.
I've found out that it is existing and reported old (dated on Jun 8, 2020) Ocelot issue: 1262.
There is also another very similar issue but solution in comments does not work in my case.

For our application solution of the problem was to override the default HTTP client used in Ocelot. I've done it only for one endpoint that is responsible for file downloading just to keep all the implemented Ocelot logic with caching, logging, etc. for rest of configured API.
To do it I've needed to perform 3 steps:

To find default implementation of Ocelot IHttpRequester. It is a HttpClientHttpRequester
To implement custom IHttpRequester implementation based on HttpClientHttpRequester for contents endpoint (that is responsible for files downloads):

public class HttpRequester : IHttpRequester
{
    private readonly IHttpClientCache _cacheHandlers;
    private readonly IOcelotLogger _logger;
    private readonly IDelegatingHandlerHandlerFactory _factory;
    private readonly IExceptionToErrorMapper _mapper;
    private readonly IHttpClientFactory _httpClientFactory;

    public HttpRequester(IOcelotLoggerFactory loggerFactory,
        IHttpClientCache cacheHandlers,
        IDelegatingHandlerHandlerFactory factory,
        IExceptionToErrorMapper mapper, IHttpClientFactory httpClientFactory)
    {
        _logger = loggerFactory.CreateLogger<HttpClientHttpRequester>();
        _cacheHandlers = cacheHandlers;
        _factory = factory;
        _mapper = mapper;
        _httpClientFactory = httpClientFactory;
    }

    public async Task<Response<HttpResponseMessage>> GetResponse(HttpContext httpContext)
    {
        if (httpContext.Request.Path.ToString().Contains("contents"))
        {
            var client = _httpClientFactory.CreateClient("FilesDownloadClient");
            var request = httpContext.Items.DownstreamRequest();
            var response = await client.SendAsync(request.ToHttpRequestMessage(), HttpCompletionOption.ResponseHeadersRead);
            return new OkResponse<HttpResponseMessage>(response);
        }

        var builder = new HttpClientBuilder(_factory, _cacheHandlers, _logger);
        var downstreamRoute = httpContext.Items.DownstreamRoute();
        var downstreamRequest = httpContext.Items.DownstreamRequest();
        var httpClient = builder.Create(downstreamRoute);

        try
        {
            var response = await httpClient.SendAsync(downstreamRequest.ToHttpRequestMessage(), httpContext.RequestAborted);
            return new OkResponse<HttpResponseMessage>(response);
        }
        catch (Exception exception)
        {
            var error = _mapper.Map(exception);
            return new ErrorResponse<HttpResponseMessage>(error);
        }
        finally
        {
            builder.Save();
        }
    }
}

Register of this custom IHttpRequester implementation and HttpClient factory in gateway DI container before registering Ocelot:

builder.Services.AddHttpClient("FilesDownloadClient", client =>
{
    client.Timeout = TimeSpan.FromMinutes(10);
});
builder.Services.TryAddSingleton<IHttpRequester, HttpRequester>();
builder.Services.AddOcelot(configuration);

Now client can download any files you need through yours Ocelot gateway.

Important thing in IHttpRequester implementation is to have set HttpCompletionOption.ResponseHeadersRead (that means the operation should complete as soon as a response is available without buffering and headers are read. The content is not read yet.) during requesting underlying API:

var response = await client.SendAsync(request.ToHttpRequestMessage(), HttpCompletionOption.ResponseHeadersRead);

You also have to remember that default timeout for HttpClient is 100 seconds and for large files gateway can throw an exception. To change timeout you can use:

builder.Services.AddHttpClient("FilesDownloadClient", client =>
{
    client.Timeout = TimeSpan.FromMinutes(10);
});

VPN on demand and Kerberos SSO in Flutter mobile app

Aleksander Parchomenko — Fri, 18 Nov 2022 08:23:03 +0000

Intro

Recently I have a pleasure to implement mobile app that among others authorizations uses Kerberos SSO. The app is distributed using corporate MDM with VPN connection configured there. Google Flutter framework was used as underlying tech stack for it. We faced known old Flutter issue https://github.com/flutter/flutter/issues/41500 for establishing VPN on demand on iOS when app tries to make a calls to internal corporate API. There a number of suggestions in the issue how to solve the problem, but we've decided to do it in another way.

Solution

It was helpful information on the relatively old apple dev thread https://developer.apple.com/forums/thread/76448 about VPN on demand:

BSD Sockets does not have a connect by name API. If you need to use BSD Sockets for other reasons — for example, you’re porting some cross-platform code — you can do some sneaky stuff to connect by name and then continue using BSD Sockets for the bulk of your I/O.

That was a hint for us to use something like ping call with native part of code that can set up the connection. For web and logged in in Active Directory users we already have logon endpoint that does some checks for AD user in the application and returns JWT token to establish Bearer authorization for the API.

The idea is to use native SWIFT code to make requests to logon endpoint. For the early first request VPN wasn't set and when we've tried to call logon API timeout has been appeared. The solution is empty ping endpoint (or some lightweight healthcheck) just to be called during first application start before logon process: that sets up VPN and only after that use logon and other API calls using Flutter technique that you use in application.

Native code

To call platform-specific code we used platform channels, where the Flutter portion of the app sends messages to its host (the non-Dart portion of the app) over a platform channel, the host listens on the platform channel, and receives the message. It then calls into any number of platform-specific APIs—using the native programming language—and sends a response back to the client, the Flutter portion of the app.
The piece of code for it (lets call it repository - an abstraction layer for any type of data persistence: local or remote via API) which sends a message to the host:

class MaintenanceRepository {
  static const platform = MethodChannel('com.flutter/http');

  MaintenanceRepository();

  Future<int> ping() async {
    try {

      if (!Platform.isIOS) {
        return HttpStatus.ok;
      }

      final response = await platform.invokeMethod('http-get-ping', {"url": "$apiUrl/api/configuration/vpn"});
      return response["statusCode"];
    } on PlatformException catch (_) {
      return HttpStatus.requestTimeout;
    } catch (e, stackTrace) {
      Log.error(e, stackTrace);
      return HttpStatus.requestTimeout;
    }
  }
}

and native part of the code placed in ios/Runner/AppDelegate.swift with callback to the Flutter app:


@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    if #available(iOS 10.0, *) {
      UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate
    }

    let controller : FlutterViewController = window?.rootViewController as! FlutterViewController
         let httpChannel = FlutterMethodChannel(name: "com.flutter/http", binaryMessenger: controller.binaryMessenger)
            httpChannel.setMethodCallHandler({
                (call: FlutterMethodCall, result: @escaping FlutterResult) -> Void in
                // Note: this method is invoked on the UI thread.
                guard call.method == "http-get-ping" else {
                    result(FlutterMethodNotImplemented)
                    return
                }

                let args = call.arguments as! NSDictionary
                let url = args["url"] as? String ?? ""

                if call.method == "http-get-ping" {
                    self.ping(url: url, result: result)
                }
            })

    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

    func ping(url: String, result: @escaping FlutterResult) {
        let session = URLSession.shared
        var request = URLRequest(url: URL(string: url)!)
        request.httpMethod = "GET"
        let task = session.dataTask(with: request) { data, response, error in

            if error != nil {
                result(FlutterError(code: "UNREACHABLE", message: "URL not reachable", details: nil))
                return
            }
            result(["statusCode": (response as? HTTPURLResponse)?.statusCode]);
        }
        task.resume()
    }
}

The above stuff resolves the VPN on demand setup on iOS application written on Flutter.

No application wrapping or MDM SDK has been added to the application in this approach.

.NET 5 Named Pipes

Aleksander Parchomenko — Thu, 13 Jan 2022 15:31:17 +0000

Intro

Named pipes provide interprocess communication between a pipe server and one or more pipe clients. They offer more functionality than anonymous pipes, which provide interprocess communication on a local computer. Named pipes support full duplex communication over a network and multiple server instances, message-based communication, and client impersonation, which enables connecting processes to use their own set of permissions on remote servers.

Use cases

When we can use it?

Desktop applications: for example to notify GUI application from batch service worker (e.g. Windows Service). It is much faster than setup self-hosted API on GUI and request it via HTTP
You can consider use NamedPipes for MVP that can be developed and scaled in a future: you not need to install queues or event stream for asynchronous communication between processes.
Instead of WCF on one machine or over local network for duplex interprocess communication. Since .NET Core and .NET 6 do not offer server-side support for hosting WCF (actually it is recommended to migrate WCF to gRPC or use CoreWCF) NamedPipes can be used for communication.

Code

Lest send command from one app to another. In example below Web API app sends message to console application (It can be any app).
First, in our server (console app) we start PipeServer and setup it for listening for messages:

internal static class Program
{
    static void Main(string[] args)
    {
        var pipeServer = new PipeServer("TestPipe");
        pipeServer.Start();
        pipeServer.MessageReceivedEvent += (sender, args) => ReceiveMessage(sender, args);            
        Console.ReadKey();
    }

    private static void ReceiveMessage(object sender, MessageReceivedEventArgs args)
    {
        var message = JsonSerializer.Deserialize<Note>(args.Message);
        if (message is not null)
        {
            Console.WriteLine(args.Message);
        }
    }
}

And a client application (for simplicity it is done in ApiController):

[ApiController]
[Route("notes")]
public class NotesController : ControllerBase
{
    private readonly IPipeClient _pipeClient;

    public NotesController(IPipeClient pipeClient)
    {
        _pipeClient = pipeClient;
        _pipeClient.Start();            
    }

    [HttpGet]
    public async Task<IEnumerable<Note>> Get()
    {
        var note = new Note { Id = 1, Title = "Title", Value = "Value" };
        await _pipeClient.SendMessage(JsonSerializer.Serialize(note));

        // Do not stop for future messages
        //_pipeClient.Stop();

        return await Task.FromResult(new List<Note> { note });
    }        
}

and IPipeClient is registered in dependency injection container:

services.AddSingleton<IPipeClient>(factory => new PipeClient("TestPipe"));

with TestPipe name. It is important that your server also created with TestPipe name.

Here we simply can send message (or more precisely, command) to another process or thread. This command is serialized on client and deserialized on the server. Pipe client and server here act as transport layer without binding to certain object types - developer is responsible to properly serialize and deserialize messages that defined in contracts assembly that is shared between applications.

How it works

NamedPipeServerStream and NamedPipeClientStream are wrapped in
IPipeServer and IPipeClient that expose methods for sending messages and events fired when messages are received on the PipeServer. Here is the client code:

public class PipeClient : IPipeClient
{
    private readonly NamedPipeClientStream _pipeClient;

    public PipeClient(string serverId)
    {
        _pipeClient = new NamedPipeClientStream(".", serverId, PipeDirection.InOut, PipeOptions.Asynchronous);
    }

    #region ICommunicationClient implementation

    /// <summary>
    /// Starts the client. Connects to the server.
    /// </summary>
    public void Start()
    {
        // 5 minutes
        const int tryConnectTimeout = 5 * 60 * 1000;
        if (!_pipeClient.IsConnected)
        {
            _pipeClient.Connect(tryConnectTimeout);
        }
    }

    /// <summary>
    /// Stops the client. Waits for pipe drain, closes and disposes it.
    /// </summary>
    public void Stop()
    {
        try
        {
            _pipeClient.WaitForPipeDrain();
        }
        finally
        {
            _pipeClient.Close();
            _pipeClient.Dispose();
        }
    }

    /// <summary>
    /// Sends string message to the server
    /// </summary>
    /// <param name="message">Message to be sent</param>
    /// <returns>Async result</returns>
    public Task<TaskResult> SendMessage(string message)
    {
        var taskCompletionSource = new TaskCompletionSource<TaskResult>();

        if (_pipeClient.IsConnected)
        {
            var buffer = Encoding.UTF8.GetBytes(message);
            _pipeClient.BeginWrite(buffer, 0, buffer.Length, asyncResult =>
            {
                try
                {
                    taskCompletionSource.SetResult(EndWriteCallBack(asyncResult));
                }
                catch (Exception ex)
                {
                    taskCompletionSource.SetException(ex);
                }
            }, null);
        }
        else
        {
            throw new IOException("pipe is not connected");
        }

        return taskCompletionSource.Task;
    }

    #endregion

    #region private methods

    /// <summary>
    /// This callback is called when the BeginWrite operation is completed.
    /// It can be called whether the connection is valid or not.
    /// </summary>
    /// <param name="asyncResult">Async Operation result</param>
    /// <returns>Task result</returns>
    private TaskResult EndWriteCallBack(IAsyncResult asyncResult)
    {
        _pipeClient.EndWrite(asyncResult);
        _pipeClient.Flush();

        return new TaskResult { IsSuccess = true };
    }

    #endregion
}

The server code:

public class PipeServer : IPipeServer
{
    private const int MaxNumberOfServerInstances = 10;
    private readonly string _pipeName;
    private readonly SynchronizationContext _synchronizationContext;
    private readonly IDictionary<string, IPipeServer> _servers;

    public PipeServer(string serverName)
    {
        _pipeName = serverName;
        _synchronizationContext = AsyncOperationManager.SynchronizationContext;
        _servers = new ConcurrentDictionary<string, IPipeServer>();
    }

    #region Events

    public event EventHandler<MessageReceivedEventArgs> MessageReceivedEvent;

    public event EventHandler<ClientConnectedEventArgs> ClientConnectedEvent;

    public event EventHandler<ClientDisconnectedEventArgs> ClientDisconnectedEvent;

    #endregion

    #region IPipeServer implementation

    public string ServerId => _pipeName;

    public void Start()
    {
        StartNamedPipeServer();
    }

    public void Stop()
    {
        foreach (var server in _servers.Values)
        {
            try
            {
                UnregisterFromServerEvents(server);
                server.Stop();
            }
            catch (Exception)
            {
                //Logger.Error("Fialed to stop server");
            }
        }

        _servers.Clear();
    }

    #endregion

    #region Private methods

    /// <summary>
    /// Starts a new NamedPipeServerStream that waits for connection
    /// </summary>
    private void StartNamedPipeServer()
    {
        var server = new InternalPipeServer(_pipeName, MaxNumberOfServerInstances);
        _servers[server.Id] = server;

        server.ClientConnectedEvent += ClientConnectedHandler;
        server.ClientDisconnectedEvent += ClientDisconnectedHandler;
        server.MessageReceivedEvent += MessageReceivedHandler;

        server.Start();
    }

    /// <summary>
    /// Stops the server that belongs to the given id
    /// </summary>
    /// <param name="id">Server ID</param>
    private void StopNamedPipeServer(string id)
    {
        UnregisterFromServerEvents(_servers[id]);
        _servers[id].Stop();
        _servers.Remove(id);
    }

    /// <summary>
    /// Unregisters from the given server's events
    /// </summary>
    /// <param name="server">Server</param>
    private void UnregisterFromServerEvents(IPipeServer server)
    {
        server.ClientConnectedEvent -= ClientConnectedHandler;
        server.ClientDisconnectedEvent -= ClientDisconnectedHandler;
        server.MessageReceivedEvent -= MessageReceivedHandler;
    }

    /// <summary>
    /// Fires MessageReceivedEvent in the current thread
    /// </summary>
    /// <param name="eventArgs">Message event Args</param>
    private void OnMessageReceived(MessageReceivedEventArgs eventArgs)
    {
        _synchronizationContext.Post(e => MessageReceivedEvent.SafeInvoke(this, (MessageReceivedEventArgs)e), eventArgs);
    }

    /// <summary>
    /// Fires ClientConnectedEvent in the current thread
    /// </summary>
    /// <param name="eventArgs">Client connected event Args</param>
    private void OnClientConnected(ClientConnectedEventArgs eventArgs)
    {
        _synchronizationContext.Post(e => ClientConnectedEvent.SafeInvoke(this, (ClientConnectedEventArgs)e), eventArgs);
    }

    /// <summary>
    /// Fires ClientDisconnectedEvent in the current thread
    /// </summary>
    /// <param name="eventArgs">Client disconnected event Args</param>
    private void OnClientDisconnected(ClientDisconnectedEventArgs eventArgs)
    {
        _synchronizationContext.Post(e => ClientDisconnectedEvent.SafeInvoke(this, (ClientDisconnectedEventArgs)e), eventArgs);
    }

    /// <summary>
    /// Handles a client connection. Fires the relevant event and prepares for new connection.
    /// </summary>
    /// <param name="sender">Event sender</param>
    /// <param name="eventArgs">Client connected event Args</param>
    private void ClientConnectedHandler(object sender, ClientConnectedEventArgs eventArgs)
    {
        OnClientConnected(eventArgs);

        // Create a additional server as a preparation for new connection
        StartNamedPipeServer();
    }

    /// <summary>
    /// Hanldes a client disconnection. Fires the relevant event ans removes its server from the pool
    /// </summary>
    /// <param name="sender">Event sender</param>
    /// <param name="eventArgs">Client disconnected event Args</param>
    private void ClientDisconnectedHandler(object sender, ClientDisconnectedEventArgs eventArgs)
    {
        OnClientDisconnected(eventArgs);

        StopNamedPipeServer(eventArgs.ClientId);
    }

    /// <summary>
    /// Handles a message that is received from the client. Fires the relevant event.
    /// </summary>
    /// <param name="sender">Event sender</param>
    /// <param name="eventArgs">Message received event Args</param>
    private void MessageReceivedHandler(object sender, MessageReceivedEventArgs eventArgs)
    {
        OnMessageReceived(eventArgs);
    }

    #endregion
}

InternalPipeServer wraps all the staff of reading from buffers, manage thread and propagates events to the PipeServer

Conclusion

Using wrapper for NamedPipes it is easy to develop async communication between different apps. Especially it is useful for desktop apps but also can be considered as asynchronous channel for MVP apps that planned to be cloud-native in future and later can be easy adopted for queues or event streams.

Full code available on GitHub:

alekshura / Compentio.Pipes

.NET 5 Named Pipes interprocess communication library

Compentio.Pipes

Provides interprocess communication between a pipe server and one or more pipe clients.

When can be used

Desktop applications: for example to notify GUI application from batch service worker (e.g. Windows Service). It is much faster than setup self-hosted API on GUI and request it via HTTP
You can consider use NamedPipes for MVP that can be developed and scaled in a future: you not need to install queues or event stream for asynchronous communication between processes.
Instead of WCF on one machine or over local network for duplex interprocess communication. Since .NET Core and .NET 6 do not offer server-side support for hosting WCF (actually it is recommended to migrate WCF to gRPC or use CoreWCF) NamedPipes can be used for communication.

How to use

Just setup pipe cient and server in your apps and send command to server In example below Web API app sends message…

View on GitHub

About “intuitive” programming

Aleksander Parchomenko — Thu, 13 Jan 2022 12:54:29 +0000

Intro

Recently, when my daughter asked me to help her with chemistry homework she gave me Mendeleev periodic table she uses in school. The last heaviest element on it was Oganeson (Og on the picture below) with the nuclear number equals 118. The curiosity of the situation for me was that over 15 years ago, during my PhD thesis preparation the official name Darmstadtium (Ds, for nuclear number equals 110) was in the process of acceptance.

Fig.1 - Mendeleev periodic table

Darmstadtium

One of parts of the my PhD dissertation was the theoretical calculation of the Ds 271 and Ds 269 lifetimes and theoretical description of the Darmstadtium nuclei decay chains: technically, synthesized super-heavy nuclei observed due to the “trace” — it consequently emits α-particles, sometimes neutrons or gamma bean and in the end, two known stable heavy nuclei. Observing a number of alphas (Helium — it is very stable, because it consists of two protons and two neutrons, that are strongly bidden), energies and time differences during alphas, neutrons and gammas registration in cyclotron, one can deduce, that such nucleus (in our case, Ds) has been synthesized and actually we saw the decay of it. That was a months of experimental work of a number of researchers.

Fig.2 - Ds α-decay chain

Our work was theoretical — calculations of parameters of decay: alpha and gamma energies, nuclei half-life and comparison with an experimental ones.

Approach

The way we obtained decay chain was the comparison the probabilities of fall of the nucleus to to its ground state or low energy state with probability of α-decay to the state with the same quantum characteristics. These probabilities also have been tested, compared and parameterized with experimentally measured data.

I’ve decided calculate decay path with use of .NET framework. At that time it was, I think .NET 1.1, maybe .NET 2.0.

From perspective of years of experience of programming starting from .NET Framework 2.0 to .NET 6, Java 16, in an era of Cloud Native architecture and k8s, it was't beautiful code compatible with design patterns or coding standards. It has`t been analysed by Sonar for tech debt, or reviewed during Pull Requests, refactored, it never even was'n versioned! It was written intuitively, just the way I felt the challenge I’ve tried to solve.

And yes, it simply worked, it simply works. The results were very close to the experimental ones. This fact in research often decides that the theory is good candidate to live pretty long period of time.

Presently, looking backward, after taking part in various software projects in different technologies, management culture, terms and requirements similar problem I observe: the thin line between working and beautiful code.

Off cause I like SOLID, clean, tested, “self-documented”, readable, well formatted code. We have powerful tools and processes to achieve this. But often, more and more time developers spend time on “refactoring”, rather than on product quality improvement.

That’s why, in my opinion, “manager” or tech leader with engineering background or at least the person who understanding technical problems and has common language with developers will be a good option.

And do not forget about intuitive coding. At all levels of our experience it is our feeling of the problem! After few weeks our code will need to be refactored! :)

GraphQL vs REST in .NET Core

Aleksander Parchomenko — Thu, 16 Dec 2021 15:20:44 +0000

GraphQL

In 2012 Facebook started GraphQL as an internal project. An idea was to increase the flexibility of client-server communication, especially for data fetching issues in their mobile apps. In 2015 GraphQL had became open source, which resulted in growing GraphQL popularity also in fortune 500 companies:

Expedia Group has moved away from its RESTful API strategy, which was causing hardships for development teams, in favor of a GraphQL approach.

In 2019, Airbnb software engineer Brie Bunge said about 5.8% of all Airbnb traffic involves GraphQL, and she expected that number to reach 10% by the end of last year.

LinkedIn has organized its “economic graph” of relationships between users, using a unified graph to hide complex systems behind a simple GraphQL API. They are leveraging the technology to enable a consistent access experience across online, nearline, and offline environments.

GraphQL vs REST

But is GraphQL an alternative for REST or should be treated as an extension, what are the possible challenges that should be considered when choosing GraphQL?

Design perspective

GraphQL is transport agnostic query language while REST is HTTP based architectural style for API design. Obviously, GraphQL typically served over HTTP, and exposes one endpoint (that often designed to accept POST requests, but it is not a must) while it is an "entrypoint" for GraphQL queries: server returns the data that's queried by the client.
REST API, on the other hand, bases on HTTP and defines a suite of URLs each of which expose a single resource using various HTTP verbs and HTTP error codes in compliance with REST API design standards, for example can be found them here. In other words, it is "bound" to HTTP.
API versioning
From GraphQL best practices:

While there's nothing that prevents a GraphQL service from being versioned just like any other REST API, GraphQL takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema.
When there's limited control over the data that's returned from an API endpoint, any change can be considered a breaking change, and breaking changes require a new version. If adding new features to an API requires a new version, then a tradeoff emerges between releasing often and having many incremental versions versus the understandability and maintainability of the API.

There is API backward compatibility issues "underneath" and a problems for REST and GraphQL are similar - while REST API during development should be kept backward compatible or should be versioned, so GraphQL schema should evolve in the same way: it also has to be backward compatible with a previous schema (Let's imagine, that during developing of new functionality few old fields from new schema have been removed - from a client perspective the issue is the same as when you will remove a fields from a REST API - in both cases client will receive an error in response).

Before you start coding

Do you expect search engines to index your URL (if so, than for these particular issue API REST has to be your choice: search engines do not index POST requests which are often used for sending GraphQL queries).
Do you plan to expose GraphQL endpoint as a data fetch from only one data storage source?
Do you plan design your GraphQL as a Gateway?
Will it be gateway for REST API or gateway for a number of GraphQL services (here you can expect n + 1 problem and it can be a challenge to design DataLoaders on your layers)? You also should consider here how authorization rules, throttling rates or caching timeouts should be handled. Since GraphQL uses only one endpoint REST route-specific rules should be transferred into GraphQL schema rules: you may need to write authorization, throttling or caching logic in a separate layer.
Is GraphQL API is a part of your Mobile and Web application or internal microservice?

Coding

For .NET Web App you can add GraphQL to you app in a few ways: for example, via separate endpoint in your controller, adding your custom GraphQL Middleware or you can use NUGET package GraphQL.Server.Transports.AspNetCore and add GraphQLHttpMiddleware or even Web Sockets Middleware.

Here I'll show an approach with adding GraphQL endpoint via standard Web API controller. First let's add such controller to Web API project:

[ApiController]
[Route("api")]
public class GraphQLController : ControllerBase
{
    private readonly IGraphQLProcessor _graphQLService;

    public GraphQLController(IGraphQLProcessor graphQLService)
    {
        _graphQLService = graphQLService;
    }

    [HttpPost("/graphql")]
    [ApiConventionMethod(typeof(GraphQLApiConventions), nameof(GraphQLApiConventions.Post))]
    public async Task<IActionResult> Post([FromBody] GraphQLRequest request)
    {
        var result = await _graphQLService.ProcessQuery(request);
        if (result.HasError)
        {
            return BadRequest(result);
        }

        if (result.Data is null)
        {
            return NotFound();
        }

        return Ok(result);
    }
}

IGraphQLProcessor is a service responsible for schema execution and exposes one method for processing GraphQL requests: Task<GraphQLResponse> ProcessQuery(GraphQLRequest request):

public async Task<GraphQLResponse> ProcessQuery(GraphQLRequest request)
{
    var result = await _schema.ExecuteAsync(_documentWriter, o =>
    {
        o.Query = request.Query;
        o.Inputs = request.Variables.ToInputs();
        o.OperationName = request.OperationName;
        o.ValidationRules = DocumentValidator.CoreRules;
        o.EnableMetrics = false;
        o.ThrowOnUnhandledException = true;
    });

    var response = JsonSerializer.Deserialize<GraphQLResponse>(result, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
    return response;
}

Similar logic for schema execution you can implement in your own Middleware like in this one.

In the next step, we should define our GraphQL schema. In the case it is used for data fetching and data mutations:

[ExcludeFromCodeCoverage]
public class GraphQLSchema : Schema
{
    public GraphQLSchema(QueryGraphType query, MutationGraphType mutation, IServiceProvider serviceProvider) : base(serviceProvider)
    {
        Query = query;
        Mutation = mutation;
    }
}

QueryGraphType is a schema definition part responsible for fetching data:

[ExcludeFromCodeCoverage]
public class QueryGraphType : ObjectGraphType
{
    public QueryGraphType(INotesService notesService)
    {
        Name = $"{GetType().Name}";

        FieldAsync<NoteGraphType, Note>("note",
            "Gets a note by its id.",
            arguments: new QueryArguments(new QueryArgument<StringGraphType> { Name = "noteId" }),
            resolve: context =>
            {
                var noteId = context.GetArgument<string>("noteId");
                return notesService.GetNote(noteId);
            });

        FieldAsync<ListGraphType<NoteGraphType>, IEnumerable<Note>>("notes", resolve: context => notesService.GetNotes());
    }
}


[ExcludeFromCodeCoverage]
public class NoteGraphType : ObjectGraphType<Note>
{
    public NoteGraphType()
    {
        Name = nameof(Note);
        Field<StringGraphType>("Id");
        Field<LongGraphType>("DocumentId");
        Field<StringGraphType>("Title");
        Field<StringGraphType>("Description");
        Field<DateTimeGraphType>("Timestamp");
    }
}

INotesService here is a business layer for data operations on INotesRepository wich uses MongoDb database. Obviously, that in real cloud native scenarios INotesService can aggregate and route a lot of data sources: REST, GraphQL, Database, etc.

Similar, MutationGraphType defined for notes adding, update and delete as:

[ExcludeFromCodeCoverage]
public class MutationGraphType : ObjectGraphType
{
    public MutationGraphType(INotesService notesService)
    {
        Name = $"{GetType().Name}";
        Description = "Mutation for the entities in the service object graph.";
        this.AuthorizeWith("DefaultPolicy");

        FieldAsync<NoteGraphType, Note>(
            "addNote",
            "Add note to database.",
            new QueryArguments(new QueryArgument<NonNullGraphType<NoteInputGraphType>>{ Name = "note" }),
            context =>
            {
                var note = context.GetArgument<Note>("note");
                return notesService.AddNote(note);
            });

        FieldAsync<NoteGraphType, Note>(
            "updateNote",
            "Update note in database.",
            new QueryArguments(
                new QueryArgument<NonNullGraphType<NoteInputGraphType>> { Name = "note" },
                new QueryArgument<NonNullGraphType<StringGraphType>> { Name = "noteId" }),
            context =>
            {
                var note = context.GetArgument<Note>("note");
                note.Id = context.GetArgument<string>("noteId");
                return notesService.UpdateNote(note);
            });

        Field<StringGraphType>(
            "deleteNote",
            "Delete note from database.",
            new QueryArguments(new QueryArgument<NonNullGraphType<StringGraphType>> { Name = "noteId" }),
            context =>
            {
                var noteId = context.GetArgument<string>("noteId");
                notesService.DeleteNote(noteId);
                return $"The note with noteId: '{noteId}' has been successfully deleted from db.";
            }).AuthorizeWith("AdminPolicy");
    }       
}

[ExcludeFromCodeCoverage]
public sealed class NoteInputGraphType : InputObjectGraphType<Note>
{
    public NoteInputGraphType()
    {
        Name = "NoteInput";
        Field(r => r.Description);
        Field(r => r.Title);
        Field(r => r.DocumentId);
        Field(r => r.Timestamp);
    }
}

In fact, all defined graph types, DocumentWriter, DocumentExecuter should be registered in Web Application Dependency Injection container. I prefer to define GraphQLServicesCollectionExtensions class to have separate configuration for GraphQL stuff:

[ExcludeFromCodeCoverage]
public static class GraphQLServicesCollectionExtensions
{
    public static IServiceCollection ConfigureGraphQL(this IServiceCollection services)
    {
        services.AddTransient<IGraphQLProcessor, GraphQLProcessor>();               

        global::GraphQL.MicrosoftDI.GraphQLBuilderExtensions
            .AddGraphQL(services)
            .AddDocumentExecuter<DocumentExecuter>()
            .AddDocumentWriter<DocumentWriter>()
            .AddValidationRule<AuthorizationValidationRule>()
            .AddDataLoader()
            .AddSelfActivatingSchema<GraphQLSchema>()
            .AddSystemTextJson(options => options.PropertyNameCaseInsensitive = true);

        return services;
    }
}

AddGraphQL().AddSelfActivatingSchema<GraphQLSchema>() registers our schema with all graph types
AddDataLoader() registers DataLoader for batch processing and caching requests for n + 1 issue
services.AddTransient<IGraphQLProcessor, GraphQLProcessor>() reqisters our GraphQLProcessor

Consuming created API

Now we can consume created GraphQL API. In the GitHub Repo same functionality has been added with REST approach and GraphQL endpoint. Also widely used Swagger configured for Web API Endpoints as well as AltairUI added for GraphQL endpoint testing. Naturally, AltairUI it not a must for GraphQL, you can also use Swagger, GraphiQL, or GraphQL Playground.

In a case of AltairUI data fetching looks like:

For mutation in a case of updateNote:

where we send two variables note and noteId

{
  "note": {
  "documentId": 1234,
  "title": "Title for mutation modified",
  "description": "Description for mutation modified",
  "timestamp": "2021-12-13T10:35:14.830Z"
  },
  "noteId": "61b733a7434d2ea2b8a57d50"
}

For this case HTTP request sent by AltairUI looks like:

{
   "query":"mutation ($note: NoteInput!, $noteId: String!){\n  updateNote(note: $note, noteId: $noteId) {\n    title\n    description\n    documentId\n    timestamp\n  }\n}",
   "variables":{
      "note":{
         "documentId":1234,
         "title":"Title for mutation modified",
         "description":"Description for mutation modified",
         "timestamp":"2021-12-13T10:35:14.830Z"
      },
      "noteId":"61b733a7434d2ea2b8a57d50"
   },
   "operationName":null
}

Validation

Naturally, data validation is a one of the base part of Web Application. In GraphQL validation run when a query is executed. There is a predefined list of validation rules that are turned on by default. You can add your own validation rules or clear out the existing ones by setting the ValidationRules property:

var result = await _schema.ExecuteAsync(_documentWriter, o =>
{
    o.Query = request.Query;
    o.Inputs = request.Variables.ToInputs();
    o.OperationName = request.OperationName;
    o.ValidationRules = DocumentValidator.CoreRules.Concat(new[] { new NoteValidationRule() });
    o.EnableMetrics = false;
    o.ThrowOnUnhandledException = true;
});

Let assume, that note's title should be less than 50 characters. ValidationRule implementation can look like:

public class NoteValidationRule : IValidationRule
{
    public async Task<INodeVisitor> ValidateAsync(ValidationContext context)
    {
        return new NodeVisitors(
            new MatchingNodeVisitor<Argument>((arg, context) =>
            {
                ValidateAsync(arg, context, context.TypeInfo.GetArgument());
            })
        );
    }

    private void ValidateAsync(IHaveValue node, ValidationContext context, QueryArgument argument)
    {
        if (argument is null)
            return;

        if (!IsNoteArgument(argument.Name))
            return;

        var note = context.Inputs.FirstOrDefault(x => IsNoteArgument(x.Key)).Value as Dictionary<string, object>;
        var noteTitle = note["title"] as string;

        if (!string.IsNullOrEmpty(noteTitle) && noteTitle.Length > 50)
        {
            context.ReportError(new ValidationError(context.Document.OriginalQuery, "1.0", $"Field 'title' in argument '{argument.Name}' can not be longer than 50", node));
        }
    }
    private static bool IsNoteArgument(string argumentName)
    {
        return argumentName.Equals("note", StringComparison.InvariantCultureIgnoreCase);
    }
}

Authorization

While in example GraphQL endpoint defined in API controller, it uses defined authentication for it.
Authorization in GraphQL based on Validation approach with using of AuthorizationValidationRule.
To add it to the project we need to do:

Install GraphQL.Server.Authorization.AspNetCore package
register your policies, register HttpContextAccessor and IClaimsPrincipalAccessor:

services.AddAuthorization(o => {
                o.AddPolicy("DefaultPolicy", policyBuilder => policyBuilder.RequireAuthenticatedUser());
                o.AddPolicy("AdminPolicy", policyBuilder => policyBuilder.RequireClaim("role", "Admin"));
            });

services.AddHttpContextAccessor().AddTransient<IClaimsPrincipalAccessor, DefaultClaimsPrincipalAccessor>();

global::GraphQL.MicrosoftDI.GraphQLBuilderExtensions
                .AddGraphQL(services)
                .AddDocumentExecuter<DocumentExecuter>()
                .AddDocumentWriter<DocumentWriter>()
                .AddValidationRule<AuthorizationValidationRule>()
                .AddDataLoader()
                .AddSelfActivatingSchema<GraphQLSchema>()
                .AddSystemTextJson(options => options.PropertyNameCaseInsensitive = true);

In GraphQLProcessor inject AuthorizationValidationRule and add it to ValidationRules collection:

public class GraphQLProcessor : IGraphQLProcessor
{
    private readonly ISchema _schema;
    private readonly IDocumentWriter _documentWriter;
    private readonly AuthorizationValidationRule _authorizationRule;

    public GraphQLProcessor(IDocumentWriter documentWriter, ISchema schema,  AuthorizationValidationRule authorizationRule)
    {
        _documentWriter = documentWriter;
        _schema = schema;
        _authorizationRule = authorizationRule;
    }


    public async Task<GraphQLResponse> ProcessQuery(GraphQLRequest request)
    {
        var result = await _schema.ExecuteAsync(_documentWriter, o =>
        {
            o.Query = request.Query;
            o.Inputs = request.Variables.ToInputs();
            o.OperationName = request.OperationName;
            o.ValidationRules = DocumentValidator.CoreRules
                .Concat(new[] { new NoteValidationRule() })
                .Concat(new[] { _authorizationRule });
            o.EnableMetrics = false;
            o.ThrowOnUnhandledException = true;
        });

        var response = JsonSerializer.Deserialize<GraphQLResponse>(result, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
        return response;
    }        
}

Having it configured now we can add authorization for graph objects, for example only Admin has permissions to Note removal, what is achieved by adding .AuthorizeWith("AdminPolicy") to field definition:

Field<StringGraphType>(
    "deleteNote",
    "Delete note from database.",
    new QueryArguments(new QueryArgument<NonNullGraphType<StringGraphType>> { Name = "noteId" }),
    context =>
    {
        var noteId = context.GetArgument<string>("noteId");
        notesService.DeleteNote(noteId);
        return $"The note with noteId: '{noteId}' has been successfully deleted from db.";
    }).AuthorizeWith("AdminPolicy");

Performance comparison

Lets now compare operations for data fetching and mutating for GraphQL and REST.

For notes list and details data fetching GraphQL average time is about 23 ms whereas for corresponding REST GET is about 14 ms. For mutation operations the times for REST and GraphQL are similar. So if a performance is a must for you and data fetching times are about 10 ms than REST should be a choice.

Summary

Obviously, GraphQL is powerful tool for designing API, especially for clients (mobile and web applications or microservices - it perfectly solves over-fetching and under-fetching issues), it has growing community, a number of solutions of known problems of data fetching and updating. However, it should be noted that it does not solve all the problems that arise when designing REST services: the complexity and number of endpoints is transferred to the complexity of the scheme.
Also, the statement that GraphQL is client oriented is a minor abuse: after all, the server defines the schema, and the client can only request a subset of the data defined on the server.

Code example

alekshura / Compentio.Notes.GraphQL

.NET 5 GraphQL Web API application with MongoDB.

Setup local MS SQL docker container

Aleksander Parchomenko — Mon, 13 Dec 2021 14:33:59 +0000

Local database container

One of the organizational tasks for development team is to setup the development environment for all remote developers. Often development teams share data on one development database: due the security policy of the company or due to the complexity of the database.

During cloud native applications implementation very natural and convenient trick for developers is to setup and run database in container on the local machines. It is important also, to have the same database container with the initial snapshot: with schemas, users, data, permissions, etc. Having SQL script for database initialization it can be done creating database initialization container compentio.ankara.database in your docker-compose:

compentio.ankara.database:
    image: mcr.microsoft.com/mssql/server:2017-latest
    container_name: ankara-db
    command: /bin/bash ./entrypoint.sh
    networks:
      - ankara
    volumes:
      - dbdata:/var/opt/mssql/data
      - ./Compentio.Ankara.Database/CreateDatabase/docker-entrypoint.sh:/entrypoint.sh
      - ./Compentio.Ankara.Database/CreateDatabase/docker-db-init.sh:/db-init.sh
      - ./Compentio.Ankara.database/CreateDatabase/ankara-db-init.sql:/ankara-db-init.sql

were docker image entrypoint looks like:

#start SQL Server, start the script to create/setup the DB 
/db-init.sh & /opt/mssql/bin/sqlservr

30s sleep is added to allow SQL Server to start and execute SQL script:

#wait for the SQL Server to come up
sleep 30s

echo "running set up script"
#run the setup script to create the DB and the schema in the DB
/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P sa@Passw0rd -d master -i ankara-db-init.sql

Above, you can see that before starting migrations all the job for creating schema, users, roles does ankara-db-init.sql script:

USE [master]
GO

IF DB_ID('ankara') IS NOT NULL
  set noexec on 

CREATE DATABASE [ankara];
GO

USE [ankara]
GO

SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO

CREATE LOGIN [migrator] WITH PASSWORD = 'migrator123!'
GO

CREATE SCHEMA app
GO

CREATE USER [migrator] FOR LOGIN [migrator] WITH DEFAULT_SCHEMA=[app]
GO

EXEC sp_addrolemember N'db_owner', N'migrator'
GO

CREATE LOGIN [ankaraUser] WITH PASSWORD = 'user123!'
GO

CREATE USER [ankaraUser] FOR LOGIN [ankaraUser] WITH DEFAULT_SCHEMA=[app]
GO

Schema migrations

In this way during Docker container startup we’ve created database, users and default schema. In such scripts, you can perform as much operations as you need. In the next step you can add tables, views to your schema. For this purpose, there are a number of approaches used: starting from pure SQL scripts to database migrations.

In contrast to pure SQL scripting popular are migration projects like Liquibase or FlyWay in Java world or Entity Framework Migrations in .NET. It is convenient to define subsequent database changes in XML, YAML or in code and store it in repository, while the migration framework will keep an eye on execution and versioning of appropriate database changes. Also it is handy during CI/CD process configuration.

Personally I prefer to use FluentMigrator to schema modification data load.

Migration project

First of all, in Visual Studio, let's created a database Cli project (more about creating .NET Core Cli, for example, you can read here):

static void Main(string[] args)
{
    CommandLineApplication commandLineApplication = new CommandLineApplication(throwOnUnexpectedArg: false);
    var previewOption = commandLineApplication.Option(
      "-$|-s |--script <fineName>", "Generate Sql database scripts but do not execute it on the database.", CommandOptionType.SingleValue);
    var unappliedOption = commandLineApplication.Option(
      "-$|-u |--unnaplied", "Generate Sql scripts for unapplied changes in database without executing. ", CommandOptionType.NoValue);

    commandLineApplication.HelpOption("-? | -h | --help");
    commandLineApplication.OnExecute(() =>
    {
        if (previewOption.HasValue())
        {
            PreviewOnly = true;
            PreviewScriptName = previewOption.Value();
        }

        if (unappliedOption.HasValue())
        {
            PreviewOnly = true;
            PreviewUnapplied = true;
            PreviewScriptName = previewOption.HasValue() ? previewOption.Value() : $"UnappliedMigrations_{ DateTime.UtcNow:yyyyMMddHHmm}.sql";
        }

        Run();
        return 0;
    });

    commandLineApplication.Execute(args);
}

Here, command line options are added. These options I going to discuss later.
With these options Run is executed:

private static void Run()
{
    var logger = LogManager.GetCurrentClassLogger();

    var configuration = new ConfigurationBuilder()
        .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
        .AddEnvironmentVariables()
        .Build();

    Configuration = configuration;

    try
    {
        logger.Info($"Start dabase migration. ConnectionString: {configuration.GetConnectionString("Ankara")}");

        var serviceProvider = CreateServices(configuration);
        using var scope = serviceProvider.CreateScope();
        UpdateDatabase(scope.ServiceProvider);

        logger.Info($"Migration sucessfull.");
    }
    catch (Exception exception)
    {
        logger.Error(exception, "Migration stopped because of exception");
        throw;
    }
    finally
    {
        LogManager.Shutdown();
    }
}

all the update logic executed in UpdateDatabase method, which calls FluentMigrator’s runner which performs all migrations’ Up method.
Entire code you can find here.

FluentMigrator extensions

It is convenient in FluentMigrator to extend it default methods according to you project, you can see it in example of FM InitialMigration:

namespace Compentio.Ankara.Database.Migrations
{
    using Compentio.Ankara.Database.Extensions;
    using FluentMigrator;
    using NLog;
    using System;
    using static Compentio.Ankara.Database.Extensions.TableExtensions;

    [Migration(2020_01_01_1000)]
    public class InitialMigration : Migration
    {
        private readonly Logger logger = LogManager.GetCurrentClassLogger();

        public override void Up()
        {
            logger.Info("Start initial migration");

            if (!Schema.AppSchemaExists())
            {
                Create.AppSchema();
            }

            if (!Schema.AppSchema().AppTableExists(TableNames.Cache))
            {
                Create.AppTable(TableNames.Cache)
                    .WithColumn("Id").AsString(449).NotNullable().PrimaryKey()
                    .WithColumn("Value").AsMaxVarBinary().NotNullable()
                    .WithColumn("ExpiresAtTime").AsDateTimeOffset(7).NotNullable()
                    .WithColumn("SlidingExpirationInSeconds").AsInt64().Nullable()
                    .WithColumn("AbsoluteExpiration").AsDateTimeOffset(7).Nullable();
            }

            if (!Schema.AppSchema().AppTableExists(TableNames.Logs))
            {
                Create.AppTable(TableNames.Logs)
                    .WithIdentityColumn()
                    .WithColumn("Severity").AsString()
                    .WithColumn("Message").AsMaxString()
                    .WithColumn("Timestamp").AsDateTime().Indexed()
                    .WithColumn("Logger").AsString()
                    .WithColumn("ExceptionType").AsString().Nullable()
                    .WithColumn("ExceptionMessage").AsMaxString().Nullable()
                    .WithColumn("UserLogin").AsString().Nullable()
                    .WithColumn("SourceName").AsString();
            }

            if (!Schema.AppSchema().AppTableExists(TableNames.Users))
            {
                Create.AppTable(TableNames.Users)
                   .WithIdentityColumn()
                   .WithColumn("UserId").AsInt64().Indexed()
                   .WithColumn("Roles").AsMaxString().WithDefaultValue("")
                   .WithPeriodColumns()
                   .WithActiveColumn()
                   .WithAuditColumns();
            }

            if (!Schema.AppSchema().AppTableExists(TableNames.UsersSession))
            {
                Create.AppTable(TableNames.UsersSession)
                  .WithColumn("SessionKey").AsString(449).NotNullable().PrimaryKey()
                  .WithColumn("SessionId").AsString().NotNullable()
                  .WithColumn("Login").AsString().NotNullable()
                  .WithColumn("UserId").AsInt64().NotNullable().Indexed()
                  .WithColumn("TimeStamp").AsDateTimeOffset(7).NotNullable().WithDefaultValue(DateTimeOffset.UtcNow);
            }


            Execute.AppScript("./Scripts/Example.sql");

            logger.Info("Initial migration completed");
        }

        public override void Down()
        {
            logger.Warn("Initial migration rollback.");

            Delete.AppSchema();

            Delete.Table(TableNames.Logs);
            Delete.Table(TableNames.Users);
            Delete.Table(TableNames.UsersSession);
            Delete.Table(TableNames.Cache);
        }
    }
}

here we've used Create.AppTable extension method, which creates table for defined scheme or .WithIdentityColumn() extension method for identity columns.
All used table extensions, can be found here.

Generate SQL from Migration project

Sometimes one of requirements coming from database administrators or DevOps team is to have SQL scripts for database update. For this purpose database Cli can be used. For generating of unapplied migrations, we can write:

compentio.ankara.database.exe -u | --unnaplied

it will generate SQL script with can be used to update database to its last version.

The trick here, is to configure FluentMigrator only to log generated SQL without execution of migrations, which is shown in code snippet:

private static IServiceProvider CreateServices(IConfiguration configuration)
{
    var connectionString = configuration.GetConnectionString("Ankara");

    return new ServiceCollection()
        .AddFluentMigratorCore()
        .ConfigureRunner(rb => rb
            .AddSqlServer()
            .ConfigureGlobalProcessorOptions(o => o.PreviewOnly = PreviewOnly)
            .WithGlobalConnectionString(connectionString)
            .ScanIn(typeof(InitialMigration).Assembly).For.Migrations())
                .AddLogging(loggingBuilder => {
                    loggingBuilder.ClearProviders();
                    loggingBuilder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Trace);
                    loggingBuilder.AddNLog("NLog.config");
                    loggingBuilder.AddFluentMigratorConsole();
                    if (PreviewOnly)
                    {
                        loggingBuilder.Services.AddSingleton<ILoggerProvider, LogFileFluentMigratorLoggerProvider>();
                        loggingBuilder.Services.Configure<LogFileFluentMigratorLoggerOptions>(
                            opt =>
                            {
                                opt.OutputFileName = PreviewScriptName;
                                opt.OutputGoBetweenStatements = true;
                                opt.ShowSql = true;
                            });
                    };
                })

        .BuildServiceProvider(false);
}

Now with use of created database Cli Admin can control all changes in generated file and manually execute it or use in CI/CD pipeline.

The full code example can be found on Github.

About Azure AD authorization Integration Tests

Aleksander Parchomenko — Mon, 06 Dec 2021 10:09:32 +0000

Introduction

It is obvious thing that during software creation life-cycle the code quality and proper functionality are the must. Besides of coding techniques like code reviews, Merge Requests/Pull Requests, pair programming, etc. various testing approaches are the must also. The QA teams or UAT tests are responsible for it at the end of coding process, but before it, the ones, who responsible for code quality are,
of course, developers.

An outcome of development is a “product” — properly working peace of software and in the era of micro-services, teams can decide about development approaches (Test-Driven-Development, Behavioral-Driven Development, Acceptance Test-Driven Development, etc.).

The “basic unit” for testing code is unit test. Coding techniques have changed during last years to make possible to cover you code (methods in a classes or units of code) by unit tests. Dependency injection and IoC containers is a “standard” (the techniques become more and more similar in .NET and Java ecosystems) while it makes also possible convenient unit testing.
Next step, is interaction testing of software components in a bigger functionality. For example, REST API method that reads data from another REST or asynchronously writes it to some Message Broker or Database. All methods used in this “process” are covered by Unit Tests, but such overall “cooperation” them starting from API entry point are not. And here developers start to write Integration Tests (or Integration Tests are already written, if you use TDD or BDD).
End to End tests (E2E) — are the next degree of your software functional tests and it is very useful if they are automated during CI/CD pipelines execution. But, of course, it depends :).
Load and stress testing that is another type of non functional tests that characterize the quality of you software. While it is not a part of this post let me redirect you here.

And a little bit more about Unit vs Integration vs System vs E2E Testing comparison from MS.

Azure AD authorization integration tests

Here I concentrate on integration tests of Web API example with Azure AD authorization, authentication and how to arrange it in a simple and readable way.

Lets imagine that we have CRUD API controller for some user notes for abstract documents. It is simply a title and description for document that user stores, something like this:

namespace Compentio.Ferragosto.Api.Controllers
{
    using Microsoft.AspNetCore.Authorization;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.Identity.Web.Resource;
    using Compentio.Ferragosto.Notes;
    using System.Collections.Generic;
    using System.Threading.Tasks;
    using System;

    [Authorize]
    [ApiController]
    [ApiConventionType(typeof(DefaultApiConventions))]
    [RequiredScope(RequiredScopesConfigurationKey = "AzureAd:Scopes")]
    [Route("api/notes")]
    public class NotesController : ControllerBase
    {
        private readonly INotesService _notesService;

        public NotesController(INotesService notesService)
        { 
            _notesService = notesService;
        }

        /// <summary>
        /// Returns list of notes
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public async Task<IEnumerable<Note>> Get()
        {
            return await _notesService.GetNotes().ConfigureAwait(false);
        }

        /// <summary>
        /// Returns note by its id
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        [HttpGet("{id}")]
        [ApiConventionMethod(typeof(DefaultApiConventions), nameof(DefaultApiConventions.Get))]
        public async Task<Note> GetNote(string id)
        {
            return await _notesService.GetNote(id).ConfigureAwait(false);
        }

        /// <summary>
        /// Method adds new note
        /// </summary>
        /// <param name="note"></param>
        /// <returns></returns>
        [HttpPost()]
        [ApiConventionMethod(typeof(DefaultApiConventions), nameof(DefaultApiConventions.Post))]
        public async Task<ActionResult<Note>> Add([FromBody] Note note)
        {
            return await _notesService.AddNote(note).ConfigureAwait(false);
        }

        /// <summary>
        /// Method updates the note
        /// </summary>
        /// <param name="id"></param>
        /// <param name="note"></param>
        /// <returns></returns>
        [HttpPut("{id}")]
        [ApiConventionMethod(typeof(DefaultApiConventions), nameof(DefaultApiConventions.Put))]
        public async Task<ActionResult<Note>> Update(string id, [FromBody] Note note)
        {
            var noteToUpdate = await _notesService.GetNote(id).ConfigureAwait(false);
            if (noteToUpdate == null)
            {
                return NotFound();
            }

            var updatedNote = await _notesService.UpdateNote(note).ConfigureAwait(false);
            return Accepted(updatedNote);
        }

        /// <summary>
        /// Method deletes the note
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        [HttpDelete("{id}")]
        [ApiConventionMethod(typeof(DefaultApiConventions), nameof(DefaultApiConventions.Delete))]
        public async Task<IActionResult> Delete(string id)
        {
            await _notesService.DeleteNote(id).ConfigureAwait(false);
            return Accepted();
        }
    }
}

The Azure Ad Scopes configured for access_as_user and access_as_admin. Web API applications here consists of three tiers: NotesControler, NotesService and NotesRepository with MongoDB configured underneath.

The overall code you can find on the GitHub: Compentio.Ferragosto.Notes
The integration tests for getting notes method could be like this:

public class NotesApiIntegrationTests : IClassFixture<WebApplicationFactory<Api.Startup>>
{
    private readonly WebApplicationFactory<Api.Startup> _factory;
    private readonly NotesRepositoryMock _notesRepositoryMock;

    private const string notesBaseUrl = "api/notes";

    public NotesApiIntegrationTests(WebApplicationFactory<Api.Startup> factory)
    {
        _factory = factory;
        _notesRepositoryMock = new();
    }


    [Fact]
    public async Task ShouldReturnListOfNotes()
    {
        // Arrange
        var httpClient = _factory.WithAuthentication()
                  .WithService(_ => _notesRepositoryMock.Object)
                  .CreateAndConfigureClient();

        var mockedNotes = NotesMocks.Notes;
        _notesRepositoryMock.MockGetNotes(mockedNotes);

        // Act
        var response = await httpClient.GetAsync(notesBaseUrl).ConfigureAwait(false);
        var notes = await response.Content.ReadFromJsonAsync<IEnumerable<Note>>().ConfigureAwait(false);

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.OK);
        response.Content.Headers.ContentType.ToString().Should().ContainAll("application/json; charset=utf-8");
        notes.Should().BeEquivalentTo(mockedNotes);            
    }

    [Fact]
    public async Task ShouldBeUnauthorized()
    {
        // Arrange
        var httpClient = _factory.WithService(_ => _notesRepositoryMock.Object)
                  .CreateAndConfigureClient();


        // Act
        var response = await httpClient.GetAsync(notesBaseUrl).ConfigureAwait(false);

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.Unauthorized);
        _notesRepositoryMock.Verify(notes => notes.GetNotes(), Times.Never());
    }

    [Fact]
    public async Task ShouldBeForbidden()
    {
        // Arrange
        var httpClient = _factory.WithAuthenticationWithoutClaims()
                  .WithService(_ => _notesRepositoryMock.Object)
                  .CreateAndConfigureClient();


        // Act
        Func<Task> getNotesTask = async () => { _ = await httpClient.GetAsync(notesBaseUrl).ConfigureAwait(false); };

        // Assert
        await getNotesTask.Should().ThrowAsync<System.Net.Http.HttpRequestException>();

        _notesRepositoryMock.Verify(notes => notes.GetNotes(), Times.Never());
    }
}

Few things here we should note:

WebApplicationFactory — factory for bootstrapping an application in memory for functional and integration tests
_httpClient — HTTP client created using WebApplicationFactory extensions for authentication and mocking services — code snippets are below
_notesRepositoryMock — mocks for repository.

WebApplicationFactory boostraps in memory HTTP web server, but for our scenario with authorization and authentication that’s not enough cause we need to check proper and invalid (unauthorized and unauthenticated) requests to our API. To cover it I’ve added WithAuthentication() and WithAuthenticationWithoutClaims() extensions methods for factory:

public static class WebApplicationFactoryExtensions
{
    public static WebApplicationFactory<T> WithAuthentication<T>(this WebApplicationFactory<T> factory) where T : class
    {
        return AddAuthentication<T, TestAuthenticationHandler>(factory);
    }

    public static WebApplicationFactory<T> WithAuthenticationWithoutClaims<T>(this WebApplicationFactory<T> factory) where T : class
    {
        return AddAuthentication<T, TestAuthenticationHandlerWithoutClaims>(factory);
    }

    private static WebApplicationFactory<T> AddAuthentication<T, TAuthHandler>(this WebApplicationFactory<T> factory) 
        where T : class
        where TAuthHandler : TestAuthenticationHandlerBase
    {
        return factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureTestServices(services =>
            {
                services.AddAuthentication("Test")
                    .AddScheme<AuthenticationSchemeOptions, TAuthHandler>("Test", options => { });
            });
        });
    }

    public static WebApplicationFactory<TFactory> WithService<TFactory, TService>(this WebApplicationFactory<TFactory> factory, Func<IServiceProvider, TService> implementationFactory) 
        where TService : class 
        where TFactory : class
    {
        return factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureTestServices(services =>
            {
                services.AddTransient(implementationFactory);
            });
        });
    }

    public static HttpClient CreateAndConfigureClient<T>(this WebApplicationFactory<T> factory) where T : class
    {
        var client = factory.CreateClient(new WebApplicationFactoryClientOptions
        {
            AllowAutoRedirect = false
        });

        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Test");

        return client;
    }

}

These methods use different AuthenticationHandlers: TestAuthenticationHandler for proper authentication and TestAuthenticationHandlerWithoutClaims for user, that does not have required claims. The handlers are below:

public class TestAuthenticationHandler : TestAuthenticationHandlerBase
{
    public TestAuthenticationHandler(IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
        : base(options, logger, encoder, clock)
    {
    }

    protected override Claim[] CreateClaims() => new[]
    {
        new Claim(ClaimTypes.Name, "Test user"),
        new Claim(ClaimTypes.NameIdentifier, Guid.NewGuid().ToString()),
        new Claim("http://schemas.microsoft.com/identity/claims/scope", "access_as_user")
    };
}

and TestAuthenticationHandlerWithoutClaims looks like:

public class TestAuthenticationHandlerWithoutClaims : TestAuthenticationHandlerBase
{
    public TestAuthenticationHandlerWithoutClaims(IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
        : base(options, logger, encoder, clock)
    {
    }

    protected override Claim[] CreateClaims() => new[]
    {
        new Claim(ClaimTypes.Name, "Test user")
    };
}

and TestAuthenticationHandlerBase is:


public abstract class TestAuthenticationHandlerBase : AuthenticationHandler<AuthenticationSchemeOptions>
{
    protected TestAuthenticationHandlerBase(IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
        : base(options, logger, encoder, clock)
    {
    }

    protected abstract Claim[] CreateClaims();

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        var claims = CreateClaims();  

        var identity = new ClaimsIdentity(claims, "Test");
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, "Test");

        var result = AuthenticateResult.Success(ticket);
        return Task.FromResult(result);
    }
}

here it is important in TestAuthenticationHandler to use claim type as “http://schemas.microsoft.com/identity/claims/scope” for Azure AD access_as_user scope. In the TestAuthenticationHandlerWithoutClaims we do not add required in NotesController access_as_user scope and in test case ShouldBeForbidden (in NotesApiIntegrationTests) we expect Forbidden response.
ShouldBeUnauthorized() method does not configured to use any authentication handler, thus we expect Unauthorized 401 error and, obviously, no any interaction with _notesRepository:

// Arrange
var httpClient = _factory.WithService(_ => _notesRepositoryMock.Object)
.CreateAndConfigureClient();
// Act
var response = await httpClient.GetAsync(notesBaseUrl).ConfigureAwait(false);
// Assert
response.StatusCode.Should().Be(HttpStatusCode.Unauthorized);
_notesRepositoryMock.Verify(notes => notes.GetNotes(), Times.Never());

Summary

Here I've covered three basic auth scenarios for API requests of one GET method:

200 OK,
401 Unauthorized
403 Forbidden. From my experience, it is important always to keep such tests in code and execute them during CI/CD pipelines, since it prevents us from accidental (which, unfortunately, occurs often) removal of Authorize or RequiredScope controller attributes. Obviously, in a real web apps integration testing scenarios, more test needed: e.g. validation tests (BadRequest), Server unexpected errors (500), empty lists or NotFound for one entity, ect.

In the post I’d like to show how we use WebApplicationFactory to arrange integration tests for different authorization scenarios. For testing and mocks I’ve used:

xUnit
Moq
Fluent Assertions
Bogus For mocking also I propose to use “Fluent Mocking” like this:

public class NotesServiceMock : Mock<INotesService>
{
    public NotesServiceMock MockGetNotes(IEnumerable<Note> notes)
    {
        Setup(service => service.GetNotes()).ReturnsAsync(notes);
        return this;
    }

    public NotesServiceMock MockGetNote(string noteId, Note note)
    {
        Setup(service => service.GetNote(It.Is<string>(i => i == noteId))).ReturnsAsync(note);
        return this;
    }

    public NotesServiceMock MockAddNote(Note note)
    {
        note.Id = Guid.NewGuid().ToString();
        Setup(service => service.AddNote(note)).ReturnsAsync(note);
        return this;
    }

    public NotesServiceMock MockModifyNote(Note note)
    {
        Setup(service => service.GetNote(It.Is<string>(i => i == note.Id))).ReturnsAsync(note);
        return this;
    }
}

Thank you and pleasure coding!

Source generators and a boilerplate code

Aleksander Parchomenko — Fri, 03 Dec 2021 10:17:42 +0000

Introduction

Source generators first were introduced in C# 9.0 in Spring 2020 as a new compiler feature that lets developers to generate new C# source code that can be added to a compilation. Using it you can inspect code with all of the rich metadata that the compiler builds up during compilation, then emit C# code back into the same compilation that is based on the data you’ve analyzed. If you’re familiar with Roslyn Analyzers, you can think of Source Generators as analyzers that can emit C# source code. It is a powerfull developers tool, that can augment you code starting from generation custom serializations and ending with generated fast dependency injection containers.

Code refactoring is one of the processes when developers maintain applications to minimize technical debth, refresh libraries used or maintain code readability. The main drawback of the boilerplate code is blackout the business logic: instead of analysis of functionality programmers need also to find it among overall code.
Here I’d like to introduce 3 libraries written by myself that are based on Source Generators features: SourceMapper, SourceConfig and SourceApi and are aimed to decrease boilerplate code in solution. An idea of each of the packages is to autogenerate code with some functionalities that can be used in code.

SourceMapper

During my work on different cloud-native applications with a various tech stacks I’ve paid attention to Java’s widely used mapping library MapStruct, where developers define mappings using Java annotations (in C# attributes). The SourceMapper package uses Source Generators and generates objects mappings based on C# attributes actually during coding. Of course, there is widely used .NET Mapper library AutoMapper, but the main difference between tham, that developer can see (and control) mappings in generated code.
The package can be installed using Nuget Package Manager:

Install-Package Compentio.SourceMapper

For example, definition of UserDao mapping to UserInfo object can be defined in interface, ClassName — defines the target mapper class name that is generated:

[Mapper(ClassName = "UserMapper")]
public interface IUserMapper
{
    [Mapping(Source = nameof(UserDao.FirstName), Target = nameof(UserInfo.Name))]
    UserInfo MapToDomainModel(UserDao userDao);
}

The Package than generates mapping code for you, that can be used in solution:

// <mapper-source-generated />
// <generated-at '01.10.2021 08:35:50' />
using System;

namespace Compentio.SourceMapper.Tests.Mappings
{
  public class UserMapper : IUserMapper
  {
      public static UserMapper Create() => new();
      public virtual Compentio.SourceMapper.Tests.Entities.UserInfo MapToDomainModel(Compentio.SourceMapper.Tests.Entities.UserDao userDao)
      {
          var target = new Compentio.SourceMapper.Tests.Entities.UserInfo();
          target.Name = userDao.FirstName;
          target.BirthDate = userDao.BirthDate;
          return target;
      }
   }
 }

Dependency injection extension code for various .NET containers also generated based on the Dependency Injection container you’ve been used in project. In this way you can inject mappers in your services, controllers or repositories and stay clean with Domain, DTO and DAO transformations in solution.

More about code, examples and contributing you can find on SourceMapper GitHub.

SourceConfig

SourceConfig package uses Source Generators Additional File Transaformation feature to generate additional C# code. The idea of this package is simple: instead of creating POCO classes for configuration in you project, the package generates these objects intead of you. First lets intall it:

Install-Package Compentio.SourceConfig

After that, even if you have few configs for different enviromnets, thay are merged in one class. Lets assume, that you have 2 configuration files for development and production like appsettings.json:

{
  "$NoteEmailAddresses": [
    "admin@test.com",
    "technical.admin@test.com",
    "business.admin@test.com"
  ],
  "ConnectionTimeout": "30",
  "ConnectionHost": "https://test.com",
  "DefaultNote": {
    "Title": "DefaultTitle",
    "Description":  "DefaultDescription"
  }
}

and for development environment appsettings.development.json:

{
  "ConnectionTimeout": "300",
  "DatabaseSize": "200"
}

All you need, is toset their properties as C# analyzer additional file in Visual Studio:

or in your *.cproj file:

<ItemGroup>
    <AdditionalFiles Include="Appsettings.Development.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </AdditionalFiles>
    <AdditionalFiles Include="Appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </AdditionalFiles>
</ItemGroup>

This will generate object for you configuration and you do not need to stay in sync when new configuration properties will be added to teh files: thay will apppear in you class automatically!:

// <mapper-source-generated />
// <generated-at '01.12.2021 15:34:34' />
using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;

namespace Compentio.SourceConfig.App
{
    [ExcludeFromCodeCoverage]
    public class AppSettings
    {
        public string ConnectionTimeout { get; set; }

        public string DatabaseSize { get; set; }

        public IEnumerable<string> _NoteEmailAddresses { get; set; }

        public string ConnectionHost { get; set; }

        public DefaultNote DefaultNote { get; set; }
    }

    [ExcludeFromCodeCoverage]
    public class DefaultNote
    {
        public string Title { get; set; }

        public string Description { get; set; }
    }
}

Source code and more, of course, on SourceConfig GitHub.

SourceApi

There are two approaches when implemening Web API: code first, that most of developers prefer: to create Web API controllers, DTO’s, to add Swagger UI and that’s all!; and API first, when API needs to be designed or discussed and only after that we start to implement it. In distributed systems with a various technologies and consumers of our API it is good to have language agnostic tools to agree and share API between the consumers. Open API Specification has been created for that:

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

The third library, that I called SourceApi created for API first approach: you (or your team) define API in yaml or json format, add it to Web API project and the package generates Controller base classes with DTO’s and documentations for your API. All you need, is to implement logic in controllers. You even do not need to create DTO’s, since it already generated.
For example, for standard Open API example, defined like

openapi: 3.0.1
info:
  title: Swagger Petstore
  description: 'This is a sample server Petstore server.  You can find out more about     Swagger
    at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For
    this sample, you can use the api key `special-key` to test the authorization     filters.'
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
- url: https://petstore.swagger.io/api/v1
- url: http://petstore.swagger.io/api/v1
paths:
  /store/inventory:
    get:
      summary: Returns pet inventories by status
      description: Returns a map of status codes to quantities
      operationId: getInventory
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                  format: int32
      security:
      - api_key: []
  /store/order:
    post:
      summary: Place an order for a pet
      operationId: placeOrder
      requestBody:
        description: order placed for purchasing the pet
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/Order'
        required: true
      responses:
        200:
          description: successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Order'
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        400:
          description: Invalid Order
          content: {}
      x-codegen-request-body-name: body
  /store/order/{orderId}:
    get:
      summary: Find purchase order by ID
      description: For valid response try integer IDs with value >= 1 and <= 10.  Other
        values will generated exceptions
      operationId: getOrderById
      parameters:
      - name: orderId
        in: path
        description: ID of pet that needs to be fetched
        required: true
        schema:
          maximum: 10.0
          minimum: 1.0
          type: integer
          format: int64
      responses:
        200:
          description: successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Order'
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        400:
          description: Invalid ID supplied
          content: {}
        404:
          description: Order not found
          content: {}
    delete:
      summary: Delete purchase order by ID
      description: For valid response try integer IDs with positive integer value.         Negative
        or non-integer values will generate API errors
      operationId: deleteOrder
      parameters:
      - name: orderId
        in: path
        description: ID of the order that needs to be deleted
        required: true
        schema:
          minimum: 1.0
          type: integer
          format: int64
      responses:
        400:
          description: Invalid ID supplied
          content: {}
        404:
          description: Order not found
          content: {}
components:
  schemas:
    Order:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
        petId:
          type: integer
          format: int64
        quantity:
          type: integer
          format: int32
        shipDate:
          type: string
          format: date-time
        status:
          type: string
          description: Order Status
          enum:
          - placed
          - approved
          - delivered
        complete:
          type: boolean
          default: false
      xml:
        name: Order

StoreControllerBase class is generated as (underhood it uses NSwag CSharpControllerGenerator to generate abstract controllers):

namespace Compentio.SourceApi.WebExample.Controllers
{
    using System = global::System;

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "13.13.2.0 (NJsonSchema v10.5.2.0 (Newtonsoft.Json v12.0.0.2))")]
    [Microsoft.AspNetCore.Mvc.Route("api/v1")]
    public abstract class StoreControllerBase : Microsoft.AspNetCore.Mvc.ControllerBase
    {
        /// <summary>Returns pet inventories by status</summary>
        /// <returns>successful operation</returns>
        [Microsoft.AspNetCore.Mvc.HttpGet, Microsoft.AspNetCore.Mvc.Route("store/inventory")]
        public abstract System.Threading.Tasks.Task<Microsoft.AspNetCore.Mvc.ActionResult<System.Collections.Generic.IDictionary<string, int>>> GetInventory();
        /// <summary>Place an order for a pet</summary>
        /// <param name = "body">order placed for purchasing the pet</param>
        /// <returns>successful operation</returns>
        [Microsoft.AspNetCore.Mvc.HttpPost, Microsoft.AspNetCore.Mvc.Route("store/order")]
        public abstract System.Threading.Tasks.Task<Microsoft.AspNetCore.Mvc.ActionResult<Order>> PlaceOrder([Microsoft.AspNetCore.Mvc.FromBody][Microsoft.AspNetCore.Mvc.ModelBinding.BindRequired] Order body);
        /// <summary>Find purchase order by ID</summary>
        /// <param name = "orderId">ID of pet that needs to be fetched</param>
        /// <returns>successful operation</returns>
        [Microsoft.AspNetCore.Mvc.HttpGet, Microsoft.AspNetCore.Mvc.Route("store/order/{orderId}")]
        public abstract System.Threading.Tasks.Task<Microsoft.AspNetCore.Mvc.ActionResult<Order>> GetOrderById([Microsoft.AspNetCore.Mvc.ModelBinding.BindRequired] long orderId);
        /// <summary>Delete purchase order by ID</summary>
        /// <param name = "orderId">ID of the order that needs to be deleted</param>
        [Microsoft.AspNetCore.Mvc.HttpDelete, Microsoft.AspNetCore.Mvc.Route("store/order/{orderId}")]
        public abstract System.Threading.Tasks.Task<Microsoft.AspNetCore.Mvc.IActionResult> DeleteOrder([Microsoft.AspNetCore.Mvc.ModelBinding.BindRequired] long orderId);
    }

    [System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "10.5.2.0 (Newtonsoft.Json v12.0.0.2)")]
    public partial class Order
    {
        [Newtonsoft.Json.JsonProperty("id", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public long Id { get; set; }

        [Newtonsoft.Json.JsonProperty("petId", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public long PetId { get; set; }

        [Newtonsoft.Json.JsonProperty("quantity", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public int Quantity { get; set; }

        [Newtonsoft.Json.JsonProperty("shipDate", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public System.DateTimeOffset ShipDate { get; set; }

        /// <summary>Order Status</summary>
        [Newtonsoft.Json.JsonProperty("status", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        [Newtonsoft.Json.JsonConverter(typeof(Newtonsoft.Json.Converters.StringEnumConverter))]
        public OrderStatus Status { get; set; }

        [Newtonsoft.Json.JsonProperty("complete", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public bool Complete { get; set; } = false;
    }

    [System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "10.5.2.0 (Newtonsoft.Json v12.0.0.2)")]
    public enum OrderStatus
    {
        [System.Runtime.Serialization.EnumMember(Value = @"placed")]
        Placed = 0,
        [System.Runtime.Serialization.EnumMember(Value = @"approved")]
        Approved = 1,
        [System.Runtime.Serialization.EnumMember(Value = @"delivered")]
        Delivered = 2,
    }
}

and can be used as base abstract class for your Web API controller. You only need to concentrate on implementation logic instead of definitions of response codes, stay in sync with DTO’s, etc. When you change Open API definition file, the base abstract class and DTO’s are refreshed:

namespace Compentio.SourceApi.WebExample.Controllers
{
    [ApiController]
    [ApiConventionType(typeof(DefaultApiConventions))]
    public class StoreController : StoreControllerBase
    {
        /// <inheritdoc />
        public async override Task<IActionResult> DeleteOrder([BindRequired] long orderId)
        {
            // Implement your async code here
            return Accepted();
        }

        /// <inheritdoc />
        public async override Task<ActionResult<IDictionary<string, int>>> GetInventory()
        {
            throw new NotImplementedException();
        }

        /// <inheritdoc />
        public async override Task<ActionResult<Order>> GetOrderById([BindRequired] long orderId)
        {
            throw new NotImplementedException();
        }

        /// <inheritdoc />
        public async override Task<ActionResult<Order>> PlaceOrder([BindRequired, FromBody] Order body)
        {
            throw new NotImplementedException();
        }
    }
}

Some configuration properties also added to the package: you can define the namespace of your base controllers, or you can generate only DTO’s in a case when you are the consumer of some REST API.
Source code and documentation can be found on SourceApi GitHub.