DEV Community: Bojan Nikolić

Your "Clean Architecture" is still layered!

Bojan Nikolić — Fri, 04 Dec 2020 13:52:09 +0000

Often developers, when talking about architecture, actually think about their project structure. Clean, Ports & Adapters, Onion... all of these are referring on how to organize your project. You either "inherit" it from your team or try some that makes more sense to you on new project or when refactoring. Thing is that project organization is important when you have a monolith or some coarse grained services that contain several functionalities that are somewhat related, but you want to keep them separate on code level and not to jump into making a (micro)service for each.

You usually end up with a solution that has several projects:

API - just for controllers and to expose business logic
Domain/Core - with business logic
Infrastructure - interface implementation
Persistence? - some folks like to keep DB stuff separated

So what is wrong with this structure? Listen to this talk by Simon Brown and continue reading to grab some code samples.

Your code doesn't match your diagram

Let's start by having an API that has two functionalities:

Weather Forecast
Calculator

How would you draw a component diagram? Something like this, right?

How would you structure your code? I guess something like this:

API (project)
Domain (project)
- WeatherForecast (folder)
- Calculator (folder)
Infrastructure
- WeatherForecast (folder)
- Calculator (folder)

There is an obvious mismatch, right? You might say - that doesn't matter, we have a nice folder structure so we keep things separated and well organized.

OK, but what is stopping something from WeatherForecast folder to call something else from Calculator folder? Internal conventions and rules? Pull requests? Yes, all of that might help, but it would be more obvious if in that pull request you would see that unwanted relation trying to creeping in.

Then how to structure?

A suggestion is that it matches you component diagram, like this:

API (project)
WeatherForecast (project)
- ...
Calculator (project)
- ...

I deliberately put three dots, since it is up to developer of the specific functionality how to organize code inside of it. Should you have Domain/Infrastructure/whatever folder structure in each project? Or you will have some convention that if functionality is simple and you have just few classes, you do not even want to have any sub-folder? Whatever your teams' convention is, that is fine.

Some obvious advantages are:

Solution structure matches diagram, so it is obvious where the code is.
All code related to one functionality is in one project, making it much harder to make some dangerous dependencies between different functionalities.

Encapsulate your component

We all know what is encapsulation, but we often think of it just in the terms of class encapsulation. Simon Brown suggested we do the encapsulation on component level too. If you think of your REST API, it is encapsulated as a consumer can only call exposed methods in a way you specified. Why not do the same for your component?

You might say you already do that by having interfaces that are then injected, so a caller can't access the implementation, but that is more often not true. Usually we have that API/Core/Implementation project structure and all our classes are public. We need them to be public as DI setup is usually in API project and they need to be visible.

With the new project-per-component structure, we do not have that problem any more. Implementation classes can be private or internal and therefore hidden from other components. Yes, you would have your DI configuration inside the component!

Sample solution

Grab a look at the sample solution on GutHub

nikolic-bojan / modularity

Sample solution showing how to organize code in Components/Modules, so we completely avoid layered approach.

Your "Clean Architecture" is still layered!

Often developers, when talking about architecture, actually think about their project structure. Hexagonal, Clean, Ports & Adapters, Onion... all of these are referring on how to organize your project. You either "inherit" it from your team or try some that makes more sense to you on new project or when refactoring. Thing is that project organization is important when you have a monolith or some coarse grained services that contain several functionalities that are somewhat related, but you want to keep them separate on code level and not to jump into making a (micro)service for each.

You usually end up with a solution that has several projects:

API - just for controllers and to expose business logic
Domain/Core - with business logic
Infrastructure - interface implementation
Persistence? - some folks like to keep DB stuff separated

So what is wrong with this structure? Listen…

View on GitHub

Structure of my project is:

API (project)
Components (solution folder to group components)
- WeatherForecast (project)
- Calculator (project)

Things that are exposed from component are:

Interfaces
DTOs needed for interfaces
Dependency Injection configuration

In API's Startup.cs you just add calls to extension methods in order to configure DI like this:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    services.AddComponentWeatherForecast();
    services.AddComponentCalculator();
}

Here is a sample of one extension method:

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddComponentWeatherForecast(this IServiceCollection services)
    {
        return services.AddScoped<IWeatherForecastService, WeatherForecastService>();
    }
}

Final words

I hope you like these encapsulated components. They are really making hard for team members to make "shortcuts". If components need to talk to each other, that is totally fine - only thing you can access on another component are interfaces and DTOs. If you want to make a full-blown service out of your component, that would be super-easy as everything is in one place.

Would like to hear your comments and questions.

Thanks for reading!

Handle errors with your convention in ASP.NET Core

Bojan Nikolić — Sat, 15 Aug 2020 22:44:58 +0000

This post is a natural continuation of some of my previous ones:

All work is done in the same GitHub repository https://github.com/nikolic-bojan/soap-client so you can see the code.

Here, we are dealing with handling errors in API project and also with logging some additional information that are valuable both for error analysis and determining how your service behaves.

Error handling

There is a good explanation on how to do error handling in Microsoft documentation - https://docs.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-3.1#exception-handler-lambda.

What I would like to point out is that if you want to have a good API(s), you should make their responses clear, especially error responses. Those responses are often not read by humans, but by someone else's code and they should be clear on what to do when error occurs.

There is a well established standard for error responses implemented also in .NET as ProblemDetails and ValidationProblemDetails classes. It is also built into the ControllerBase since Core 2.1.

It is not a problem to use these, it is more of an issue what to put into their properties and based on what. In this sample, I tried to make things simple, but you might want to make them more complex for your case. My advice - do not go too complex as someone needs to implement their code based on them.

In order to handle errors, I added the following line in Startup.cs

app.UseExceptionHandler(errorApp => errorApp.Run(ExceptionHandler.CreateExceptionHandler(env)));

Important stuff is in that method, which will handle exceptions with a few steps:

We need to get the exception via IExceptionHandlerFeature and create some starting ProblemDetails.
We then switch by exception type and change some ProblemDetails properties and at the same time add some log scope data.
Finally, we write ProblemDetails directly to Response Body stream.

In order not to c/p entire method and bloat the post, please check the code here https://github.com/nikolic-bojan/soap-client/blob/master/Api/Handlers/ExceptionHandler.cs

What you will notice that I have only 3 outcomes, all based on exception type:

Validation exception - we return ValidationProblemDetails and log errors (maybe it could be LogWarning)
Service exception - any exception that happens in Service class (adapter to 3rd party)
Any other not handled exception

Some advises on property values

Create few (fewer is better) exception types that will define some standard exceptional situations.
Return 400 for Validation errors (thanks Mr. Obvious!)
Return 404 from your controller (NotFound) if you want to inform there is no resource.
Use app.UseStatusCodePages(), so e.g. wrong URL will not produce same error as when resource is not found.
All exceptions that bubble up in your code should be returned as 500.
- Do not try to be "smart" and correlate exceptions to status codes (we made that mistake and status codes became misleading).
- Correlate exception types to type property in response either by exception type name or (better) by having URL to your documentation that will explain what that error type is all about.

This way the consumer of your service will know if they should retry the call, was that a temporary issue, something to alarm on immediately (you should also do that by logging Critical error, for example); in general - how to behave.

Sample responses

Here is how BadRequest looks like

{
    "type": "ValidationException",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "92d14dddb407d945909d970efdc03988",
    "errors": {
        "FirstName": [
            "First name must not be 400"
        ]
    }
}

This is some error calling 3rd party system (SoapUI mock was down)

{
    "type": "ServiceException",
    "title": "The content type text/html; charset=iso-8859-1 of the response message does not match the content type of the binding (text/xml; charset=utf-8). If using a custom encoder, be sure that the IsContentTypeSupported method is implemented properly. The first 95 bytes of the response were: '<html><body><p>There are currently 0 running SoapUI MockServices</p><ul></ul></p></body></html>'.",
    "status": 500,
    "traceId": "145be362dd1e7c42b84c4a566ae0ed24"
}

Log more information for diagnostics and alarming

This is kind of separate subject, but in my head exceptional situations and logging additional information that can help identifying the pattern of the issue or can be used for diagnostics and alarming, goes in the same package.

This logging is per request and contains all kind of request related data. You can write this code by yourself or use some add-on from your logging library, like Serilog has RequestLoggingMiddleware. In the sample I use clean Microsoft Logger, so I had to write it by myself. Code is available here https://github.com/nikolic-bojan/soap-client/blob/master/Api/Handlers/TraceContextMiddleware.cs

On each request we LogInformation on that request. Base on those data we can create some dashboard widgets that would show us the statistics on HTTP status code per Controller and Action. We could also setup some alarms based on certain thresholds, e.g. "if there are more than X error logs during Y minutes then..."

Feedback

This post feels a bit "rough" and most likely opinionated (isn't everything?)

I would really like to get a feedback on this subject as I do not think this is something you can call best-practice and all will agree with the approach.

What are your thoughts? How do you handle error handling?

BR,
Bojan

Log HttpClient request and response based on custom conditions in .NET Core

Bojan Nikolić — Thu, 13 Aug 2020 20:13:31 +0000

In my team, we created a lot of code for calling some 3rd party services. From time to time we needed to see what how did the actual HTTP request and response looked like. Usually when something goes "south" from various reasons.

It is not a hard task to log each request and response, but if you take into consideration performance, log size, logging of sensitive data, etc. you might not want to do that for each request.

We knew when we would like to log:

If there was some error while communicating to 3rd party service, so we can have request/response for their support (or for our reproduction of the issue)
We explicitly wanted to send some parameter to capture request/response, for various reasons, even though everything went fine (or looked like it did)
Based on some response HTTP code or something else from the response, but that was different from service to service.

What we also knew is that:

We would like to have it reusable
It should not make our Service class (the one that implements adapter to 3rd party service) bloated and
We should be able to add it as any other Delegating Handler through HttpClient setup

Delegating Handler

We created a delegating handler with two parameters in constructor



internal class TraceLogHandler : DelegatingHandler
{
  public TraceLogHandler(IHttpContextAccessor httpContextAccessor, 
    Func<HttpResponseMessage, bool> shouldLog)
    {
        ...

First we need IHttpContextAccessor to allow us to acces current HttpContext. We need it for two purposes - to access to query parameters and check if "traceme" was sent.



bool traceMe = _httpContextAccessor.HttpContext.Request.Query
  .ContainsKey("traceme");

That is a signal for us we should log, no matter what. It is also good to add that value through some middleware in all log messages, but I skip that part for this sample.

Second one is for purpose of creating a logger as HttpContext also allow us access to IServiceProvider (the RequestServices property).



var logger = _httpContextAccessor.HttpContext.RequestServices
  .GetRequiredService<ILogger<TraceLogHandler>>();

Second constructor parameter is a Func that accepts HttpResponseMessage (response from 3rd party service) and should return bool value. Remember I said we wanted some dynamic decision based on response? Well, this is it. To give you an example how it could look, let's go to the Startup.cs where I setup HttpClient.



services.AddHttpClient(HelloService.ServiceName, config =>
{
    // Some custom configuration like request timeout
    config.Timeout = TimeSpan.FromSeconds(5);
})
.AddTraceLogHandler((response) =>
{
  // Here we setup that if Response status code is not 200-299, 
  // we should log entire HttpClient request and response 
  // to 3rd party service.
  // You can setup any condition based on the HttpResponseMessage.

  return !response.IsSuccessStatusCode;
});

As explained in a comment, you can setup any condition based on HttpResponseMessage. If your function returns true, delegating handler will log request and response.

We needed this to be variable per HttpClient, since different 3rd party services behave differently - we have one that throws HTTP status 500 when record is not found, other one returns for the same situation status 200 with some text message... don't ask...

AddTraceLogHandler is an extension method so we can add handler easier. Here are two extension methods as an example.



public static class HttpClientBuilderExtensions
{
  public static IHttpClientBuilder AddTraceLogHandler(
    this IHttpClientBuilder builder, 
    Func<HttpResponseMessage, bool> shouldLog)
  {
    return builder.AddHttpMessageHandler((services) => 
      new TraceLogHandler(services
        .GetRequiredService<IHttpContextAccessor>(), shouldLog));
  }

  public static IHttpClientBuilder AddTraceLogHandler(
    this IHttpClientBuilder builder)
  {
    return builder.AddHttpMessageHandler((services) => 
      new TraceLogHandler(services
        .GetRequiredService<IHttpContextAccessor>(), 
      (HttpResponseMessage) => { return false; }));
  }
}

Show us the code!

Right, almost forgot - code of the handler itself. You can find it here on the GitHub https://github.com/nikolic-bojan/soap-client/blob/master/Api/Handlers/TraceLogHandler.cs as a part of my SoapClient repository.

There I use it for calling some SOAP 3rd party service with some "magic" for using HttpClient for calling SOAP, but that doesn't matter, that is just a regular delegating handler, so you can use it for any HttpClient.



internal class TraceLogHandler : DelegatingHandler
{
    private readonly IHttpContextAccessor _httpContextAccessor;
    private readonly Func<HttpResponseMessage, bool> _shouldLog;

    public TraceLogHandler(IHttpContextAccessor httpContextAccessor, Func<HttpResponseMessage, bool> shouldLog)
    {
        _httpContextAccessor = httpContextAccessor;
        _shouldLog = shouldLog;
    }

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        bool logPayloads = false;

        // If you pass a query string parameter "traceme", HttpClient request/response will be logged.
        bool traceMe = _httpContextAccessor.HttpContext.Request.Query.ContainsKey("traceme");

        logPayloads = logPayloads || traceMe;

        HttpResponseMessage response = null;
        try
        {
            response = await base.SendAsync(request, cancellationToken);

            // We run the ShouldLog function that calculates, based on HttpResponseMessage, if we should log HttpClient request/response.
            logPayloads = logPayloads || _shouldLog(response);
        }
        catch (Exception)
        {
            // We want to log HttpClient request/response when some exception occurs, so we can reproduce what caused it.
            logPayloads = true;
            throw;
        }
        finally
        {
            // Finally, we check if we decided to log HttpClient request/response or not.
            // Only if we want to, we will have some allocations for the logger and try to read headers and contents.
            if (logPayloads)
            {
                var logger = _httpContextAccessor.HttpContext.RequestServices.GetRequiredService<ILogger<TraceLogHandler>>();
                Dictionary<string, object> scope = new Dictionary<string, object>();

                scope.TryAdd("request_headers", request);
                if (request?.Content != null)
                {
                    scope.Add("request_body", await request.Content.ReadAsStringAsync());
                }
                scope.TryAdd("response_headers", response);
                if (response?.Content != null)
                {
                    scope.Add("response_body", await response.Content.ReadAsStringAsync());
                }
                using (logger.BeginScope(scope))
                {
                    logger.LogInformation("[TRACE] request/response");
                }
            }
        }

        return response;
    }
}

To explain briefly - if either of the conditions for logging was true (we have "traceme" query string parameter, there was some exception, function based on HTTP response returned true), we will create logger, add request and response headers and content to log scope and log that on information level.

This is how that look in Seq. Looks good to me!

Check out the SoapClient repository for full code https://github.com/nikolic-bojan/soap-client and copy the parts you need to see it working in your project.

Hope to see some comments and questions!

BR,
Bojan

Make SOAP requests using IHttpClientFactory in .NET Core

Bojan Nikolić — Mon, 03 Aug 2020 14:29:38 +0000

SOAP services became second class citizen in .NET Core. REST was "the-way-to-go" and who creates SOAP services these days anyways? Well, maybe not these days, but a lot of them were created back in the days when SOAP was the King. Some of them are still alive and you need to access them.

Sure, accessing is not a big deal, VS still supports this, but if you worked with IHttpClientFactory when calling REST services and liked it, you would want to have all that while working with SOAP.

Is this possible?

TL;DR;
Yes it is! You can find sample application here on my GitHub repository https://github.com/nikolic-bojan/soap-client Browse through the code to figure what I did or just continue reading this article.

Problem and digging out the solution

Around a year and a half ago we moved our first service from "old" Framework to .NET Core. Later that year I started looking for a way to move to .NET Core some services that call SOAP 3rd party services. I wasn't satisfied with the basic stuff Core offers and I wanted something more similar to the options we have with IHttpClientFactory. Actually, I wanted the same experience!

I started looking for a solution. There were some custom libraries, but that was out of the question. They also felt hacky. I played around writing ISoapClientFactory as a copy of HTTP one, but only to realize I do not want to maintain something like that. At last, I postponed this for later.

Few months back, I gave it another go. This time I ran into GitHub issue https://github.com/dotnet/wcf/issues/3230 that pointed me to both this blog post https://medium.com/trueengineering/realization-of-the-connections-pool-with-wcf-for-net-core-with-usage-of-httpclientfactory-c2cb2676423e and this PR added to Core https://github.com/dotnet/wcf/pull/2534/files by a demigod of WCF - Matt Connew. Big thank you for these people!

So, is this article more/less a re-chewing of the GitHub Issue, PR and the blog post? Yes, you can say that, but I will explain one or two other walls I hit with this, so it is up to you where you will continue reading.

Add SOAP service

Adding existing SOAP/WCF service should not be a big issue. You should just follow the official documentation here https://docs.microsoft.com/en-us/dotnet/core/additional-tools/wcf-web-service-reference-guide

Caveat #1

What I encountered is that I couldn't do it. I kept getting the error that tool can't work on my .NET Core 3.x (I removed all previous versions) and requires v2.1. In order not to be blocked, I managed to find and install v2.1. Runtime installation should do the trick (I am not 100% sure, it was 2 months ago, do not hunt me down if runtime doesn't work and you need SDK). Visual Studio was now creating proxy as it should. Great!

How to make SOAP client work with IHttpClientFactory

When I went through those GitHub issue and PR, it is quite simple to answer - you need to add new Endpoint Behavior that will basically replace the default HttpClientHandler with the HttpMessageHandler that will be created by our beloved IHttpMessageHandlerFactory.

OK, how do I do that? First, you will need a new class that will implement IEndpointBehavior and will look like this



public class HttpMessageHandlerBehavior : IEndpointBehavior
{
    private readonly Func<HttpMessageHandler> _httpMessageHandler;

    public HttpMessageHandlerBehavior(IHttpMessageHandlerFactory factory, string serviceName)
    {
        // Here we prescribe how handler will be created.
        // Since it uses IHttpMessageHandlerFactory, this factory will manage the setup and lifetime of the handler, 
        // based on the configuration we provided with AddHttpClient(serviceName) 
        _httpMessageHandler = () => factory.CreateHandler(serviceName);
    }

    public void AddBindingParameters(ServiceEndpoint endpoint, BindingParameterCollection bindingParameters)
    {
        // We need this line to add our HttpMessageHandler as HttpClientHandler.
        bindingParameters.Add(new Func<HttpClientHandler, HttpMessageHandler>(handler => _httpMessageHandler()));
    }

    public void ApplyClientBehavior(ServiceEndpoint endpoint, ClientRuntime clientRuntime) { }

    public void ApplyDispatchBehavior(ServiceEndpoint endpoint, EndpointDispatcher endpointDispatcher) { }

    public void Validate(ServiceEndpoint endpoint) { }        

}

There you have all the "magic" where constructor accepts IHttpMessageHandlerFactory and defines function for creating a new handler; plus the part where we define how newly created HttpMessageHandler should be used as HttpClientHandler when calling SOAP service.

Of course, I had to add this EndpointBehavior in constructor of my HelloService singleton that injects IHttpMessageHandlerFactory



public HelloService(IHttpMessageHandlerFactory factory, ILogger<HelloService> logger)
{
    _logger = logger;
    _client = new Hello_PortTypeClient();
    _client.Endpoint.EndpointBehaviors.Add(new HttpMessageHandlerBehavior(factory, ServiceName));
}

Wait! What is this ServiceName? Well, I need to configure HttpClient, so I will refer it with a ServiceName both in HelloService class and in Startup



// Here we configure how the HttpClient with HtpMessagehandler will be configured, like for any HTTP client (e.g. calling REST/JSON service)
services.AddHttpClient(HelloService.ServiceName, config =>
{
    // Some custom configuration like request timeout
    config.Timeout = TimeSpan.FromSeconds(5);
});

There you will put your additional handlers, Polly resilience and all those nice things, like you already do when calling REST.

Caveat #2

You can't put in AddHttpClient stuff like BaseAddress or Authentication etc. That stuff needs to be setup on Endpoint or Binding, like explained in this blog post https://medium.com/grensesnittet/integrating-with-soap-web-services-in-net-core-adebfad173fb

I suggest you setup some of the things in constructor of your service (HelloService in my example) with injecting of Options, but I will leave that up to you, depending on how much things you need to setup and your best practices on that.

Caveat #3

I was so happy with the solution, so I just wanted to confirm it like in blog post with some load test with JMeter. I started the SoapUI mock (provided in the repository), opened CurrPorts and I didn't like what I found there. Even though calls did work, application opened too many connections - no connection pooling! Basically opened a connection per request! That was unacceptable.

It looked like solution was not using IHttpClientFactory. That was not possible, I went through debugger, it should work as advertised. CurrPorts was looking good on that blog post. What am I missing?

After few hours wasted on looking what could be wrong, I noticed that there are new NuGet versions available for System.ServiceModel.* packages. Mine (generated by VS) were 4.4.0, latest were 4.7.0. No, it can't be something stupid like that... yes it was.

I updated NuGet packages and all started working as it should!

I hit it from JMeter with 5 threads (and 100 calls per thread) and voila - 5 connections opened, just like it should!

Final words

If you would like to recreate code from repository, you will need:

SoapUI, to run mock (https://www.soapui.org/downloads/soapui/)
JMeter to run load tests (https://jmeter.apache.org/download_jmeter.cgi)
CurrPorts to see how many ports have been open (https://www.nirsoft.net/utils/cports.html#DownloadLinks)

I wanted to keep this short (failed as usual), so please ask questions if you are not clear on some of the steps.

Ocelot Gateway with "auto-generated" Swagger

Bojan Nikolić — Sun, 10 Nov 2019 16:00:48 +0000

We have a Gateway API that routes all calls to services below. The simplest initial solution was to create it with controllers and to define return types and other annotations, so we could have Swagger UI for other business units that use our "common" services.

I re-invented the wheel with creating a library on top of the HttpClient, just in order to be able to call services below. I was aware of Ocelot, but didn't have a solution to make it work and have Swagger file generated.

Now I have a workaround, that will not require team to learn swagger's JSON/YAML syntax. We can continue working as we did and also have Ocelot gateway with all its' possibilities.

TL;DR;
I am keeping my OLD gateway in order to generate swagger.json, but will not deploy it any more to server. I am also creating new OCELOT gateway that will just use that generated swagger.json. Visit Git repository https://github.com/nikolic-bojan/ocelot-with-swagger that contains code and build definition for this transition.

Initial state

I guess you already opened GitHub repository, so I would like to explain what was the initial state of the solution. There were 2 projects:

Gateway - This is initial gateway with controllers and Swashbuckle library to generate and show Swagger UI.
Api - This represents some underlying service that gateway is calling.

I added some sample call from Gateway to Api, so you can verify it works. I commented it out in code so we can prove later we do not need it really, but you can uncomment to see it works. Of course, this is super-simplified code, for easier understanding. Grab a look at the WeatherForecastController.

[HttpGet]
public async Task<IEnumerable<WeatherForecast>> Get()
{
    var client = _httpClientFactory.CreateClient("api");
    var response = await client.GetAsync("weatherforecast");

    var result = JsonSerializer.Deserialize<IEnumerable<WeatherForecast>>(await response.Content.ReadAsByteArrayAsync());

    return result;
}

OK, that works. We have return type, we can add more annotations, so Swagger definition can be more rich, with samples etc. On start it generates swagger.json and all is good. All except I use some Ocelot-like library I made, that is proven in Production, but doesn't have all features Ocelot has and it is not battle tested with hundreds of projects, so some edge cases could occur. In Production. Not so fun.

Googling for the solution

I was hoping there is some solution to jump from internal library to Ocelot without too much fuzz. The conclusions were next:

There is no automatic solution as it is impossible (https://github.com/ThreeMammals/Ocelot/issues/161)
Create swagger.json and maintain it manually (entire team should learn syntax and know what they are doing)
Somehow generate swagger.json on each model change and just use it in Ocelot gateway

Second was an option, but I am already pushing my luck with the team with jumping to new framework, changes in our CI, etc. Dropping "we need to learn Swagger syntax" would maybe be too much. Issues with adoption, bugs introduced in first few weeks/months, etc. Not worth of it. Maybe in 2020 :)

Solution and Pros/Cons

OK, then what? Easy - we can keep the Old Gateway project to generate swagger.json and just use that in new Ocelot Gateway!

Pros:

We use Ocelot! With all its' possibilities and extensibility.
We do not need to learn Swagger specification.
We change very little how we work.

Cons:

We have a project that has sole purpose to generate swagger.json.
We need to add manually ReRoutes (we had to do similar in Old Gateway).

In my opinion pros/cons looks good. I like it. Someone could say that you can do some magic stuff in internal library with some handlers, but you can also use handlers in Ocelot. Also... magic... not sure if it is good always.

Generate `swagger.json` for Ocelot

Small problem was - how to generate swagger.json. It is generated when application starts. I didn't want Old Gateway to start on run anywhere.

No problem, Test project and WebApplicationFactory to the rescue!
You create new (or use existing) Test project and create the following test case.

[TestMethod]
public async Task CreateSwaggerJson()
{
    WebApplicationFactory<OldGateway.Startup> factory = new WebApplicationFactory<OldGateway.Startup>();

    var client = factory.CreateClient();

    var swaggerResponse = await client.GetAsync("/swagger/v1/swagger.json");

    await File.WriteAllTextAsync("../../../../../src/OcelotGateway/wwwroot/swagger.json", await swaggerResponse.Content.ReadAsStringAsync());
}

To explain it:

WebApplicationFactory will run your Old Gateway in-memory.
HttpClient will GET swagger.json that was generated on start.
You will save it in new Ocelot Gateway wwwroot folder so it can be picked up by SwaggerUI middleware.

That is it! Done! You have swagger.json generated from a project that will never be deployed or ran anywhere!

Swagger UI in new Ocelot Gateway

With previous step, swagger.json is already in Ocelot's wwwroot folder and just needs to be configured with one simple step.

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger.json", "My API V1");
});

I deliberately added a dummy.txt file in wwwroot as I had issue with build on Azure DevOps - as nothing was in that folder, it was not created, so saving swagger.json from Test case was failing. Now it is all good.

Azure DevOps build

So, it was all fine in local. I manually run Tests and swagger.json is saved to Ocelot's wwwroot folder. Then I start Ocelot Gateway and it picks it up from that folder.

That is not how it will look on a build server. That is why I created a YAML build to show you how it should work.

trigger:
- master

pool:
  vmImage: 'windows-latest'

variables:
  buildConfiguration: 'Release'

steps:
- task: DotNetCoreCLI@2
  inputs:
    command: 'build'
    projects: 'OcelotWithSwagger.sln'
- task: DotNetCoreCLI@2
  inputs:
    command: 'test'
    projects: 'test/Gateway.Tests/Gateway.Tests.csproj'
    testRunTitle: 'Generate Old Gateway swagger.json'
- task: DotNetCoreCLI@2
  inputs:
    command: 'publish'
    publishWebProjects: false
    projects: 'src/OcelotGateway/OcelotGateway.csproj'
    arguments: '--configuration $(buildConfiguration) --output $(Build.ArtifactStagingDirectory)'
- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)'
    ArtifactName: 'OcelotGateway'
    publishLocation: 'Container'

It has the following steps:

Build entire solution (all projects)
Run Gateway.Tests project, to create swagger file
Publish Ocelot Gateway
Create build artifact (zipped Ocelot Gateway as a single EXE)

Final words

Now you have all to transform your API based Gateway to Ocelot and keep Swagger UI auto-generated.

TBH, I plan to push my team toward learning Swagger/OpenApi specification, but YAML style. Maybe in 2020, but at least we can now use great library like Ocelot!

I would like to hear comments and questions, so we can improve this some more, if needed.

BR,
Bojan

Memory+Distributed Caching in .NET Core

Bojan Nikolić — Sun, 08 Sep 2019 21:54:31 +0000

We were building yet another adapter toward some 3rd party service. They are caching results on their side for 1 day (7 days for one of the routes), but charging you per call.
OK, if you want to play like that... We can cache also!

TL;DR;
I created a small service class that allows you to cache in both Memory and some Distributed cache and take best of both worlds.
Visit Git repository https://github.com/nikolic-bojan/common-utilities
That contains code, unit tests and sample console application.
Copy/Paste the code and make your flavor.

Caching in Core

Documentation is really good in .NET Core, so this is no exception. You have 2 options when caching - IMemoryCache and IDistributedCache.

Since our apps run on IIS, even though they are set to Allways Running, our Ops crew set App Pools to restart every 29 hours. So, caching just to memory could work, but we have several servers, we could redeploy, some server restarts...

OK, let's do it then in some Distributed cache. We had Redis setup and that is all good, but it is slower than memory cache. But what if...

Best of both worlds

Why not caching to both memory and to Redis (or some other Distrubuted cache)? I searched a little bit and stumbled upon a great post by Nick Craver about how they do it in Stack Overflow How We Do App Caching

OK, we are super-far from that number of requests and needs for caching, but why not make some reusable code for some Caching Service that would have options for both memory and distributed caching?

Here is the logic:

Check if you have cached item in memory cache (on that server)
If you have, all good, no need to do anything else
If you do not - go to Distributed cache and check there
If it is there, grab it and store it in memory cache also
If it is not, execute some "factory" method that will create the value for cache and store it in distributed and then memory cache

Here is the example of how would you call Caching Service



await cachingService.GetOrCreateAsync<TestObject>(
    "key", 
    () => Task.FromResult(new TestObject()), 
    TimeSpan.FromMinutes(1), 
    TimeSpan.FromMinutes(5));

Most interesting part is second parameter and that one is a Func<Task<T>>. That function will be only executed if Caching Service doesn't find key in both memory and distributed cache.
That function will contain some "expensive" part - from code execution or from pricey-3rd-party-call perspective.

Show us the code!

This is the current state of code on GitHub. I deliberately didn't want to create some NuGet, because I didn't do that yet for our local use also. When I figure out the needs from several projects, I will build something truly reusable, even though it is very reusable now.

nikolic-bojan / common-utilities

Common utilities that can be reused for any project

Memory+Distributed Caching in .NET Core

We were building yet another adapter toward some 3rd party service. They are caching results on their side for 1 day (7 days for one of the routes), but charging you per call OK, if you want to play like that... We can cache also!

TL;DR I created a small service class that allows you to cache in both Memory and some Distributed cache and take best of both worlds. Visit Git repository https://github.com/nikolic-bojan/common-utilities That contains code, unit tests and sample console application. Copy/Paste the code and make your flavor.

#Caching in Core

Documentation is really good in .NET Core, so this is no exception. You have 2 options when caching - IMemoryCache and IDistributedCache.

Since our apps run on IIS, even though they are set to Allways Running, our Ops crew set App Pools to restart every 29 hours. So, caching just to memory…

View on GitHub

Interface is fairly simple



public interface ICommonCachingService
{
    Task<T> GetOrCreateAsync<T>(string key, Func<Task<T>> factory, TimeSpan memoryCacheExpiration, TimeSpan? distributedCacheExpiration = null) where T : class;

    Task<string> GetOrCreateStringAsync(string key, Func<Task<string>> factory, TimeSpan memoryCacheExpiration, TimeSpan? distributedCacheExpiration = null);

    Task<T> GetOrCreateAsync<T>(IConverter<T> converter, string key, Func<Task<T>> factory, TimeSpan memoryCacheExpiration, TimeSpan? distributedCacheExpiration);
}

You have 3 methods:

Caching objects with JSON serialization.
Caching strings without serialization (because it didn't work for me with JSON serialization; I am lazy to figure out why)
Caching whatever with custom Converter (implement your serialization)

First two are just calling the third, where the actual implementation is, with a pre-selected Converter.

Parameters for the methods are:

key - A key to cache by, make some method for generating unique one.
factory - I explained it earlier.
memoryCacheExpiration - Time-to-live (TTL) in memory cache. There is no sliding option.
distributedCacheExpiration - TTL in distributed cache.
converter - Simple serialize/deserialize interface as code below shows.



public interface IConverter<T>
{
    string Serialize(object obj);

    T Deserialize(string value);
}

Memory cache



public async Task<T> GetOrCreateAsync<T>(IConverter<T> converter, string key, Func<Task<T>> factory, TimeSpan memoryCacheExpiration, TimeSpan? distributedCacheExpiration)
{
    var local = await _memoryCache.GetOrCreateAsync(key, entry =>
    {
        TimeSpan calculatedDistributedCacheExpiration = distributedCacheExpiration ?? memoryCacheExpiration;

        entry.AbsoluteExpiration = DateTime.UtcNow.Add(memoryCacheExpiration);
        return GetFromDistributedCache(converter, key, factory, calculatedDistributedCacheExpiration);
    });

    return local;
}

MemoryCache already has this handy GetOrCreateAsync method that accepts "factory" method. I just added setup for expiration and forwarded function call with all the parameters.

Distributed cache



private async Task<T> GetFromDistributedCache<T>(IConverter<T> converter, string generatedKey, Func<Task<T>> factory, TimeSpan calculatedDistributedCacheExpiration)
{
    _logger.LogDebug("Getting cached value from Distributed cache for key {Key}", generatedKey);
    try
    {
        var cachedItem = await _distributedCache.GetStringAsync(generatedKey);
        if (cachedItem != null)
        {
            _logger.LogDebug("Read cached value from Distributed cache for key {Key}", generatedKey);
            var value = converter.Deserialize(cachedItem);
            return value;
        }
    }
    catch (Exception e)
    {
        _logger.LogWarning(e, "Exception getting cached item from Distributed cache.");
    }

    var item = await factory.Invoke();
    if (item != null)
    {
        try
        {
            var cacheEntryOptions = new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = calculatedDistributedCacheExpiration };
            var serializedValue = converter.Serialize(item);
            await _distributedCache.SetStringAsync(generatedKey, serializedValue, cacheEntryOptions, CancellationToken.None);
            _logger.LogDebug("Stored in Distributed cache for key {Key}", generatedKey);
        }
        catch (Exception e)
        {
            _logger.LogWarning(e, "Exception storing cached item in Distributed cache.");
        } 
    }

    return item;
}

This little fellow has a bit more logic:

Tries to get value from distributed cache and return value if available,
If it is not there, calls "factory" method to create value and then store it in cache.

I also added basic try-catch, so nothing breaks if there is some issue with Redis or some other distributed cache, both for reading and storing.

Example

You already saw it on the beginning, but let's do it again



await cachingService.GetOrCreateAsync<TestObject>(
    "key", 
    () => Task.FromResult(new TestObject()), 
    TimeSpan.FromMinutes(1), 
    TimeSpan.FromMinutes(5));

Now you know this tells a story - try to get from memory/distributed cache a value with a key "key"; if you do not find it, crate it with "factory" method and keep it in memory cache for 1 minute and in distributed cache for 5 minutes.

You can use it in your Controllers, Core/Domain or your Infrastructure (some of the stuff refers to Onion/Clean/whatever-name architecture). I do not think there is just one answer where to use it. Actually, there is - anywhere!

Improvements?

Add some CacheEntryOptions class for more fine-grained cache setup.
Add resilience for calls to distributed cache like retry with circuit breaker.
Allow more than one Distributed cache (Why dude? It's just more headache!).
Remove dependency on Logging as I just use it to write unit tests with less hustle.

Words of caution!

Since one of the toughest things in programming is caching, beware of all potential issues, like:

Memory pressure if you keep to many objects in cache that are big-ish
Large object heap, if your objects are >85k
Invalidation - I am not even thinking about it here, but you might need it.

Why I am not concerned about those in our use-case:

I am setting low Memory Cache Expiration (e.g. 10 minutes), so hardly I can come to memory pressure situation.
I know how big are my objects.
I setup Distributed Cache Expiration also to some time span that I know it will not require me to regret I do not have Invalidate method.

Know your stuff!

Comments, questions and suggestions are very much welcome!

Best regards,
Bojan

Azure DevOps YAML build for Mono Repository with multiple projects

Bojan Nikolić — Wed, 21 Aug 2019 23:34:30 +0000

I will show you how I setup the YAML build in Azure DevOps for our Mono repository that contains multiple (20-ish) Services that are part of one Product.

TL;DR;
Visit Git repository https://github.com/nikolic-bojan/azure-yaml-build
It contains a working sample of YAML build for 3 services.

Move to Mono repository

We have ~20 different Services (REST APIs), with a Gateway in front of them that routes calls to those services and orchestrations. You can call it micro-service architecture or not, but let's not get into that discussion now.

It was organized like this:

Each Service had it's own repository
Each Model NuGet (that contained shared request/response classes) for inter-service communication had it's repository

So, around 40 repositories and same number of Build definitions that were created and maintained. Plus, we did GitFlow as a small team. Nightmare!

When I finally got time, I know where we should go - Mono repository. I do not want to convince you it is for everybody, but if you are already (or on your way) there and need some help, keep on reading.

This is the short story how it was done.

New repository

Creating a new repository is easy, but what about moving the code? Copy/paste - no way, we lose all the Git history. I found a few good articles online and with a bit help of Sourcetree (I am not Git console guy. Yet) and Git console (you can't avoid it), here are the steps I did for each project. Of course, make sure you are in the new repository's master branch:

Add Remote repository in Sourcetree pointing to your old project's repository and call it repo
Execute following GIT command git merge repo/master --allow-unrelated-histories. Of course, chose to move from master or any other old repo's branch. Very important to use allow-unrelated-histories or it will not work.
Create in new repository a folder for your Service. You do not want to have all projects in same folder, right?
Move all files to a new folder.
Resolve conflicts, if any.
Push changes.
Lock old repository's branches to prevent some developer to continue working there.

If you have some feature branches (not all new code is on master), you can create new branch on a New Repository and just copy files from Old repository to that Service's folder. Git will figure that out like changes and you can push them. You will loose some commit history on that feature branch, but you can live with that.

This way I moved all my Services to a new repository, but after these 7 steps I also did few more related to Build definition for each Service. Do not rush into moving all at once. Move Service by Service.

Build definition changes

Everything is now in the same repository. Also, all Services are in their new folders. Now we come to the problem - we need to change our build definition, depending on how it was made, of course.

What I had to do is next:

Allowed trigger only on master and only for a folder where Service is. I just wanted to see builds work with the New Repository.
Change all the steps/variables that point to *.sln or *.csproj files to follow new folder structure in order to build just what you want, not the whole darn thing.
Try the build. Build Service, push it on some lower environment and hit it with regression tests. All needs to be in perfect order.
Now you can migrate next Service.

Model NuGets

Remember I was mentioning those? Those were simple .NET Standard 2.0 projects that contain just POCO models. I decided to move them to a Service's solution as they represent the interface for that Service.

All other Services that need them also (that call that Service) have them also referenced directly. It is the same Repository!

I wasn't trying there to keep the history. Copy/paste did the thing. But it is possible as we did with the Services.

Regressions were all green after this. That was the most important.

One Build to rule them all

I wasn't very happy with having build triggers only on master. I could have put triggers on all branches, but I wanted more control.

What if I wanted to build 2 or 3 Services when code in one changes (remember those Model projects?). I know, that is not clean separation, but after all, the point of having things in one repository is because they are - connected.

I wasn't keen on maintaining 20+ builds also. I wanted control in one place.

PowerShell + YAML to the resque!

It would be very nasty to setup CI through UI to know when to trigger and which Services to build. Yes, I said "Services", not Service. That is due to how I want things to work. If I make changes to several Services at once, I want all of them build. Sometimes if I make change to 1 Service, I want 2 of them to build.

Good thing is that all our Builds had same steps and we parameterized one build, so it can be easily cloned and specialized for particular Service using Variables.

First, create a new Build definition. You need to select YAML build. There you should enter following:

trigger:
  branches:
    include:
    - '*'

resources:
- repo: self

jobs:
- job: Build_Queue
  steps:  
  - task: powershell@2
    name: setBuildQueue
    inputs:
      targetType: filePath
      filePath: ./build/get-service-queue.ps1
    displayName: 'Get Service Build Queue'    

- template: build-template.yml
  parameters:
    name: Service_01
    solutionFolder: 'service1'
    projectFile: '/service1.api/service1.api.csproj'

- template: build-template.yml
  parameters:
    name: Service_02
    solutionFolder: 'service2'
    projectFile: '/service2.api/service2.api.csproj'

- template: build-template.yml
  parameters:
    name: Service_03
    solutionFolder: 'service3'
    projectFile: '/service3.api/service3.api.csproj'

# Add more template jobs with parameters for other Services

OK, what I just did was:

Set the trigger on all branches.
Set repository to itself.
Created a PowerShell Job to get list of services to build.
Defined to run build template for each of my services (here just 3)

What will happen is that a PowerShell Script will determine which services should be built (custom logic) and output that as a list of semi-colon (;) separated Service folder names (not perfect, still polishing that one, my PowerShell is beginner level).

$global:buildQueueVariable = ""
$global:buildSeparator = ";"

Function AppendQueueVariable([string]$folderName)
{
    $folderNameWithSeparator = -join($folderName, $global:buildSeparator)

    if ($global:buildQueueVariable -notmatch $folderNameWithSeparator)
    {
        $global:buildQueueVariable = -join($global:buildQueueVariable, $folderNameWithSeparator)
    }
}

if ($env:BUILDQUEUEINIT)
{
    Write-Host "Build Queue Init: $env:BUILDQUEUEINIT"
    Write-Host "##vso[task.setvariable variable=buildQueue;isOutput=true]$env:BUILDQUEUEINIT"
    exit 0
}

# Get all files that were changed
$editedFiles = git diff HEAD HEAD~ --name-only

# Check each file that was changed and add that Service to Build Queue
$editedFiles | ForEach-Object { 
    Switch -Wildcard ($_ ) {        
        "service1/*" { 
            Write-Host "Service 1 changed"
            AppendQueueVariable "service1"
        }
        "service2/*" { 
            Write-Host "Service 2 changed" 
            AppendQueueVariable "service2"
        }
        "service3/*" { 
            Write-Host "Service 3 changed" 
            AppendQueueVariable "service3"
            AppendQueueVariable "service2"
        }
        # The rest of your path filters
    }
}

Write-Host "Build Queue: $global:buildQueueVariable"
Write-Host "##vso[task.setvariable variable=buildQueue;isOutput=true]$global:buildQueueVariable"

This is the logic:

I first check if anyone set buildQueueInit variable on build. I want to have option to set which services to build manually. If yes, I set buildQueue output (very important to be output) variable and skip the part with GIT diff.
If buildQueueInit was not set, I will do GIT diff, pickup files that were changed in last commit and figure out in which folders they are, so I can make a list of changed Services. Then I set buildQueue output variable with that value.

That GIT diff magic was picked up from Taul's answer and gets all files that were changed in last commit
https://stackoverflow.com/questions/53227343/triggering-azure-devops-builds-based-on-changes-to-sub-folders/53837840#53837840

Build template

OK, last piece of the puzzle - Build template. I grabbed it by clicking on View YAML button of my existing build pipeline. Then I had to adjust it a bit. Here is how the first part of it looks (I just kept the Restore task for sample):

parameters:
    name: '--'
    BuildConfiguration: 'Release'
    BuildPlatform: 'any cpu'
    solutionFolder: '--'
    projectFile: '/Api/Api.csproj'
    RestoreBuildProjects: '$(project.file)'    

jobs:
- job: ${{ parameters.name }}
  dependsOn: Build_Queue
  continueOnError: true
  variables:
    BuildConfiguration: ${{ parameters.BuildConfiguration }}
    BuildPlatform: ${{ parameters.BuildPlatform }}
    project.file: ${{ parameters.solutionFolder }}${{ parameters.projectFile }}
    Parameters.RestoreBuildProjects: ${{ parameters.RestoreBuildProjects }}
    myBuildQueue: $[ dependencies.Build_Queue.outputs['setBuildQueue.buildQueue'] ]
  condition: and(succeeded(), contains(dependencies.Build_Queue.outputs['setBuildQueue.buildQueue'], '${{ parameters.solutionFolder }}'))
  steps:
  - task: powershell@2
    inputs:
      targetType: inline
      script: 'Write-Host "Build Queue init: $(buildQueueInit) and from parameters $(myBuildQueue)"'

  - task: DotNetCoreCLI@2
    displayName: Restore
    inputs:
      command: restore
      projects: '$(Parameters.RestoreBuildProjects)'

Parameters are input parameters for the template. You remember we used name and solutionFolder?

Variables are for the Job and we read some of the input parameters in order to set them up.

Important here is myBuildQueue that contains entire list of all Services that should be built.
Even more important is the condition that checks if this entire Job should be executed. It checks if solutionFolder is in that semi-colon separated list that was populated in that crazy PowerShell script.

If it matches - Tasks in this Job will be ran. If not, it will just skip this entire Job.

In the PowerShell script, you can define that Services have dependencies, so you can say that if there is a change in Service 3, you should also build Service 2. That is what I did for Service 3 in this part of the script.

Switch -Wildcard ($_ ) {
        "service3/*" { 
            Write-Host "Service 3 changed" 
            AppendQueueVariable "service3"
            AppendQueueVariable "service2"
        }

That is it! You can setup some interesting rules within the scripts in order to define what should be built on which change.

Now, you have just one Build to maintain!

Queue build manually with a list of Services to buils

Remember when I mentioned buildQueueInit and you setup a Variable. Here are the steps to do it in Azure DevOps:

Go to your Pipeline -> Builds and select your YAML build
Click to Edit build and you will see a button Variables
Click on it and then to + to create new one
Set it's name to buildQueueInit and check Let users override this value when running this pipeline box

Now, when you manually queue a build, you can add a value in it, e.g. service1;service2; and Service 1 and 2 will be built for you.

One scenario where you do want this is maybe for some Release branches, where you do not want stuff to be auto-triggered based on just last commit. You want to decide "those Services will be released after this Sprint".

Thanks for reading!

DEV Community: Bojan Nikolić

Your "Clean Architecture" is still layered!

Your code doesn't match your diagram

Then how to structure?

Encapsulate your component

Sample solution

nikolic-bojan / modularity

Sample solution showing how to organize code in Components/Modules, so we completely avoid layered approach.

Your "Clean Architecture" is still layered!

Final words

Handle errors with your convention in ASP.NET Core

Error handling

Some advises on property values

Sample responses

Log more information for diagnostics and alarming

Feedback

Log HttpClient request and response based on custom conditions in .NET Core

Delegating Handler

Show us the code!

Make SOAP requests using IHttpClientFactory in .NET Core

Problem and digging out the solution

Add SOAP service

Caveat #1

How to make SOAP client work with IHttpClientFactory

Caveat #2

Caveat #3

Final words

Ocelot Gateway with "auto-generated" Swagger

Initial state

Googling for the solution

Solution and Pros/Cons

Generate swagger.json for Ocelot

Swagger UI in new Ocelot Gateway

Azure DevOps build

Final words

Memory+Distributed Caching in .NET Core

Caching in Core

Best of both worlds

Show us the code!

nikolic-bojan / common-utilities

Common utilities that can be reused for any project

Memory+Distributed Caching in .NET Core

Memory cache

Distributed cache

Example

Improvements?

Words of caution!

Azure DevOps YAML build for Mono Repository with multiple projects

Move to Mono repository

New repository

Build definition changes

Model NuGets

One Build to rule them all

PowerShell + YAML to the resque!

Build template

Queue build manually with a list of Services to buils

Generate `swagger.json` for Ocelot