DEV Community: Rick Hopkins

Creating a Nuget Package From a .Net 6 class library

Rick Hopkins — Sat, 05 Nov 2022 17:10:30 +0000

Backstory...

Recently I was attempting to create a shareable library of code in C# to interact with a new enterprise document storage solution. The document storage solution essentially stored metadata about a document in an onprem database, but stored the document itself in Azure blob storage and kept a reference to the blob in our database. To interact with this service I created an pretty basic web api with just a few endpoints that did some CRUD operations. The api was secured using a client id / client secret provided by our Okta instance.

My main goal with this library, as with all shareable code I write, was to make it as simple as possible to implement the code and interact with the new document storage solution. The code behind this shareable library offered a quick configuration method that setup some services for dependency injection and a factory class that would retrieve those services for the developer, all the while handling authentication in the background so they didn't need to think about it too much. This code had the potential to be used by any group in our organization so simplicity was key as well as access.

I decided to create a nuget package of the code that we could host in our Azure artifacts nuget feed. If you don't know what a nuget package is, it is essentially a zip file with the .nupkg extension that contains compiled DLL files and any supporting files needed for the shared code.

I've created nuget packages before, but not in quite a while and it seemed like some things had changed since last time. After multiple google searches I was able to piece together something that worked very well to get a nuget package with .net 6, and thought I'd share here...

How To...

A couple requirements I had for the package:

It needs to be part build pipelines in Azure and get an automated build version.
It needs a README file that popups up in Visual Studio with documentation on how to use the code.

So first I created a nuspec file which is essentially a file that defines what needs to be in the package and some metadata about the package itself. It looks like this...

The parts I want you to take notice of are



<id>NHA.Document.Client</id>
<version>$version$</version>
...
<readme>README.md</readme>
<dependencies>...</dependencies>
<files>...</files>

The id field must be some unique id. If you were to publish this on https://www.nuget.org/ a unique ID is necessary.

The version is dynamic because of the $version$ parameter we will pass to it. More on that in a bit.

Dependencies are any other nuget packages that this code relies on. In this case I use Swashbuckle for some data annotations.

The files section is probably the most important. Here you must list out the files that are necessary for the actual usage of the client library. Any .dll, .pdb files that are compiled for this library must be listed here. Also, if you want to have a readme file popup upon installation you must list it here. The src value is just a file path to where the file exist. Since it is compiled code it will be placed in the bin subdirectory aligning with the .Net version you're on.

A note on README documentation.
I'm still a little confused on it, but I believe the case is that if you have a readme.txt file it will automatically popup upon installation. With a .txt file you are sort of limited in how nice you can make it look. If you want a nicely formatted markdown readme that displays on the nuget.org site when you publish it then you also need that file in the package and have it referenced in the tag of the nuspec file.

Once I created the nuspec file and saved it at the root of the client library as NHA.Document.Client.nuspec I was ready for the next step.

The next piece was to modify the .csproj file for the client library I was packaging. It looks like this...

The main part to take notice of is



<PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <NuspecFile>NHA.Document.Client.nuspec</NuspecFile>
    <NuspecProperties>version=$(PackageVersion)</NuspecProperties>
</PropertyGroup>

This section says where to get the .nuspec file definition for the packaage and sets up our $version$ variable. In our case we are going to get the version from the actual build id and pass it in when we use the dotnet pack command. More on that in just a sec...

There is another section below... but if I'm honest I don't for sure if it's necessary :) ... I don't remember adding this and I am unsure how it got there... either way here it is.



<ItemGroup>
    <None Update="README.md">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <Pack>True</Pack>
      <PackagePath>\</PackagePath>
    </None>
</ItemGroup>

With that we are ready to pack it up with the "dotnet pack" command. We need to point the pack command at the csproj and pass some additional arguments.



dotnet pack NHA.Document.Client.csproj  -p:PackageVersion=2.0.5 -c Release

If I run this command at the root of the client project it will find the csproj file which then points to the nuspec file. Using the -p: command we can pass in variable values. In this case we pass in a version number. The -c command is for the build configuration to use, in this case I use Release. You can run this from the command line if you have dotnet installed or include it in your build yml files. In my case the command in my yml files looks like this...



--target=pack --build-arg VERSION="$(Build.BuildNumber)"

Using this command gets the build number from the build and that becomes our package version. Our build pipeline kicks off automatically every time we PR to the main branch.

Conclusion

So there it is... how I build nuget packages from a dotnet 6 class library. Probably not terribly exciting to many, but I know when I was working on it I did a lot of google searching and trial and error some hopefully this helps anyone else trying to do the same thing.

Above All Else... Take Care Of Your Mental Health

Rick Hopkins — Sat, 10 Sep 2022 19:51:50 +0000

It can feel like drowning. Like there's no air.

A couple years ago I was sitting in a meeting a couple fellow developers and a product owner. I was there because my time and experience it was thought would give valuable feedback to an upcoming project. At one point I was asked a question by the product owner and as I started to answer I began to feel like my heart was pounding and racing in my chest. I got short of breathe and had to actually ask to be excused about mid-sentence.

I had no idea what was going on but my heartrate had climbed to over 160 bpm at a sit still. I was sweating and panicked. I went outside and began walking around our companies property. One lap is a little less than half a mile or so.

I did 7 laps.

My heart was still going pretty quick at the end of this so I thought I may want to call a doctor and see if I should come in. I called my main physician and they said they actually had an opening right then to come in so I left work and went to the doctors office.

I waited a short amount of time and was called back. They took my pulse and it was still over 160bpm and my blood pressure was skyrocket high. They decided to hook me up to an EKG machine. The doctor came in and looked at the readings on the paper and got a concerned look on her face. She decided to run it again. The second time she got the same look of concern and walked out of the room. She came back in a few minutes later and said, "Mr. Hopkins I'd like you to lay down and take this pill. I've already called an ambulance. We think you could have a blockage in your heart."

I was 40 years old. Way too young for something like this to be happening.

I called my wife quick before the ambulance got there and said to her something that felt surreal to say... "they think I'm having a heart attack". She was understandably concerned but had to run around and pick up kids and figure out how she was going to get them all watched and taken care of before coming to the hospital with me.

The ambulance arrived and they strapped me to a gurney like I was about to compete in a nascar race. They loaded me up and away we went.

The first indication that it may not be as bad as I thought was that the ambulance was not speeding. There were no lights on. They were just driving me to a hospital. The EMT that was tending to me seemed like he'd seen this a thousand times and knew what it was, though he really didn't say much. But his demeanor did calm me greatly in what was one of the scariest moments of life up until that point.

We arrived at the hospital and they wheeled me to a room and the doctors and nurses began running all sorts of tests and hooking me up to monitors. At one point I had a real emotional release because of the panic and dread that had come over me at the thought of having a heart attack... what if I died? What if my kids grew up with out a dad? What if my wife had to go on without me? What was going to happen to me?

But it wasn't a heart attack. Every test they ran came back normal and the only real concern they had, if you could even call it that, was for my blood pressure which was very high. So what was it?

It was a massive panic attack.

I'd been having a lot of signs and symptoms of anxiety leading up this and I'd struggled with depression for years. Shortly before this I had torn my ACL and had to get surgery and it just made me feel old. I have six kids, a wife, a house, two dogs, bills, taxes, etc. My job had been very stressful for a long time. For years I didn't actually enjoy being a software engineer. I wanted to be a professionl touring musician... For real. I write music and I don't think it's half bad. Here's an example. You can also find me on spotify. But I digress...

So for years, I hadn't tended to my mental health. I'd let it go thinking I can just muscle through the depression and anxiety. I wasn't really eating well, exercising much, or doing any sort of mindfulness practices. Stress built on top of stress. Things shifted at my job that actually caused me to enjoy being a developer more than I ever had, however it also meant more responsibility and more eyes on me... at least in my head it did. In reality, the pressure was all self imposed because of past struggles with imposter syndrome. I didn't want to look like I didn't know what I was talking about. I didn't want everyone to find out how much of a phony I was. So says the voice in my head.

Not sure if you've been there, but all this kept building until that day in the meeting room where I was asked one simple question and suddenly I felt like I was drowning and couldn't breath.

The point of this whole post is this. Above all else, as a software engineer or any other profession really... take care of your mental health.

Failing to take notice of the warning signs of anxiety and depression, or not taking them seriously will get you right where I was. Burnt out, dreading getting out of bed in the morning, feeling like you are literally dying, stressed out at the most minor of things, and treating those you love with less patience, compassion, and empathy.

If you feel these things happening to you, please reach out to a friend, to a counselor, your employer, or even to me. I'll listen. Especially you men out there. It's hard for us to talk about what is going on inside of us. I get it. You don't want to appear weak. Well, you can talk about it in private conversation with someone, or you can have a public melt down... Which would you rather?

There were a few key factors in my recovery. First off, my family is amazing and supportive. Secondly, the company I work, at least for me at that time, was great at recognizing that I needed a little time and space and they gave it to me. They allowed me a little more grace in sick days and needing to take some mental health time. They were very understanding and I fully realize that not everyone has that situation. I would challenge you that if you work for a company that doesn't have that type of concern for it's employees that you find another place to work that does. Especially in the realm of software development at this time there are plenty of companies looking for software engineers.

The final key in my recovery was looking out for my own mental, physical, emotional, and spiritual health. I changed my diet and started eating better. I started to practice meditation. I began exercising regularly. Nothing crazy really. I work out doing body weight exercises 4-5 times a week for roughly 20-30 minutes. I also try to get outside for walks and doing yard work. For a while after the ambulance ride I was having panic attacks on the regular so I did end up going on a medication called lexapro. I had put sort of a major stigma on using medication up until this point, but when I couldn't seem to get it under control and realized I needed help, I talked to my doctor and this was suggested. I can't tell you how much better I felt after a month of taking lexapro. It was like I had come out of a 10 year fog. I was calmer, less depressed and less anxious. I'm not suggesting everyone should go on meds, but it sure helped me get over the hump. I still take it today and think often about weaning myself off, but haven't yet. I'm not in a rush.

Now that my mental health is at least in a more stable place, it has renewed my desire to be the best I can be in every area of life. As a father, husband, friend, co-worker, mentor, neighbor, software engineer, etc.

I still have struggles and I'm not saying all of life is perfect... but for the love of self, above all else, take care of your mental health.

VS Code Extension Development: Azure Work Management

Rick Hopkins — Mon, 13 Sep 2021 23:30:12 +0000

The Idea

As a principal software engineer I probably spend 80% of my day inside VS Code writing lots of TypeScript / JavaScript, CSS, HTML, and C#. Occasionally a little PHP gets thrown in there, but not nearly as much these days. I love VS Code. It is by far my favorite development tool. The extensibility of it allows me to stay inside one tool for just about anything I need to do. However, there was one piece that was missing for me. Our company has adopted Azure DevOps for task and work management. We generally use the kanban boards feature to track work through different stages of completion. I couldn't find a good extension for handling Azure DevOps work items. So, after reading the July / August 2021 edition of Code magazine and ruminating on my need for a work item management tool in VS Code, I decided to build my own.

Side note: Code Magazine is really pretty great. They have good articles and well written tutorials occasionally like the ones in this issue.

Azure Work Management

So if you also are looking for a VS Code extension to handle working with boards / columns / work items in Azure DevOps, look no further...

https://marketplace.visualstudio.com/items?itemName=MelodicDevelopment.azure-work-management

The basic idea behind the extension was to get a minimal amount of functionality right inside of VS Code so I don't have to leave the tool to do the few main tasks I usually have to perform:

Read the work item description
Assign the work item to myself or someone else
Move the work item to a different column
Open the work item inside Azure DevOps for full functionality.

The extension adds a side bar menu with the Azure DevOps icon that when opened up will display at tree view with your available boards. You can expand each board to display the columns, and expand the columns to display the work items. There is a small amount of configuration like getting a personal access token from Azure DevOps, then setting configuration settings for the organization, project, team and iteration. The iteration has a helper command that will display a list of iterations and help you find the current one.

The Source

If you're interested in the source code you can visit my GitHub repository for the extension at https://github.com/MelodicDevelopment/azure-work-management.

I learned a ton about developing VS Code extensions from writing this one and I'd love to see people get some use out of it. As far as how I created it I'd rather point you to the Code magazine article that I based a lot of my ideas on. They created a Vue application which is not what I ended up doing, but the article itself helps you get started. If you have further questions about my particlar extension, or suggestions for improvement I'd love to hear them.

Email me at rick.hopkins@gmail.com or catch me on twitter at @melodicdev.

Thanks for checking it out!

Unit & Integration Testing In .Net With Moq and xUnit

Rick Hopkins — Sun, 15 Aug 2021 18:10:54 +0000

NOTE: This post was originally posted on Melodic Development. The Melodic Development dev.to site is operated by Rick Hopkins. Rick is a Principal Software Engineer at NHA.

Testing In .Net with xUnit & Moq

Today I want to cover some simple testing setup and configuration. I'll be using my example project from the Dapper & CQRS post I made last week so consider this post a part 2. For tooling I'll be using xUnit and Moq as well as a few other nuget packages to easily configure and run tests in Visual Studio. I am working on a Mac, but operating system shouldn't matter.

We all know we should be testing our code. The company I work for has been woefully bad at it for years, but we have been working lately at developing a testing strategy and we're making great strides in this area. Moq and xUnit make testing pretty easy and allow us to catch some bugs early. Dare I even say, testing could possibly even become enjoyable...?

Ok so maybe fun is a stretch, but it's still important. So let's get started shall we!

Code

You can get all the source code for this example at https://github.com/MelodicDevelopment/example-dotnet-api-cqrs.

Tests

The dotnet-api-cqrs.tests project contains (simplistic) examples for doing integration as well as unit testing. This is pretty geared towards our particular Dapper / CQRS pattern, however it could be useful for other patterns as well.

One thing to take note is that we configured our tests to run against an actual database. You can mock data if you'd like, but we chose to run our queries and commands against our CI database. This gives us the added bonus of testing to ensure database changes have not occurred that would break our code. The queries will run as expected against the database, however commands are all rolled back so that nothing is actually committed to the database. To achieve this, we've created a TestDbContext which is based on our DbContext from the dotnet-api-cqrs.data project. The TestDbContext extends and overwrites most the virtual methods on the DbContext class. This way we can differentiate between queries and commands and for commands we have an addition setting to rollback comamnds. This will attempt to execute the command, but not actually commit any changes to the database. This way we get to see if any errors happen in the command without actually affecting the database. We can catch whatever exceptions the database throws, such as duplicate key errors, or unique key exceptions.

dotnet-api-cqrs.tests/TestDbContext.cs

using System;
using System.Collections.Generic;
using System.Data;
using dotnet_api_cqrs.data;

namespace dotnet_api_cqrs.tests
{
    public class TestDbContext : DbContext
    {
        private readonly bool _noCommit;
        private bool _isQuery;

        public TestDbContext(string connectionString, bool noCommit = false) : base(connectionString)
        {
            _noCommit = noCommit;
        }

        public override IEnumerable<T> Query<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null)
        {
            _isQuery = true;
            return base.Query<T>(query, param, commandType, transaction);
        }

        public override T QueryFirst<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null)
        {
            _isQuery = true;
            return base.QueryFirst<T>(query, param, commandType, transaction);
        }

        public override int InsertSingle(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null)
        {
            _isQuery = false;
            return base.InsertSingle(sql, param, commandType, transaction, timeout);
        }

        public override int Command(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null)
        {
            _isQuery = false;
            return base.Command(sql, param, commandType, transaction, timeout);
        }

        public override T Transaction<T>(Func<IDbTransaction, T> query)
        {
            if (!_noCommit || _isQuery) {
                _isQuery = false;
                return base.Transaction(query);
            } else {
                _isQuery = false;

                using var connection = Connection;
                using var transaction = BeginTransaction();

                try {
                    var result = query(transaction);
                } catch (Exception) {
                    throw;
                }

                transaction.Rollback();

                return default;
            }
        }

        public override void Transaction(Action<IDbTransaction> query)
        {
            if (!_noCommit || _isQuery) {
                _isQuery = false;
                base.Transaction(query);
            } else {
                _isQuery = false;

                using var connection = Connection;
                using var transaction = BeginTransaction();

                try {
                    query(transaction);
                } catch (Exception) {
                    throw;
                }

                transaction.Rollback();
            }
        }

        ~TestDbContext()
        {
            Dispose();
        }
    }
}

So our tests are against a real live database... but not our production database. We're testing it live, but not really live... and we don't commit. So... it all works out right? Seems to be working for us.

Required Nuget Packages

If you view the nuget package manager in Visual Studio you can see which packages are required for this, but in short they are:

Moq
xUnit
xUnit.Runner.VisualStudio
Microsoft.AspNetCore.Mvc.Testing
Microsoft.AspNetCore.TestHost
Microsoft.NET.Test.Sdk

Unit Tests

For unit tests we'll look at how we tested on of our queries and one of our commands. To make sure we were using the correct TestDbContext I created a base class that all our unit tests extend. It's called TestBase. It news up a TestDbContext and allows for passing in a noCommit flag. This flag prevents commands from being committed to the database.

dotnet-api-cqrs.tests/TestBase.cs

using dotnet_api_cqrs.contracts.data;

namespace dotnet_api_cqrs.tests
{
    public abstract class TestBase
    {
        private readonly bool _noCommit;

        protected readonly IDbContext TestDbContext;

        public TestBase(bool noCommit = false)
        {
            _noCommit = noCommit;

            TestDbContext = new TestDbContext($"use-configuration-to-get-connection-string", _noCommit);
        }
    }
}

dotnet-api-cqrs.tests/Data/Book/BookQueryTests.cs

using dotnet_api_cqrs.data.Queries.Book;
using Xunit;

namespace dotnet_api_cqrs.tests.Data.Book
{
    public class BookQueryTests : TestBase
    {
        [Fact]
        public void GetAllBooksTest()
        {
            var query = new GetAllBooksQuery();
            var results = query.Execute(TestDbContext);

            Assert.NotEmpty(results);
        }

        [Theory]
        [InlineData(1)]
        public void GetBookByIDTest(int bookID)
        {
            var query = new GetBookQuery(bookID);
            var results = query.Execute(TestDbContext);

            Assert.NotNull(results);
        }


        [Theory]
        [InlineData(1)]
        public void GetBookForAuthorTest(int authorID)
        {
            var query = new GetBooksForAuthorQuery(authorID);
            var results = query.Execute(TestDbContext);

            Assert.NotNull(results);
        }
    }
}

In the BookQueryTests.cs file you will see multiple tests that can be run. These are 2 simplistic tests that will test all three of our queries you can find in the dotnet-api-cqrs.data project. xUnit allows for a couple method attributes. The first one is Fact and this one simply runs the test with no parameters. The Theory attribute allows for one more attribute called InlineData. In the InlineData attribute you can pass arguments which will then be passed to the test method. You can see this working in the GetBookByIDTest test method. Again, this is a very simplistic test and we just pass a 1 which indicates the book ID to search for. These tests can be written to be much more complex and test various scenarios with much more complicated test data. We won't get into that here for sake of time, but go check out their documentation and do some google searching. There's lots of good stuff out there to help write more complex and stringent unit tests.

Using Moq To Test A Service

Moq allows you to very easily setup a mock object that can be used inside your unit tests. For another simple and basic example we have our BookServiceTests.cs file. This again extends the TestBase class and uses Moq to create a mock object of the IBookFacade which the BookService is expecting as a constructor argument. In this example, we create a mock of IBookFacade, and configure it so that when the GetBooks method is called we pass back some test data. This way when the BookService calls the GetBooks method on the facade it will get some test data and perform whatever business logic we have. Then we can test the result.

dotnet-api-cqrs.tests/Services/BookServicesTests.cs

using dotnet_api_cqrs.contracts.data;
using dotnet_api_cqrs.data;
using dotnet_api_cqrs.services;
using Moq;
using Xunit;

namespace dotnet_api_cqrs.tests.Services
{
    public class BookServicesTests : TestBase
    {
        [Fact]
        public void GetAllBooksTest()
        {
            var mockFacade = new Mock<IBookFacade>();
            mockFacade.Setup(repo => repo.GetBooks())
                .Returns((context, transaction) => {
                    return TestData.Books;
                });

            var bookService = new BookService(TestDbContext, mockFacade.Object);

            Assert.NotEmpty(bookService.GetAllBooks());
        }
    }
}

Integration Tests

We can also use xUnit and the Microsoft.AspNetCore.Mvc.Testing nuget package to run integration tests. These integration tests will setup a virtual web server in memory, run the api project on that virtual server, and then hit the endpoints to test them from the api endpoint down to the database query or command and return any issues along the way.

The first piece we need is called the WebApplicationFactory. The Mvc.Testing package supplies this base class and we just extend it a little bit so that we can overwrite our default IDbContext dependency injection with the TestDbContext.

dotnet-api-cqrs.tests/api/ApiQueryTestApplicationFactory.cs

using dotnet_api_cqrs.contracts.data;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.AspNetCore.TestHost;
using Microsoft.Extensions.DependencyInjection.Extensions;

namespace dotnet_api_cqrs.tests.Api
{
    public class ApiQueryTestApplicationFactory<TStartup> : WebApplicationFactory<TStartup> where TStartup: class
    {
        protected override void ConfigureWebHost(IWebHostBuilder builder)
        {
            base.ConfigureWebHost(builder);

            builder.ConfigureTestServices(services => {
                services.RemoveAll<IDbContext>();
                services.TryAddScoped<IDbContext>(sp => new TestDbContext($"use-configuration-to-get-connection-string"));
            });
        }
    }
}

This particular factory class is for testing queries. We have a separate one that will test when commands are being run. These are rather simplistic tests I realize and we're still working on a solid strategry for testing more complex business logic that will run both commands and queries in one pass, but this should get you started anyway.

Now if you look at the BookControllerQueryTests file you can see one more test where we hit the end point on the BookController that returns all books. In this particular test we are simply testing that the call was made succesfully.

dotnet-api-cqrs.tests/Api/Controllers/BookControllerQueryTests.cs

using System.Net.Http;
using System.Threading.Tasks;
using dotnet_api_cqrs.api;
using Xunit;

namespace dotnet_api_cqrs.tests.Api.Controllers
{
    public class BookControllerTests : IClassFixture<ApiQueryTestApplicationFactory<Startup>>
    {
        private readonly ApiQueryTestApplicationFactory<Startup> _factory;
        private readonly HttpClient _httpClient;

        public BookControllerTests(ApiQueryTestApplicationFactory<Startup> factory)
        {
            _factory = factory;
            _httpClient = _factory.CreateClient();
        }

        [Fact]
        public async Task GetBooks_IsSuccessful()
        {
            var response = await _httpClient.GetAsync($"/api/book");

            response.EnsureSuccessStatusCode();
            Assert.True(response.IsSuccessStatusCode);
        }
    }
}

Conclusion

So again, this was a rather simplistic look at unit and integration testing using xUnit and Moq, but I hope it gets you started on the road to more thorough and complex testing in your own code to ensure you are creating the best products you can.

Please let me know if the comments your thoughts.

Unit & Integration Testing In .Net With Moq and xUnit

Rick Hopkins — Sun, 15 Aug 2021 02:38:27 +0000

Testing In .Net with xUnit & Moq

Ok so maybe fun is a stretch, but it's still important. So let's get started shall we!

Code

You can get all the source code for this example at https://github.com/MelodicDevelopment/example-dotnet-api-cqrs.

Tests

dotnet-api-cqrs.tests/TestDbContext.cs

using System;
using System.Collections.Generic;
using System.Data;
using dotnet_api_cqrs.data;

namespace dotnet_api_cqrs.tests
{
    public class TestDbContext : DbContext
    {
        private readonly bool _noCommit;
        private bool _isQuery;

        public TestDbContext(string connectionString, bool noCommit = false) : base(connectionString)
        {
            _noCommit = noCommit;
        }

        public override IEnumerable<T> Query<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null)
        {
            _isQuery = true;
            return base.Query<T>(query, param, commandType, transaction);
        }

        public override T QueryFirst<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null)
        {
            _isQuery = true;
            return base.QueryFirst<T>(query, param, commandType, transaction);
        }

        public override int InsertSingle(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null)
        {
            _isQuery = false;
            return base.InsertSingle(sql, param, commandType, transaction, timeout);
        }

        public override int Command(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null)
        {
            _isQuery = false;
            return base.Command(sql, param, commandType, transaction, timeout);
        }

        public override T Transaction<T>(Func<IDbTransaction, T> query)
        {
            if (!_noCommit || _isQuery) {
                _isQuery = false;
                return base.Transaction(query);
            } else {
                _isQuery = false;

                using var connection = Connection;
                using var transaction = BeginTransaction();

                try {
                    var result = query(transaction);
                } catch (Exception) {
                    throw;
                }

                transaction.Rollback();

                return default;
            }
        }

        public override void Transaction(Action<IDbTransaction> query)
        {
            if (!_noCommit || _isQuery) {
                _isQuery = false;
                base.Transaction(query);
            } else {
                _isQuery = false;

                using var connection = Connection;
                using var transaction = BeginTransaction();

                try {
                    query(transaction);
                } catch (Exception) {
                    throw;
                }

                transaction.Rollback();
            }
        }

        ~TestDbContext()
        {
            Dispose();
        }
    }
}

Required Nuget Packages

If you view the nuget package manager in Visual Studio you can see which packages are required for this, but in short they are:

Moq
xUnit
xUnit.Runner.VisualStudio
Microsoft.AspNetCore.Mvc.Testing
Microsoft.AspNetCore.TestHost
Microsoft.NET.Test.Sdk

Unit Tests

dotnet-api-cqrs.tests/TestBase.cs

using dotnet_api_cqrs.contracts.data;

namespace dotnet_api_cqrs.tests
{
    public abstract class TestBase
    {
        private readonly bool _noCommit;

        protected readonly IDbContext TestDbContext;

        public TestBase(bool noCommit = false)
        {
            _noCommit = noCommit;

            TestDbContext = new TestDbContext($"use-configuration-to-get-connection-string", _noCommit);
        }
    }
}

dotnet-api-cqrs.tests/Data/Book/BookQueryTests.cs

using dotnet_api_cqrs.data.Queries.Book;
using Xunit;

namespace dotnet_api_cqrs.tests.Data.Book
{
    public class BookQueryTests : TestBase
    {
        [Fact]
        public void GetAllBooksTest()
        {
            var query = new GetAllBooksQuery();
            var results = query.Execute(TestDbContext);

            Assert.NotEmpty(results);
        }

        [Theory]
        [InlineData(1)]
        public void GetBookByIDTest(int bookID)
        {
            var query = new GetBookQuery(bookID);
            var results = query.Execute(TestDbContext);

            Assert.NotNull(results);
        }


        [Theory]
        [InlineData(1)]
        public void GetBookForAuthorTest(int authorID)
        {
            var query = new GetBooksForAuthorQuery(authorID);
            var results = query.Execute(TestDbContext);

            Assert.NotNull(results);
        }
    }
}

Using Moq To Test A Service

dotnet-api-cqrs.tests/Services/BookServicesTests.cs

using dotnet_api_cqrs.contracts.data;
using dotnet_api_cqrs.data;
using dotnet_api_cqrs.services;
using Moq;
using Xunit;

namespace dotnet_api_cqrs.tests.Services
{
    public class BookServicesTests : TestBase
    {
        [Fact]
        public void GetAllBooksTest()
        {
            var mockFacade = new Mock<IBookFacade>();
            mockFacade.Setup(repo => repo.GetBooks())
                .Returns((context, transaction) => {
                    return TestData.Books;
                });

            var bookService = new BookService(TestDbContext, mockFacade.Object);

            Assert.NotEmpty(bookService.GetAllBooks());
        }
    }
}

Integration Tests

dotnet-api-cqrs.tests/api/ApiQueryTestApplicationFactory.cs

using dotnet_api_cqrs.contracts.data;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.AspNetCore.TestHost;
using Microsoft.Extensions.DependencyInjection.Extensions;

namespace dotnet_api_cqrs.tests.Api
{
    public class ApiQueryTestApplicationFactory<TStartup> : WebApplicationFactory<TStartup> where TStartup: class
    {
        protected override void ConfigureWebHost(IWebHostBuilder builder)
        {
            base.ConfigureWebHost(builder);

            builder.ConfigureTestServices(services => {
                services.RemoveAll<IDbContext>();
                services.TryAddScoped<IDbContext>(sp => new TestDbContext($"use-configuration-to-get-connection-string"));
            });
        }
    }
}

dotnet-api-cqrs.tests/Api/Controllers/BookControllerQueryTests.cs

using System.Net.Http;
using System.Threading.Tasks;
using dotnet_api_cqrs.api;
using Xunit;

namespace dotnet_api_cqrs.tests.Api.Controllers
{
    public class BookControllerTests : IClassFixture<ApiQueryTestApplicationFactory<Startup>>
    {
        private readonly ApiQueryTestApplicationFactory<Startup> _factory;
        private readonly HttpClient _httpClient;

        public BookControllerTests(ApiQueryTestApplicationFactory<Startup> factory)
        {
            _factory = factory;
            _httpClient = _factory.CreateClient();
        }

        [Fact]
        public async Task GetBooks_IsSuccessful()
        {
            var response = await _httpClient.GetAsync($"/api/book");

            response.EnsureSuccessStatusCode();
            Assert.True(response.IsSuccessStatusCode);
        }
    }
}

Conclusion

Please let me know if the comments your thoughts.

Dapper & CQRS

Rick Hopkins — Thu, 12 Aug 2021 20:18:43 +0000

NOTE: This post was originally posted on Melodic Development. The Melodic Development dev.to site is operated by Rick Hopkins. Rick is a Principal Software Engineer at NHA.

Introduction

In 2016 NHA launched a major rewrite of our main software suite. We are an education company and so the software included everything that a school administration or teacher would need from grade book, attendance, curriculum, assessment, behavior, scheduling. It was really a pretty big success. Teachers and administrative officials seemed to enjoy the software and see it as a large step forward. We were all very proud. In time though, the shine wore off. The common complaints we began to get were that user interfaces were confusing, buggy and hard to navigate and that the system was slow.

As we began to investigate the slowness we noticed that data calls to the various apis were quite slow. Sometime in late 2018 we began to look into ways to speed up the data calls to our api. This was about the time that .Net Core 2.0 had come out, but we were currently using .Net 4.5.3. So instead of reworking currently existing APIs we decided to start from scratch with a new API layer written completely in .Net Core.

I know... I know... We can debate the rightness or wrongness of this decision to start from scratch. To save us all time lets just move onto what we ended up doing with the new stack.

The "legacy stack" as it came to be known was written in .Net 4.5.3 using Entity Framework and the classic repository / unit of work pattern. As we worked with Entity Framework Core in .Net Core we found that we were not improving our query speeds. They were still slow. Usually in the area of 250ms on up based on the query. Entity Framework wasn't going to cut it for this "new stack" code. We decided to try Dapper. Along with Dapper we decided to adopt a different pattern with how our back end code would be structured and data would be delivered. After reading quite a bit about CQRS (Command Query Responsibility Segregation) and finding some great examples online we settled on this pattern. This article in particular was very useful. Though we didn't follow it exactly, we stole quite a few ideas from it.

The rest of this article is a walk through an example of how we setup our API code now and the patterns we follow.

Code

You can get all the source code for this example at https://github.com/MelodicDevelopment/example-dotnet-api-cqrs. We can debate the organization of the code another time. I was trying to get an example up pretty quick. This is however pretty close to what we follow on my team.

If you run the API project you will be brought to a swagger page that documents the simple API I created for this example.

Contracts

The contracts project contains all the interfaces and DTOs for the solution. The example DTOs are Author and Book. Since we decided to follow the CQRS pattern our database queries and commands are separated into separate classes. Queries are based on the IQuery interface.

dotnet-api-cqrs.contracts/data/IQuery.cs

using System.Data;

namespace dotnet_api_cqrs.contracts.data
{
    public interface IQuery<T>
    {
        string Sql { get; set; }

        T Execute(IDbContext context, IDbTransaction transaction = null);
    }
}

Commands are based upon the ICommand interface. ICommand is a simple extension of the IQuery interface with a generic type of int since all commands return an integer.

dotnet-api-cqrs.contracts/data/ICommand.cs

namespace dotnet_api_cqrs.contracts.data
{
    public interface ICommand : IQuery<int> { }
}

The IDbContext is our database connection class that will execute our queries and commands. The implementation is in the data project so we'll talk more about that later.

dotnet-api-cqrs.contracts/data/IDbContext.cs

using System;
using System.Collections.Generic;
using System.Data;

namespace dotnet_api_cqrs.contracts.data
{
    public interface IDbContext : IDisposable
    {
        T QueryFirst<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null);
        IEnumerable<T> Query<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null);
        int InsertSingle(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null);
        int Command(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null);
        T Transaction<T>(Func<IDbTransaction, T> query);
        void Transaction(Action<IDbTransaction> query);
    }
}

You're going to notice some interfaces that include the name facade as well. Each facade inteface defines methods that return Func or Action delegates. More on these when we talk about the data project.

Data: Commands & Queries

The data project is where you're going to see most of the organization around our data access layer. The first two folders are for commands and queries, and inside each folder is a sub folder for each DTO. Inside the DTO folder you will see query classes. Each query is named for what it does. For example:

GetAllBooksQuery
GetBookQuery

It's not hard to determine what these queries do. Let's look at the GetAllBooksQuery.

dotnet-api-cqrs.data/Queries/Book/GetAllBooksQuery.cs

using System.Collections.Generic;
using System.Data;
using dotnet_api_cqrs.contracts.data;
using D = dotnet_api_cqrs.contracts.dto;

namespace dotnet_api_cqrs.data.Queries.Book
{
    public class GetAllBooksQuery : IQuery<IEnumerable<D.Book>>
    {
        public string Sql { get; set; }

        public GetAllBooksQuery()
        {
            Sql = @$"
SELECT              BookID,
                    Title,
                    CopyRightYear,
                    AuthorID
FROM                dbo.Books
ORDER BY            Title";
        }

        public IEnumerable<D.Book> Execute(IDbContext context, IDbTransaction transaction = null)
        {
            return context.Query<D.Book>(Sql, transaction: transaction);
        }
    }
}

The GetAllBooksQuery class implements the IQuery> interface. When we want to execute it we pass in the IDbContext to the Execute method. Pretty straightforward. Now lets look at the InsertBookCommand class.

dotnet-api-cqrs.data/Commands/Book/InsertBookCommand.cs

using System.Data;
using dotnet_api_cqrs.contracts.data;
using D = dotnet_api_cqrs.contracts.dto;

namespace dotnet_api_cqrs.data.Commands.Book
{
    public class InsertBookCommand : ICommand
    {
        private readonly D.Book _book;

        public string Sql { get; set; }

        public InsertBookCommand(D.Book book)
        {
            _book = book;

            Sql = $@"
INSERT INTO         dbo.Books
                    (Title, CopyRightYear, AuthorID)
VALUES              (@Title, @CopyRightYear, AuthorID);";
        }

        public int Execute(IDbContext context, IDbTransaction transaction = null)
        {
            var param = new {
                Title = _book.Title,
                CopyRightYear = _book.CopyRightYear,
                AuthorID = _book.AuthorID
            };

            return context.InsertSingle(Sql, param, transaction: transaction);
        }
    }
}

This class will take in the book parameter, setup the sql parameters, and then execute them with the IDbContext. The InsertSingle method will actually return the new Book and return it's new ID.

Data: Facades

When we originally started developing with this pattern we began using the queries and commands directly in our services without setting them up for injection. We simply did new GetAllBooksQuery() right in the code in the services. This proved hard to test. So to solve this problem we decided to use facades. Facades simply group together related queries and commands for a DTO or logical group of DTOs. Another challenge we wanted to try and solve between the services and the facades was the ability to use read / write database contexts. So we adopted the pattern of always returning a function delegate from the facade methods. To make this easier we created a Facade base class with some methods to use in the child classes. If we want to return a value from the query or command we use the Func delegate. If we don't need a return value from the query or command we use the Action delegate. Each function delegate takes in an IDbContext and a possible IDbTransaction. This allows us to pass in possibly different contexts to execute the query or command. Passing in a transcaction allows us to perform multiple database actions in the same transaction. The DbContext is setup to run every query and command within a transaction. You can also use the Transaction method in the DbContext to create your own transaction to perform multiple database actions.

dotnet-api-cqrs.data/Facade.cs

using System;
using System.Data;
using dotnet_api_cqrs.contracts.data;

namespace dotnet_api_cqrs.data
{
    public class Facade
    {
        protected Func<IDbContext, IDbTransaction, T> Prepare<T>(IQuery<T> queryCommand)
        {
            return (context, transaction) => {
                return queryCommand.Execute(context, transaction);
            };
        }

        protected Action<IDbContext, IDbTransaction> Prepare(ICommand command)
        {
            return (context, transaction) => {
                command.Execute(context, transaction);
            };
        }
    }
}

The BookFacade is a straightforward example of what a facade looks like in practice. Again, facades don't contain any business logic. They simply allow us to group queries and commands related to a DTO or logical grouping of DTOs.

using System;
using System.Collections.Generic;
using System.Data;
using dotnet_api_cqrs.contracts.data;
using dotnet_api_cqrs.contracts.dto;
using dotnet_api_cqrs.data.Commands.Book;
using dotnet_api_cqrs.data.Queries.Book;

namespace dotnet_api_cqrs.data
{
    public class BookFacade : Facade, IBookFacade
    {
        public Func<IDbContext, IDbTransaction, IEnumerable<Book>> GetBooks()
        {
            return Prepare(new GetAllBooksQuery());
        }

        public Func<IDbContext, IDbTransaction, Book> GetBook(int bookID)
        {
            return Prepare(new GetBookQuery(bookID));
        }

        public Func<IDbContext, IDbTransaction, IEnumerable<Book>> GetBooksForAuthor(int authorID)
        {
            return Prepare(new GetBooksForAuthorQuery(authorID));
        }

        public Func<IDbContext, IDbTransaction, int> InsertBook(Book book)
        {
            return Prepare<int>(new InsertBookCommand(book));
        }

        public Action<IDbContext, IDbTransaction> DeleteBook(int bookID)
        {
            return Prepare(new DeleteBookCommand(bookID));
        }
    }
}c#

Services

The services project is where we put any business logic that needs to happen. One thing we found when we went with Dapper and CQRS was that a lot of business logic was taken care of by the fact that we were retrieving exactly what we wanted from the database. We didn't have an entity to represent each table in the database and a repository to work with that entity. We only took the columns we wanted and we could do simple table joins to create our business models exactly as we wanted them without all the boilerplate of Entity Framework and the repository pattern. Our actual code has methods to execute stored procedures and return multiple datasets, but I didn't include that here for simplicity's sake. So in the end our services look pretty trim usually, but they do serve as the place where business logic happens. The services all extend a base Service class that can take in multiple database contexts for reading and writing. We inject our facades here into the services. For this particular example I'm only using one context that does all reading and writing.

dotnet-api-cqrs.services/BookService.cs

using System.Collections.Generic;
using dotnet_api_cqrs.contracts.data;
using dotnet_api_cqrs.contracts.dto;
using dotnet_api_cqrs.contracts.services;

namespace dotnet_api_cqrs.services
{
    public class BookService : Service, IBookService
    {
        private readonly IBookFacade _bookFacade;

        public BookService(IDbContext context, IBookFacade bookFacade) : base(context)
        {
            _bookFacade = bookFacade;
        }

        public IEnumerable<Book> GetAllBooks()
        {
            return _bookFacade.GetBooks()(Context, null);
        }

        public Book GetBook(int bookID)
        {
            return _bookFacade.GetBook(bookID)(Context, null);
        }

        public IEnumerable<Book> GetBooksForAuthor(int authorID)
        {
            return _bookFacade.GetBooksForAuthor(authorID)(Context, null);
        }

        public Book InsertBook(Book book)
        {
            var newBookID = _bookFacade.InsertBook(book)(Context, null);
            return _bookFacade.GetBook(newBookID)(Context, null);
        }

        public void DeleteBook(int bookID)
        {
            _bookFacade.DeleteBook(bookID)(Context, null);
        }

        public Book ReplaceBook(Book oldBook, Book newBook)
        {
            return Context.Transaction<Book>(_transaction => {
                _bookFacade.DeleteBook(oldBook.BookID)(Context, _transaction);

                var newBookID = _bookFacade.InsertBook(newBook)(Context, _transaction);
                return _bookFacade.GetBook(newBookID)(Context, _transaction);
            });
        }
    }
}

Injection

I'm not going super deep here. The data and services projects each contain a static class that sets up the facades and services for injection. These classes are referenced in the Startup.cs file of the api to setup all the necessary injection.

API

The api has two controllers with endpoints for doing some simple CRUD methods on books and authors.

dotnet-api-cqrs.api/Controllers/BookController.cs

using System.Collections.Generic;
using dotnet_api_cqrs.contracts.dto;
using dotnet_api_cqrs.contracts.services;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace dotnet_api_cqrs.api.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class BookController : ControllerBase
    {
        private readonly ILogger<BookController> _logger;
        private readonly IBookService _bookService;

        public BookController(ILogger<BookController> logger, IBookService bookService)
        {
            _logger = logger;
            _bookService = bookService;
        }

        [HttpGet]
        public IEnumerable<Book> Get()
        {
            return _bookService.GetAllBooks();
        }

        [HttpGet("{bookID:int}")]
        public Book Get(int bookID)
        {
            return _bookService.GetBook(bookID);
        }

        [HttpGet("author/{authorID:int}")]
        public IEnumerable<Book> GetForAuthor(int authorID)
        {
            return _bookService.GetBooksForAuthor(authorID);
        }

        [HttpPost]
        public Book Post(Book book)
        {
            return _bookService.InsertBook(book);
        }

        [HttpDelete("{bookID:int}")]
        public IActionResult Delete(int bookID)
        {
            _bookService.DeleteBook(bookID);
            return Ok();
        }
    }
}

Benefits

The performance gains we saw with this approach were impressive. Where we were seeing return times of >250ms, we were able to write queries that were returning in <50ms.
No more crazy Entity Framework / OData queries that got hobbled together by .Net and killed performance across the board. We could work with our database team to write highly optimized queries that were extremely performant.
This approach greatly simplied testing and increased the speed of development because we didn't have as much boilerplate.
Being a sAFE team, we are big on the T-shaped developer. This approach allowed our database engineers the ability to easily understand our queries and get into the code to make modifications themselves where it use to be a "no database engineers" zone.

There was more benefits, but we'll leave it here for now. This article is getting a bit long.

So that's the basic setup for how our APIs are configured now. I'd love to get your thoughts / questions / criticisms. Be gentle. This is my first technical blog post. More to come though.

Dapper & CQRS

Rick Hopkins — Wed, 11 Aug 2021 01:32:09 +0000

Introduction

In 2016 the company I work for launched a major rewrite of our main software suite. We are an education company and so the software included everything that a school administration or teacher would need from grade book, attendance, curriculum, assessment, behavior, scheduling. It was really a pretty big success. Teachers and administrative officials seemed to enjoy the software and see it as a large step forward. We were all very proud. In time though, the shine wore off. The common complaints we began to get were that user interfaces were confusing, buggy and hard to navigate and that the system was slow.

I know... I know... We can debate the rightness or wrongness of this decision to start from scratch. To save us all time lets just move onto what we ended up doing with the new stack.

The rest of this article is a walk through an example of how we setup our API code now and the patterns we follow.

Code

If you run the API project you will be brought to a swagger page that documents the simple API I created for this example.

Contracts

dotnet-api-cqrs.contracts/data/IQuery.cs

using System.Data;

namespace dotnet_api_cqrs.contracts.data
{
    public interface IQuery<T>
    {
        string Sql { get; set; }

        T Execute(IDbContext context, IDbTransaction transaction = null);
    }
}

Commands are based upon the ICommand interface. ICommand is a simple extension of the IQuery interface with a generic type of int since all commands return an integer.

dotnet-api-cqrs.contracts/data/ICommand.cs

namespace dotnet_api_cqrs.contracts.data
{
    public interface ICommand : IQuery<int> { }
}

The IDbContext is our database connection class that will execute our queries and commands. The implementation is in the data project so we'll talk more about that later.

dotnet-api-cqrs.contracts/data/IDbContext.cs

using System;
using System.Collections.Generic;
using System.Data;

namespace dotnet_api_cqrs.contracts.data
{
    public interface IDbContext : IDisposable
    {
        T QueryFirst<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null);
        IEnumerable<T> Query<T>(string query, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null);
        int InsertSingle(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null);
        int Command(string sql, object param = null, CommandType commandType = CommandType.Text, IDbTransaction transaction = null, int? timeout = null);
        T Transaction<T>(Func<IDbTransaction, T> query);
        void Transaction(Action<IDbTransaction> query);
    }
}

Data: Commands & Queries

GetAllBooksQuery
GetBookQuery

It's not hard to determine what these queries do. Let's look at the GetAllBooksQuery.

dotnet-api-cqrs.data/Queries/Book/GetAllBooksQuery.cs

using System.Collections.Generic;
using System.Data;
using dotnet_api_cqrs.contracts.data;
using D = dotnet_api_cqrs.contracts.dto;

namespace dotnet_api_cqrs.data.Queries.Book
{
    public class GetAllBooksQuery : IQuery<IEnumerable<D.Book>>
    {
        public string Sql { get; set; }

        public GetAllBooksQuery()
        {
            Sql = @$"
SELECT              BookID,
                    Title,
                    CopyRightYear,
                    AuthorID
FROM                dbo.Books
ORDER BY            Title";
        }

        public IEnumerable<D.Book> Execute(IDbContext context, IDbTransaction transaction = null)
        {
            return context.Query<D.Book>(Sql, transaction: transaction);
        }
    }
}

dotnet-api-cqrs.data/Commands/Book/InsertBookCommand.cs

using System.Data;
using dotnet_api_cqrs.contracts.data;
using D = dotnet_api_cqrs.contracts.dto;

namespace dotnet_api_cqrs.data.Commands.Book
{
    public class InsertBookCommand : ICommand
    {
        private readonly D.Book _book;

        public string Sql { get; set; }

        public InsertBookCommand(D.Book book)
        {
            _book = book;

            Sql = $@"
INSERT INTO         dbo.Books
                    (Title, CopyRightYear, AuthorID)
VALUES              (@Title, @CopyRightYear, AuthorID);";
        }

        public int Execute(IDbContext context, IDbTransaction transaction = null)
        {
            var param = new {
                Title = _book.Title,
                CopyRightYear = _book.CopyRightYear,
                AuthorID = _book.AuthorID
            };

            return context.InsertSingle(Sql, param, transaction: transaction);
        }
    }
}

This class will take in the book parameter, setup the sql parameters, and then execute them with the IDbContext. The InsertSingle method will actually return the new Book and return it's new ID.

Data: Facades

dotnet-api-cqrs.data/Facade.cs

using System;
using System.Data;
using dotnet_api_cqrs.contracts.data;

namespace dotnet_api_cqrs.data
{
    public class Facade
    {
        protected Func<IDbContext, IDbTransaction, T> Prepare<T>(IQuery<T> queryCommand)
        {
            return (context, transaction) => {
                return queryCommand.Execute(context, transaction);
            };
        }

        protected Action<IDbContext, IDbTransaction> Prepare(ICommand command)
        {
            return (context, transaction) => {
                command.Execute(context, transaction);
            };
        }
    }
}

using System;
using System.Collections.Generic;
using System.Data;
using dotnet_api_cqrs.contracts.data;
using dotnet_api_cqrs.contracts.dto;
using dotnet_api_cqrs.data.Commands.Book;
using dotnet_api_cqrs.data.Queries.Book;

namespace dotnet_api_cqrs.data
{
    public class BookFacade : Facade, IBookFacade
    {
        public Func<IDbContext, IDbTransaction, IEnumerable<Book>> GetBooks()
        {
            return Prepare(new GetAllBooksQuery());
        }

        public Func<IDbContext, IDbTransaction, Book> GetBook(int bookID)
        {
            return Prepare(new GetBookQuery(bookID));
        }

        public Func<IDbContext, IDbTransaction, IEnumerable<Book>> GetBooksForAuthor(int authorID)
        {
            return Prepare(new GetBooksForAuthorQuery(authorID));
        }

        public Func<IDbContext, IDbTransaction, int> InsertBook(Book book)
        {
            return Prepare<int>(new InsertBookCommand(book));
        }

        public Action<IDbContext, IDbTransaction> DeleteBook(int bookID)
        {
            return Prepare(new DeleteBookCommand(bookID));
        }
    }
}c#

Services

dotnet-api-cqrs.services/BookService.cs

using System.Collections.Generic;
using dotnet_api_cqrs.contracts.data;
using dotnet_api_cqrs.contracts.dto;
using dotnet_api_cqrs.contracts.services;

namespace dotnet_api_cqrs.services
{
    public class BookService : Service, IBookService
    {
        private readonly IBookFacade _bookFacade;

        public BookService(IDbContext context, IBookFacade bookFacade) : base(context)
        {
            _bookFacade = bookFacade;
        }

        public IEnumerable<Book> GetAllBooks()
        {
            return _bookFacade.GetBooks()(Context, null);
        }

        public Book GetBook(int bookID)
        {
            return _bookFacade.GetBook(bookID)(Context, null);
        }

        public IEnumerable<Book> GetBooksForAuthor(int authorID)
        {
            return _bookFacade.GetBooksForAuthor(authorID)(Context, null);
        }

        public Book InsertBook(Book book)
        {
            var newBookID = _bookFacade.InsertBook(book)(Context, null);
            return _bookFacade.GetBook(newBookID)(Context, null);
        }

        public void DeleteBook(int bookID)
        {
            _bookFacade.DeleteBook(bookID)(Context, null);
        }

        public Book ReplaceBook(Book oldBook, Book newBook)
        {
            return Context.Transaction<Book>(_transaction => {
                _bookFacade.DeleteBook(oldBook.BookID)(Context, _transaction);

                var newBookID = _bookFacade.InsertBook(newBook)(Context, _transaction);
                return _bookFacade.GetBook(newBookID)(Context, _transaction);
            });
        }
    }
}

Injection

API

The api has two controllers with endpoints for doing some simple CRUD methods on books and authors.

dotnet-api-cqrs.api/Controllers/BookController.cs

using System.Collections.Generic;
using dotnet_api_cqrs.contracts.dto;
using dotnet_api_cqrs.contracts.services;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace dotnet_api_cqrs.api.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class BookController : ControllerBase
    {
        private readonly ILogger<BookController> _logger;
        private readonly IBookService _bookService;

        public BookController(ILogger<BookController> logger, IBookService bookService)
        {
            _logger = logger;
            _bookService = bookService;
        }

        [HttpGet]
        public IEnumerable<Book> Get()
        {
            return _bookService.GetAllBooks();
        }

        [HttpGet("{bookID:int}")]
        public Book Get(int bookID)
        {
            return _bookService.GetBook(bookID);
        }

        [HttpGet("author/{authorID:int}")]
        public IEnumerable<Book> GetForAuthor(int authorID)
        {
            return _bookService.GetBooksForAuthor(authorID);
        }

        [HttpPost]
        public Book Post(Book book)
        {
            return _bookService.InsertBook(book);
        }

        [HttpDelete("{bookID:int}")]
        public IActionResult Delete(int bookID)
        {
            _bookService.DeleteBook(bookID);
            return Ok();
        }
    }
}

Benefits

The performance gains we saw with this approach were impressive. Where we were seeing return times of >250ms, we were able to write queries that were returning in <50ms.
No more crazy Entity Framework / OData queries that got hobbled together by .Net and killed performance across the board. We could work with our database team to write highly optimized queries that were extremely performant.
This approach greatly simplied testing and increased the speed of development because we didn't have as much boilerplate.
Being a sAFE team, we are big on the T-shaped developer. This approach allowed our database engineers the ability to easily understand our queries and get into the code to make modifications themselves where it use to be a "no database engineers" zone.

There was more benefits, but we'll leave it here for now. This article is getting a bit long.

So that's the basic setup for how our APIs are configured now. I'd love to get your thoughts / questions / criticisms. Be gentle. This is my first technical blog post. More to come though.

An Introduction

Rick Hopkins — Fri, 06 Aug 2021 21:41:22 +0000

In the year 2001, I began work as a web application developer at an industrial equipment company in Grand Rapids, Michigan. The only experience I had before getting the job was working with Dreamweaver and Flash to create a simple website for my college rock band. I’m not sure how I fooled them into hiring me (actually I do, but that is another story…), however this started me on the path of becoming the Senior Software Engineer that I am today.

The first language I taught myself was PHP, and after that moved very quickly onto HTML, CSS, and JavaScript. I’ve also worked extensively with C#, done a little python, worked with Node, and a whole bunch of other languages. I’ve worked with more frameworks and libraries over the years than I can remember. Lately I’m heavily invested in Angular and AngularJS, but I have a lot of interest in Vue and React as well.

I’ve always loved teaching myself new things, and I enjoy being presented with problems that need to be solved. I’ve been able to work on a myriad of different software solutions over the years. Planned maintenance software for industial equipment, completely custom CRM systems, employee performance systems built on top of Microsoft Dynamics CRM (as well as a pile of other custom CRM based solutions), and now that I work for an educational company I work on classroom based software solutions like curriculum and assessment.

A key interest of mine has always been understanding how things work, and teaching myself the newest technology with whatever spare time I can come up with. I’m a married man with six kids so that spare time is hard to come by, but when I can get it I like to spend it learning and trying to grow my abilities.

I’m also a fan of music. I love to write and record music. Writing music and sharing it with people I find has a similar effect to making software. I love to be creative and make something that I can share with others in order to help them with something they are facing, or working through. This is where I got the idea for Melodic Development. I want to learn, create, and share as much as I can to help other developers who are also just trying to learn and become better at what they do.

I hope that what I share can be of use to anyone looking to learn along with me.

NOTE: This was originally posted on Medium a while back. Trying to get something rolling (again).

NHA Coding Standards

Rick Hopkins — Mon, 24 Aug 2020 14:59:07 +0000

INTRODUCTION

This is the National Heritage Academies (NHA) School Applications Development team's coding standards page. Feel free to use these standards for your own reference. As the development team at NHA has grown over the past couple years so has the importance of common coding practices and standards. This article is meant to serve as the agreed upon standards to be followed by the NHA School Applications Development team. These standards are meant to help with:

Keeping our code consistent
Making our code easy to read and understand
Making our code easier to maintain

The following sources were used to compile this list of standards.

https://medium.com/javascript-in-plain-english/19-simple-javascript-coding-standards-to-keep-your-code-clean-7422d6f9bc0

GENERAL CODING STANDARDS

Always use semicolons (;)

Even though the semicolon is optional in JavaScript, we are choosing to end all statements with the semicolon. This is a consistent requirement across JavaScript, TypeScript, C#, and even SQL.

Always use curly braces around control structures.

Braces are required for all control structures (i.e. if, else, for, do, while, etc). Do use use single line if statements. The curly brace should start on the same line as the control structure and close on a new line. There should be a space before the opening curly brace.

Fail:

if (val == 2) doSomething();
if (val == 2)
    doSomething();
if (val == 2)
    doSomething();
else
    doSomethingElse();

Pass:

if (val === 2) {
    doSomething();
}
if (val == 2) {
    doSomething();
} else {
    doSomethingElse();
}

Try to reduce nesting

Nesting if statements within if statements can lead to messy, unreadable code. Always look for ways to avoid nesting if at all possible. Also try to avoid else if statements.

Fail:

if (myNumber > 0) {
  if (myNumber > 100) {
       if (!hasDiscountAlready) {
           return addDiscountPercent(0);
} else {
           return addDiscountPercent(10);
       }
  } else if (myNumber > 50) {
    if (!hasDiscountAlready) {
       return addDiscountPercent(5);
    }
  } else {
    if (!hasDiscountAlready) {
      return addDiscountPercent(0);
    } else {
      return addDiscountPercent(1);
    }
}
} else {
    error();
}

Pass:

if (myNumber <= 0) {
   return error;
}
if (!hasDiscountAlready) {
    return addDiscountPercent(0);
}
if (myNumber > 100) {
    return addDiscountPercent(10);
}
if (myNumber > 50) {
    return addDiscountPercent(5);
}
return addDiscountPercent(1);

Switch statements should use break and have a default

Try not to use switch statements, but if you must then make sure to each break condition and use default. Like if statements, the curly braces should start on the same line as the switch statement and end on a new line. There should be a space before the opening curly brace.

Fail:

switch (myNumber) {
  case 10:
   addDiscountPercent(0);
  case 20:
   addDiscountPercent(2);
  case 30:
   addDiscountPercent(3);
}

Pass:

switch (myNumber) {
  case 10:
    addDiscountPercent(0);
    break;
  case 20:
    addDiscountPercent(2);
    break;
  case 30:
    addDiscountPercent(3);
    break;
  default:
    addDiscountPercent(0);
    break;
}

Only use one variable per declaration

It is a cleaner and more understandable way to declare your variables.

Fail:

const a = 2, b = 3;

Pass:

const a = 2;
const b = 3;

TYPESCRIPT

The following rules are based on typescript but should also be followed where applicable to JavaScript.

When comparing use === instead of ==

Using === matches on both the type and value.

Fail:

if (val == 2)

Pass:

if (val === 2)

Never use var.

Use const for values that cannot be reassigned and let for anything else. Favor using const as much as possible.

Fail:

var value: number = 100;

Pass:

const value1: number = 100;
let value2: number = 200;

Always set the type for variables and properties.

Fail:

const value = 100;

class CarModel {
    private _value = 100;
}

Pass:

const value: number = 100;

class CarModel {
    private _value: number = 100;
}

Always set the return type for functions and class methods.

Fail:

function callback() {
    return 'hello world';
}

class CarModel {
    callback() {
        return 'hello world';
    }
}

Pass:

function callback(): string {
    return 'hello world';
}

class CarModel {
    callback(): string {
        return 'hello world';
    }
}

Always set the argument types for functions and class methods.

Fail:

function callback(inputStr) {
    return inputStr;
}

class CarModel {
    callback(inputStr) {
        return inputStr;
    }
}

Pass:

function callback(inputStr: string): string {
    return inputStr;
}

class CarModel {
    callback(inputStr: string): string {
        return inputStr;
    }
}

Avoid the use of any as a type as much as possible

Using any can allow for too many unknowns in what type of data you are dealing with. While it can't be avoided entirely, it should be very limited in its use.

Fail:

const value: any = 1;

Pass:

const value: number = 1;

Class Names should be in PascalCase format

Fail:

class carModel { }

Pass:

class CarModel { }

Class Property Definitions

Class properties should be listed before the constructor. Each property should be properly labeled private, protected, or public and listed in that order. Private properties should begin with an underscore and be camelCased. Protected and Public should simply be camelCased. It is preferrable to label public properties as such, but is not exactly required. It's preferred because by default non-labeled properties are considered public. However in C#, non-labeled properties are considered private. I think consistency across our two most used languages would be a good thing to pursue.

Fail:

class CarModel {
    constructor() { }

    TestPrivateProperty = 1;
    TestProtectedProperty = true;
    TestPublicProperty = 'I am public';
    TestPublicProperty2 = 'So am I';
}

Pass:

class CarModel {
    private _testPrivateProperty: number = 1;
    protected testProtectedProperty: boolean = true;
    public testPublicProperty: string = 'I am public';
    testPublicProperty2: string = 'So am I';

    constructor() { }
}

Class Method Definitions

Class methods should be camelCased. Each method should be properly labeled private, protected, or public with the exception of the constructor. It is preferrable to label public methods as such, but is not exactly required. It's preferred because by default non-labeled methods are considered public. However in C#, non-labeled methods are considered private. I think consistency across our two most used languages would be a good thing to pursue.

Also opening brackets are on the same line as the method name, and the closing bracket is on a new line.

Fail:

class CarModel {
    TestPrivateMethod(): number {
        return 1;
    }
    TestProtectedMethod(): boolean {
        return true;
    }
    TestPublicMethod(): string {
        return 'I am public';
    }
    TestPublicMethod2() {
        return 'So am I';
    }
}

Pass:

class CarModel {
    private testPrivateMethod(): number {
        return 1;
    }
    protected testProtectedMethod(): boolean {
        return true;
    }
    public testPublicMethod(): string {
        return 'I am public';
    }
    testPublicMethod2(): string {
        return 'So am I';
    }
}

C

The following rules are based on C#.

Class Names should be in PascalCase format

Fail:

class carModel { }

Pass:

class CarModel { }

Class Property Definitions

Class properties should be listed before the constructor. Each property should be properly labeled private, protected, or public and listed in that order. Private properties should begin with an underscore and be camelCased. Protected and Public should simply be PascalCased. It is preferrable to label private properties as such, but is not exactly required. It's preferred because by default non-labeled properties are considered private. However in TypeScript, non-labeled properties are considered public. I think consistency across our two most used languages would be a good thing to pursue.

Fail:

class CarModel {
    CarModel() { }

    int TestPrivateProperty = 1;
    bool TestProtectedProperty = true;
    string TestPublicProperty = 'I am public';
    string TestPublicProperty2 = 'So am I';
}

Pass:

class CarModel {
    private int _testPrivateProperty = 1;
    protected bool TestProtectedProperty = true;
    public string TestPublicProperty = 'I am public';
    public string TestPublicProperty2 = 'So am I';

    CarModel() { }
}

Class Method Definitions

Class methods should be PascalCased. Each method should be properly labeled private, protected, or public. It is preferrable to label private methods as such, but is not exactly required. It's preferred because by default non-labeled methods are considered private. However in TypeScript, non-labeled methods are considered public. I think consistency across our two most used languages would be a good thing to pursue.

Also, opening and closing brackets are on new lines.

Fail:

class CarModel {
    int TestPrivateMethod() {
        return 1;
    }
    bool TestProtectedMethod() {
        return true;
    }
    string TestPublicMethod()
    {
        return 'I am public';
    }
    string TestPublicMethod2()
    {
        return 'So am I';
    }
}

Pass:

class CarModel {
    private int TestPrivateMethod()
    {
        return 1;
    }
    protected bool TestProtectedMethod()
    {
        return true;
    }
    public string TestPublicMethod()
    {
        return 'I am public';
    }
    public string TestPublicMethod2()
    {
        return 'So am I';
    }
}

Conclusion

This is a work in process document. These standards and guidelines will change and evolve over time.