.NET modernisation: a view from the trenches

These were a rather mixed bag. We had a dozen or so APIs in total — thankfully nothing that served the public internet or outside consumers. One or two of these were already on .NET Core, though still several years out of date; nothing was on .NET 6 or above.

Two particularly thorny projects were on legacy ASP.NET (as opposed to ASP.NET Core). This meant they couldn’t be built when I ran a simple dotnet build on the solution file, which was a personal goal of mine. Thankfully, these were already on life support and not getting any meaningful code updates.

We had twenty or so backend services that ran as Windows services on an AWS EC2 instance to mimic a traditional Windows server environment.

Some of these manifestly didn’t need to exist; for example, one service ran all day, but the only work it did was send out emails at a specified time every morning, something that could be done with Amazon SNS.

The more interesting fact, however, is that they were run with an ingeniously janky homegrown version of Microsoft.Extensions.Hosting. I’ll refer to it as 'Hoster' to protect the innocent.

Hoster worked by dynamically loading assemblies at runtime. You built your projects as libraries, compiling to simple .dlls, and supplied a config file specifying the name of the method and type that would serve as your entrypoint.

The promise of Hoster was that it setup logging for you, handled graceful restarts and shutdowns, and supported arbitrary numbers of projects running under one executable. You could theoretically even add or remove projects between app invocations by just removing their config file, though in practice this was never done.

Naturally this solution gave us plenty of problems. It was horribly brittle — without knowing the special places you had to put .dlls and configs, things failed silently. Exceptions in the hosted code would not reliably be transmitted to the Hoster shell. Dynamically loading the assemblies led to days of pain with binding exceptions, and was also only supported on .NET Framework. The implementation used AppDomains, which were essentially deprecated in .NET Core. Deployment was unnecessarily complex; we had to marshal together not only the correct version of Hoster, but all the code we actually cared about. It was a quintessential example of taking flexibility too far. And the vast majority of the time, we only ever hosted one service per executable anyway, so its flexibility was of little use. Hoster was written before Microsoft.Extensions.Hosting, and it wasn’t a bad bit of work for the time. But it was sorely past its use-by date.

I think every .NET dev has touched this kind of old Winforms app at some point. Lots of complex, bespoke forms built up of DevExpress widgets customised into unrecognisability. Code-behind files that easily broke five thousand lines in length.

This is the one part of the solution I’ve yet to seriously touch, because it’s obviously business-critical and has a lot of moving parts. Watch this space.

Assume in this section, and really this entire document, that when I say 'dependency' I mean a reference between projects. NuGet packages can sometimes be troublesome, if they only support specific framework versions — EF6 comes to mind — but they are generally a lesser concern. To put it simply, a project is only allowed to reference projects with a lower-or-matching framework version, or .NET Standard. .NET Framework can’t depend on .NET Core and vice versa. One of the biggest issues when modernising a big solution is untangling the Gordian knot of project dependencies, slowly carving out an island of .NET Standard code that you can ride, raft-like, to safety.

Anyway, let’s not get carried away with metaphors. A project with no dependencies is easier to upgrade than one which does. So naturally we should try to trim down the dependencies of our projects as much as possible. Naturally this isn’t important if the dependencies are themselves .NET Standard already. The bottom-up approach should make this the case a lot of the time, but it’s not feasible to follow with 100% consistency, so sometimes you’ll need to migrate away from a .NET Framework dependency.

Trimming dependencies takes two forms: removing unnecessary dependencies and narrowing your dependencies.

By 'unnecessary', I mean a project dependency that is entirely unused and can be removed with no ill effect in the consumer. This happens more frequently than you might think in a legacy codebase with lots of churn; if a piece of code moves from HelperLibrary.Imp to BasicCode.Core, you might not realise the HelperLibrary reference is no longer needed. Manually auditing all your project references is a pain — the best approach I know of is to comment them out one-by-one in the .csproj, build the project and see if it breaks. It’s much better to use tooling for this. I use Rider as my daily driver, and it has a 'find unused references' feature which identifies unused assemblies most of the time. Doing this let me cut out dozens of dependency-links between projects and made more than a few of them entirely isolated (and, thereby, trivial to upgrade).

What about 'narrowing' your dependencies? This means only depending on what you actually need. There are two scenarios where you can end up depending on more than what’s necessary.

Fixing the first step is fairly easy. Reference the project you need directly. Transitive project dependencies are useful, but they also hide information, and during a modernisation drive that should be avoided. I didn’t have access to any fancy tools like NDepend to map out the project hierarchy in my solution, so I just played this part by ear. Note that this usually requires the projects in questions to have SDK-style .csprojs, which I talk about in a later point.

As for 2), this is where we get into splitting up projects or reorganising code.

A project might be 'held back' to .NET Framework by one small little class that happens to use WCF or an API that’s not supported on later versions. In those cases it’s often valuable to extract that 1% of the project out to somewhere else, potentially even its own project. This does lead to solution bloat, but sometimes things have to get worse before they can get better. You can also take the route of quarantining all the legacy code into its own project. Besides making other projects safe to upgrade, it also makes it very clear to other developers that they should avoid using anything in the legacy project for new work, if at all possible.

I told a white lie previously when I said that .NET Core could only interoperate with .NET Standard seamlessly. .NET Core assemblies will, in fact, try to 'just work' with .NET Framework dependencies. In a lot of cases, this will be fine and you won’t notice the difference. But you get very few guarantees, working this way; if the runtime encounters something it can’t handle it reserves the right to explode at runtime. So this should be considered a last resort. You’ll thankfully get some very noticeable compiler warnings when you do this, which is actually quite useful, as it’s easy to do this accidentally via transitive dependencies.