It is not.

Facts: what System.Threading.Channels gives you

Introduced to provide a producer/consumer primitive tuned for async code, System.Threading.Channels exposes Channel<T> with bounded / unbounded modes, explicit completion, and reader/writer halves that cooperate with async/await without busy-waiting.¹

Useful mental model:

Stephen Toub’s detailed posts on channels remain the best narrative explanation of design trade-offs inside .NET’s concurrency toolbox.³

Facts: why Dependency Injection cares about lifetime

Any shared mutable pipe must align with service lifetime:

• Singleton channel → every consumer sees one logical bus (great for in-process pub/sub).
• Scoped channel → one pipe per request/scope (good when isolation matters).
• Transient writers/readers without a stable channel → usually accidental complexity.

Microsoft documents service lifetimes (Singleton, Scoped, Transient) and cautions about capturing scoped services in singletons—the same reasoning applies when the “service” is effectively an async queue.⁴

Opinion (labeled honestly): what this library is

A named pipe with async manners that the host already understands: backpressure, completion, multiple readers/writers — the stuff you would otherwise reinvent with ConcurrentQueue plus vibes.

Registering Channel<T> in DI is saying: this subsystem talks to that subsystem through here, and the lifetime is explicit.

What it is not

It is not a replacement for messaging infrastructure. It is not Kafka in your process. It is not “use channels everywhere because channels are cool” — that way lies spaghetti with async characteristics.

Pitfalls that bite real systems

1. Unbounded memory — unbounded channels absorb spikes until OutOfMemoryException becomes your profiler.
2. Forgotten completion — readers wait forever if writers never call Complete.
3. Blocking sync-over-async on channel edges — defeats the whole point; keep boundaries async.
4. Lifetime mismatch — singleton consumer holding scoped producer references leaks scope or starves work.

Why I bothered packaging it

Because I kept writing the same three registrations in every project, and copy-paste across repos is how subtle bugs become tradition.

TL;DR

If the API feels boring, it is working. The interesting part is what you push through the channel — not the fact that DI can hand you the ends.

References

• Microsoft Learn — System.Threading.Channels
• Microsoft Learn — Dependency injection in .NET
• Stephen Toub — Introduction to System.Threading.Channels
• Frank.Channels.DependencyInjection (GitHub)

Facts: what “no security” means on the wire

Classic IRC predates ubiquitous TLS on the wire: protocol documents assume cleartext TCP unless an implementation layers transport security separately.¹ Modern deployments often terminate TLS at proxies or use vendor-specific extensions—the baseline remains “know what you actually expose.”

TLS itself is standardized (today TLS 1.3 in RFC 8446; TLS 1.2 still documented in RFC 5246 for historical comparison).²³ The lesson for application authors is not memorizing cipher suites—it is using maintained implementations (OS/BoringSSL/OpenSSL/.NET stack) instead of rolling bespoke crypto.

Facts: why “rolled my own crypto” ages poorly

MITRE CWE-327 documents Use of a Broken or Risky Cryptographic Algorithm—including adopting obsolete primitives or constructing ad-hoc protocols.⁴ OWASP guidance repeatedly warns that custom cryptography combine-and-match tends to fail open under real attackers.⁵

Related failure mode: downgrade attacks and oracle behaviors appear when authenticated encryption + proper key hierarchy are skipped—why TLS evolution focuses on authenticated AEAD ciphersuites and tight handshake rules.

The setup (IRC-shaped honesty)

IRC is text over TCP in the textbook telling. No encryption in the classic story. No authentication that survives a stiff breeze. If you squint, that is horrifying—but at least it is honest horrifying.

The worse option

Rolling your own crypto-ish layer because you feel bad about plaintext — but doing it slightly wrong — is how you get false confidence. Users think they are safe. You think you are safe. The attacker thanks you for the predictable mistake.

This aligns with broader engineering consensus: prefer proven protocols implemented by specialists; document threat boundaries instead of improvising them.

The boring correct stance

Either use a boring, audited stack end-to-end, or be loudly honest about what you are not protecting. “No security” with documentation is often more ethical than “security theater” with marketing.

Concrete checklist:

1. Name the adversary (network observer? malicious server? compromised client?).
2. Pick TLS or Noise or QUIC from maintained stacks—not “AES + vibes.”
3. Publish what you do not mitigate (social engineering, endpoint malware, etc.).

Where I land

I would rather say “I am not the person to implement your threat model” than ship a half-understood cipher suite because sleep deprivation and hubris formed an alliance.

TL;DR

Admitting limits is not defeat. Shipping bad crypto because you could not stand the shame of plaintext — that is defeat with extra steps.

References

• RFC 2812 — IRC Client Protocol
• RFC 8446 — TLS 1.3
• RFC 5246 — TLS 1.2
• CWE-327 — Broken/Risky Crypto Algorithm
• OWASP — Cryptographic Storage Cheat Sheet

1. “Never prefix your packages with your first name.” — NuGet guidance emphasizes discoverability and prefix reservations for trusted publishers, not outlawing personal prefixes—but the ecosystem norm skews corporate.¹

2. “Always write the ADR before the code.” — Architecture Decision Records formalize intent before implementation spikes; the pattern was popularized to capture why, not block prototyping.²

3. “Avoid global state.” — Structured programming dogma (Dijkstra-era) and functional idioms both warn against implicit mutable globals—yet every GUI toolkit eventually exposes process-wide singletons (Application.Current). Trade honesty about deliberate globals vs accidental ones.

4. “One repo per concern.” — Martin Fowler’s Monolith First essay argues microservice partitioning often premature; polyrepos vs monorepos remain tooling choices, not virtues.³

5. “Never optimize early.” — Donald Knuth’s oft-misquoted line appears in his 1974 Computing Surveys paper on structured programming: small efficiencies can hurt readability unless you know the critical 3%—not “never optimize.”⁴

6. “Always use the framework’s blessed path.” — Framework vendors document golden paths sized for median apps; extension points exist precisely because blessed paths fail edge domains (games, compilers, protocol stacks).

7. “Write tests first.” — Kent Beck crystallized TDD as red/green/refactor loops; empirical teams blend test-after for exploratory spikes—method books describe ideals, delivery adapts.⁵

8. “Keep posts short.” — Attention-economy blogging advice; incompatible with posts that carry citations and narrative arcs—pick your audience.

9. “Never ship a rant.” — Engineering culture prefers sanitized communications; incident reviews prove emotionally honest narratives accelerate learning when paired with facts.

10. “Be consistent.” — PEP 8 famously quotes “A foolish consistency is the hobgoblin of little minds” to defend breaking style when readability improves—consistency serves comprehension, not uniformity.⁶

The actual moral

Rules are heuristics from someone else’s scars. Steal the scars, question the slogans, keep the compiler happy.

References

• Martin Fowler — Monolith First
• Martin Fowler — Test-Driven Development
• Knuth (1974) — DOI 10.1145/356635.356640
• ADR GitHub
• PEP 8
• Microsoft Learn — NuGet package authoring

RoboSharp is the opposite on purpose. The point is not the robot on the grid; the robot is the excuse. The point is that you can see the stages update while you edit: tokens, syntax, bound tree, IL, interpreter. Boring, finicky, real computer science — the stuff textbooks skip because it does not fit on a slide.

Facts: what a compiler pipeline usually contains

Textbooks divide compilation into predictable phases—names vary, but the skeleton is stable:

Engineering a Compiler (Cooper & Torczon) presents the same pipeline with engineering emphasis—trade-offs between IR shapes, passes, and diagnostics quality.⁴

For .NET, Roslyn exposes compiler APIs so tooling (IDE refactorings, analyzers, source generators) shares the same frontend as csc. Microsoft’s conceptual docs describe syntax trees, semantic models, and workspaces for building analyzers.⁵

Why visibility beats “just use the API”

When the API is the curriculum, you learn one vendor’s opinion. When the pipeline is the curriculum, you learn how languages actually work, which transfers even when the framework du jour changes its mind next Tuesday.

The honest downside

It is more intimidating. Some people bounce off immediately because there is no dopamine tutorial path where you “build Instagram in ten minutes.” Good. Instagram already exists. I would rather have a smaller audience that sticks around because the machine finally clicked.

TL;DR

If you can watch it compile, you might hate it for an hour — then you might never unsee how much software you use every day was always doing this work under the hood.

References

• Microsoft Learn — .NET Compiler Platform SDK
• Roslyn GitHub — Wiki overview
• Aho et al. — Compilers: Principles, Techniques, and Tools (Pearson)
• Cooper & Torczon — Engineering a Compiler
• RoboSharp (GitHub)

Facts: how NuGet expects packages to identify themselves

NuGet package IDs must follow predictable rules—length limits, allowed characters, no reserved prefixes unless you own them. Microsoft documents authoring guidelines and ID prefix reservation so consumers can trust who publishes Microsoft.*, System.*, etc.¹

That matters because names are not cosmetic—they control restore graphs, typosquatting risk, and tooling assumptions.

Is that good branding?

For discoverability, absolutely not. NuGet search is not going to surface “Frank” as a category unless you already know me. For ownership, though, it is weirdly practical: I can tell at a glance what I spawned, what I maintain, and what is allowed to be as opinionated as I want without pretending it is a neutral industry utility.

OSS ecosystems repeatedly debate namespaces vs vanity prefixes—npm scoped packages (@org/pkg) solved part of the collision surface; NuGet leans on prefix reservations + longer IDs instead.

The real reason

Half of it is ego — I will not pretend otherwise. The other half is namespace hygiene in a world where every second word is Microsoft.Extensions.SomethingSomething. I want my packages to read like mine, not like a missing chapter of the framework docs.

When it is embarrassing

When someone asks “which Frank library does channels again?” and I have to mentally grep twelve repos. When I explain my work to a normal human and they think my legal name is a product line.

When I would still do it again

Because naming is the first API you ship. If Frank.* filters out people who cannot tolerate a little vanity, those people were never going to enjoy my commit messages either.

References

• Microsoft Learn — NuGet package authoring
• Microsoft Learn — Package ID prefix reservation
• NuGet Gallery — search guidelines

Facts: how WPF expects an application to boot

Microsoft documents System.Windows.Application as the entry point for WPF UI—a message pump (Run) tied to Windows message semantics and STA threading.¹

.NET console templates historically used [STAThread] on Main because COM and classic UI frameworks expected STA; WPF shares that heritage even when you host inside Microsoft.Extensions.Hosting.²

The Worker SDK (Microsoft.NET.Sdk.Worker) pulls in hosting primitives (BackgroundService, configuration, DI) documented under .NET Generic Host.³⁴

This pattern pairs:

Why would you use WPF without XAML

The easy answer: I don’t like XAML. Even with MVVM it is fiddly XML that fights you the moment you want real nesting, dynamic trees, or anything that is not a designer-friendly toy demo.

Tradeoff snapshot:

Pitfalls worth naming

1. Lifetime mismatch — treating MainWindow like a singleton when your DI scope says scoped invites ghosts after window close.
2. Async void on UI thread — still the easiest footgun in event handlers.
3. Shutdown semantics — forcing Environment.Exit (as below) is blunt; production apps usually coordinate CancellationToken + IHostApplicationLifetime.

How to get started?

1. Use the dotnet CLI or Visual Studio project creator to create a “Worker project” and change the .csproj to look something like this:

Prefer a modern TargetFramework (net8.0-windows or newer LTS) unless you truly need net5.0-windows.

<Project Sdk="Microsoft.NET.Sdk.Worker">
    <PropertyGroup>
        <TargetFramework>net8.0-windows</TargetFramework>
        <LangVersion>latest</LangVersion>
        <Nullable>enable</Nullable>
        <OutputType>Exe</OutputType>
        <UseWpf>true</UseWpf>
    </PropertyGroup>
</Project>

2. Add an App.cs that extends Application

using System.Windows;

namespace Demo.WpfApplication
{
    public class App : Application
    {
    }
}

3. Create a MainWindow.cs to be your main window

using System.Windows;
using System.Windows.Controls;

namespace Demo.WpfApplication
{
    public class MainWindow : Window
    {
        private readonly ILogger<MainWindow> _logger;

        public MainWindow(ILogger<MainWindow> logger)
        {
            _logger = logger;

            var button = new Button { Content = "Log something" };
            button.Click += (_, _) => _logger.LogInformation("Something");

            Content = button;
        }
    }
}

4. Rename Worker.cs to WindowHost.cs then inject only the IServiceProvider

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace Demo.WpfApplication
{
    public class WindowHost : BackgroundService
    {
        private readonly IServiceProvider _serviceProvider;

        public WindowHost(IServiceProvider serviceProvider) => _serviceProvider = serviceProvider;

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            using var scope = _serviceProvider.CreateScope();
            var window = scope.ServiceProvider.GetRequiredService<MainWindow>();
            var app = scope.ServiceProvider.GetRequiredService<App>();
            window.Closed += (_, _) => Environment.Exit(666); // replace with graceful shutdown in real apps

            app.Run(window);
        }
    }
}

5. Then finally edit Program.cs to look like this

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

namespace Demo.WpfApplication
{
    public class Program
    {
        [STAThread]
        public static void Main(string[] args)
        {
            var host = Host.CreateDefaultBuilder(args)
                .ConfigureServices((hostContext, services) =>
                {
                    services.AddLogging();
                    services.AddScoped<App>();
                    services.AddScoped<MainWindow>();

                    services.AddHostedService<WindowHost>();
                });

            host.Build().Run();
        }
    }
}

References

• Microsoft Learn — WPF overview
• Microsoft Learn — Application
• Microsoft Learn — Generic Host
• Microsoft Learn — Worker Service template

This is the story of how I wanted to make an IRC client/server library, but ended up making a workflow library, a Pub/Sub library, and a DI Channel library, a data persistence library, CronJobs, and a bunch of other things along the way, while still not having any idea how to make an IRC client/server library. Adopting a Torrent client along the way was interesting though.

TL;DR

I wanted to make an IRC client/server library, but ended up making an entire ecosystem of libraries, and still don’t have any IRC client/server library to show for it.

Motivation

IRC is a protocol that has been around for a long time. It is simple, and it is still used today, and it is still relevant. It lends itself to be used in many different ways, and it is a good protocol to learn about networking, and to learn about low level stuff and efficient data/string manipulation. It is also a good protocol to learn about security, as it has no security. It is also a good protocol to learn about how to make a client/server library.

Facts: IRC specifications worth bookmarking

The classic IRC protocol stack is defined across multiple RFCs—RFC 1459 documents the original architecture (channels, operators, numeric replies), while RFC 2812 focuses on client behaviour and explicitly discusses security considerations that boil down to “transport security is out of band unless you bolt something on.”¹²

Modern deployments sometimes layer TLS (ircs://) or vendor-specific extensions—IRCv3 working-group drafts catalogue capability negotiation—but the baseline mental model remains cleartext channel semantics unless you prove otherwise.

Microsoft’s Microsoft.AspNetCore.Connections.Abstractions—what Bedrock.Framework showcased—is documented today under ASP.NET Core connection middleware / Kestrel extensibility; learning those primitives is orthogonal to IRC grammar but essential if you want composable socket pipelines in .NET.³

The Idea

I wanted to make an IRC client/server library. I wanted to make it in a way that it would be easy to use, and easy to extend. It should be .net, nuget distributed, and should be able to run on cross-platform. It should be close to out-of-the-box, but alse a framework that can be extended. It should be able to run as a server, and as a client, (in different packages of course).

The Journey

First I looked at the existing libraries. There are a few, many are .net/.net core, but none of them are close to what I wanted. I am a big fan of Dependency Injection, and I wanted to make the library in a way that it would be easy to use with this pattern. I also wanted to make it in a way that it would be easy to use with modern .net core features like Channel<>, IHostedService, and CronJobs.

I started with the server. I wanted to make it in a way that it would be easy to use, and easy to extend. I wanted to make it so it would be easy to use with Dependency Injection, and I wanted to make it so it would be easy to use with modern .net, and also wanted everything to be async. I wanted to make it so it would be easy to use with Channel<>, and I wanted to make it with mostly my own code, and not rely on too many third party libraries. Easy peasy, right? WRONG!

Where it started to go wrong

So I am on the .net stack, and I love it. Microsoft has done a great job with .net core, but its microsoft, and so they don’t give you A gun to shoot yourself in the foot, they give you a machine gun, or at least a box of guns. So I started looking at the System.Net.Sockets namespace, and I was like, “Oh, this is easy, I can do this.” And then I started looking into life cycle management, and I was like, “Oh, this NOT easy, I can NOT do this.”, is this skillissues? Yes, but also: The .net team hasn’t made it easy to work with sockets. I sank so low I asked a question on Reddit, /dotnet, and I got an answer, from none other than David Fowler, he pointed me to a tech demo he had noted on his GitHub. This was a good start, and I found a library he had made called “Bedrock.Framework”. I started looking into it, and I was like, “Oh, this is easy, but oh so much stuff I don’t need, and oh so much stuff I don’t understand.” I started looking into the source code, and I did the rational thing, I copied it, and started to strip it down, didn’t like it, then I took a step back, and started to look at what he was doing and saw he was basically demonstrating how to use the new Microsoft.AspNetCore.Connections.Abstractions, so I pivoted, and now I have a TCP client/server library that is using the new Microsoft.AspNetCore.Connections. Abstractions called “Frank.BedrockSlim”. I am happy with it. It is async, it is easy to use, and it is easy to extend. It uses a bear minimum of asp.net core low level stuff, and it is easy to use with Dependency Injection. The server does have a framework reference to asp.net core, but the client does not. I am happy with it, but I still don’t have an IRC client/server you might have noticed.

Servers need data persistence

So I have a server, and I have a client, and I have a protocol, and I have a way to communicate, but servers usually need data. Sessions, users, channels, messages, etc. I started to look into how to do this, and I was like, “Oh, this is easy, I just use a database and Entity Framework Core”. Well, a database, even SQLite, is not always the correct answer. I wanted flexibility in my data persistence, because user profile data is nice to blob in a json, logs should be in a log file, and messages should perhaps be in a database. Well, I solved it by making a data persistence library called “Frank.DataStorage”. Now I have a common interface, and I have a few implementations, and I can use it with Dependency Injection. Now I’m just 5 months into the project, and I still don’t have an IRC client/server library. I have something cool though.

Oooh, shiny!

Channel<>, is maybe the coolest thing added to .net core in the last few years. It is a way to pass data between threads, from one to many, from many to one, and it is async. I wanted to use it in my server, and I wanted to use it in my client, so it can be more reactive, and many things are workflow-like, maybe I should make a workflow library? Forshadowing? Channels seems to be awesome for in-memory Pub/Sub, and I wanted to make a library for that, and I did, and I called it Frank.PulseFlow. It is a simple Pub/Sub library that uses Channel<>, and it is easy to use with Dependency Injection. Oh, there is a need for DI Channel<> other places too, so I made a library for that, and I called it Frank.Channels. DependencyInjection, (It’s really cool, you just register your type as a channel and you can inject the entire channel, the reader or writer, and looking at resource use its like nothing, AWESOME!). I’m getting a bit off track here, wasn’t I making an IRC client/server library?

CronJobs

I have contributed to a few open source projects, one of them is a library called CronQuery. It is a library that can very easily parse a cron expression from configuation, and start DI CronJobs. I wanted to use it in my server and client, and I wanted to use it a bit differently than it was intended, so I made a library called Frank.CronJobs. It is a library that don’t rely on the Microsoft.Extensions.Configuration namespace, and it is easy to use with Dependency Injection. I have a great deal of respect for open source, and so I copied the license header from the original library, and I have a link to it, and even rewrote a lot of the more complex parts of the library, so I’m not just a copycat.

Workflows

I have been working with workflows for a long time, and I have been working with a lot of different workflow engines, I have even created a few myself. But I wanted to make a workflow engine that is built on Dependency Injection and modern .net core and that uses Channel<>, IHostedService, and CronJobs. I wanted to make it so it would be easy to use, and easy to extend. I wanted it to be simple, because I understand that workflows can be complex, but most of the time they are not, they are just a linear sequence of steps. So I made a library called Frank.WorkflowEngine. It is a simple workflow engine that is built with a lot of the previously mentioned libraries.

Security, what’s that?

So, I remembered a tiny bit about IRC, NO SECURITY! Its text over TCP, and it is not encrypted, and it is not authenticated, and an IRC server should at least be a little secure, and so I started to look into how to make it secure, and I was like, “Oh, lets build a security library”, and I did, and I called it Frank.Security, (There’s a pattern to my naming scheme that is REALLY hard to deduce). What kind of security? Well, password hashing, passprashe generation, and a few other things. How to use it with IRC? Well, he he… Actually securing and encrypting IRC is a bit more complex than I thought, and I can say that I’d rather not do it, and I can say that there is no end-to-end encryption, rather than doing it wrong. I have some experience with security, but low level networking security and cryptography is not my strong suit, and I don’t want to do it badly.

Side note: No security, and openness about it, is usually exponentially better than bad security. A bad implementation of encryption is worse than no encryption, as it gives a false sense of security, and opens one up to liability.

Torrents

How did I end up with a Torrent client? Well, I wanted to dowload some files, and I wanted to do it with a Torrent as it was a bunch of data science stuff, and it would take forever to download, so Torrent was the best option. I didn’t want to install anything, so I looked into Torrent Client libraries, and I found a few, and they were all pretty old and outdated, so I forked one, and I started to look into it, and spent a long time to get it into a usable state, and I called it Frank. TorrentClient. It is a simple Torrent client that is built on Dependency Injection and modern .net core features and have a couple of UI projects that are built on AvaloniaUI and WPF. It needs a lot of work, but it is usable for now.

A Game Framework/Engine? Seriously? What’s wrong with you?

So, I used to be a game developer, (unity), but I was always fighting the engine. I wanted to buold my own engine, or rather my own framework, and I did, and I called it Frank.GameEngine. It is a simple game framework that is built on the idea of interchangeable parts, so you can use whatever rendering engine you want, and whatever physics engine you want, and it should just work. Its pretty jankey, and it needs a lot of work, especially the collision detection.

Conclusion

So, I have made a lot of libraries, and I have made a lot of things, and I have learned a lot, and I have had a lot of “fun”, yet I still don’t have an IRC client/server library. The journey has been interesting, and while I have not reached my endgoal, I have made an ecosystem of libraries that are easy to use, and easy to extend, and that are built on Dependency Injection and modern .net core features. This has helped me be a better developer, but I still want my IRC client/server library to be a reality. I have a lot of ideas, and I have a lot of code, and I have a lot of experience.

The Future

Will I ever make an IRC client/server library? I don’t know, and now I have seen a few other technologies besides TCP that might be better suited for making a chat server. There is a lot of cool stuff out there, and I have a lot of ideas, so for now I will just keep on making stuff and see where it takes me. I am very interested in code generation, and it would be benefical to make a code generator for the IRC client/server library, as there are a lot of commands and events, and LLMs is a thing I have been looking into, and that also might be a good fit for the IRC server library, because building in a moderation chat bot would be cool.

References

• RFC 1459 — IRC Protocol
• RFC 2812 — IRC Client Protocol
• Microsoft Learn — ASP.NET Core / Kestrel
• Frank.BedrockSlim (GitHub)
• IRCv3 specifications

This post is part rant, part therapy, part actual spec for a thing called simple-installer because if I don’t write it down here, nobody will, including future me.

The project

It was just a small simple project: a simple installer tool called simple-installer. Pack a zip with metadata, install it. Nothing fancy.

It just needed to be able to:

• Pack a zip
• Unpack a zip
• Run as a CLI tool
• Be distributed through NuGet
• Run as a dotnet global tool

The problem

I got a lot done. Menus, zip in, zip out, CLI, NuGet. Then I hit “global tool” and realized I had no idea what to do next — and no breadcrumbs for how I got here in the first place.

It’s not perfect, but parts work. The problem is continuity: I don’t remember the decisions, and there is no documentation. No specs, no issues, no “why we chose this” anywhere except inside my skull, which is a terrible persistence layer.

The solution

Write this blog post and treat it as living documentation for the rest of the project. Yes, that is a ridiculous place for specs. It is still better than nowhere.

Facts: kinds of documentation that actually help

Opinion: any artifact beats brain-RAM. Fact: teams usually separate intent from procedure:

Architecture Decision Records were popularized for documenting significant technical choices in version control—short markdown files, immutable history, searchable blame.¹

For shipping a CLI installer as a .NET tool, Microsoft documents the packaging model explicitly: your package must declare the dotnet tool asset, expose an entry assembly, and consumers install with dotnet tool install -g <packageId> (or use a manifest for local tools).² NuGet’s own reference describes optional package types such as DotnetTool when authoring packages intended for that pipeline.³

None of that replaces a product spec—but it tells you where in the official docs to look once you admit you forgot what you were doing.

Practice: minimal spec outline for simple-installer

If you want something copy-pasteable:

1. Goal — zip-backed package format + manifest.json schema version.
2. Commands — pack, install, list, remove, update (even if some are stubs).
3. Distribution — NuGet package layout today; DotnetTool package type target state.
4. Non-goals — MSI, services, elevation stories you refuse to own.
5. Open questions — global tool vs framework-dependent bundle; signing.

That five-bullet skeleton is enough to stop thrashing.

Pitfalls I walked into

• Assuming “I’ll remember why this flag exists” (false—entropy wins).
• Shipping features without an issue number or ADR pointer (future you files a silent lawsuit).
• Mixing “blog post spec” with zero tests—this doc helps humans; automated checks still matter.

Let’s get started

The problem we are trying to solve (the specs)

Installers are unnecessary complex, and they usually have a lot of features that are not needed. So we want to make a simple installer tool that can do the following: Install a program, uninstall a program, update a program, and list installed programs.

The design

We want to make a CLI tool that can be used to install, uninstall, update and list installed programs. We want to make it as simple as possible, so we will use a simple zip file as the package format. The zip file will contain a manifest.json file that will contain the metadata for the package, and the files that will be installed.

Menu flow

graph TD
    A[Start Installer] -->|Check for ZIP file| B
    B -->|Yes| C[Show Menu with Install Option]
    B -->|No| D[Show Menu without Install Option]
    C -->|Select Install| E[Install Process]
    C -->|Select Pack| F[Pack Process]
    C -->|Select Exit| G[Exit Installer]
    D -->|Select Pack| F
    D -->|Select Exit| G
    E --> H[Return to Menu] -.-> B
    F --> |Pack completes| H 
    G --> I[End Installer]
    H --> C

[!NOTE] Use Chat Gpt-4 to generate some C# code

using System;
using System.IO;
using Spectre.Console;

class Program
{
    static void Main(string[] args)
    {
        Func<bool> isZipFilePresent = () => File.Exists("yourfile.zip");
        Action showMenu = () => ShowMenuWithSpectre(isZipFilePresent());

        showMenu();
    }

    static void ShowMenuWithSpectre(bool isZipPresent)
    {
        var cmd = AnsiConsole.Prompt(
            new SelectionPrompt<string>()
                .Title("Choose an [green]option[/]:")
                .AddChoices(new[] { "Pack", "Exit" })
                .AddChoiceIf(isZipPresent, "Install"));

        switch (cmd)
        {
            case "Pack":
                Pack();
                break;
            case "Exit":
                Exit();
                break;
            case "Install":
                if (isZipPresent)
                {
                    Install();
                }
                break;
        }
    }

    static void Pack()
    {
        AnsiConsole.MarkupLine("[yellow]Packing...[/]");
        // Packing logic here
    }

    static void Install()
    {
        AnsiConsole.MarkupLine("[green]Installing...[/]");
        // Installation logic here
    }

    static void Exit()
    {
        AnsiConsole.MarkupLine("[red]Exiting...[/]");
        Environment.Exit(0);
    }
}

References

• Microsoft Learn — Global tools
• Microsoft Learn — How to manage local tools
• NuGet — Set a package type
• ADR GitHub — Architecture Decision Records

Facts: where ML.NET sits in the ecosystem

ML.NET is Microsoft’s .NET-first ML stack—data loading (IDataView), training pipelines, evaluation metrics, and deployment patterns documented under Microsoft Learn. ¹

Model Builder (Visual Studio extension) and the mlnet CLI automate common scenarios (classification, regression, recommendation, computer vision) so you can iterate without writing boilerplate trainers by hand. ²

ONNX interoperability matters because academic and industry workflows often train in Python then export; ML.NET documents the ONNX Runtime dependency and how to run ONNX models from .NET. ³

Ethics / optics: game-adjacent demos (aim bots, wall hacks as pedagogy) should foreground responsible disclosure—teach detection and adversarial robustness, not cheat distribution. Microsoft publishes Responsible AI principles and Azure Machine Learning documentation on fairness, interpretability, and human review—useful guardrails even for scratch tutorials. ^{4 5}

Concept

Most ML.NET content falls into two buckets:

1. “Data scientists, look — C# exists.”
2. “C# devs, you can be ML people too, here is a spreadsheet and a dream.”

Both are fine. Neither is what I want to build. I want messier, more playful stuff: things you can break, things that feel like games, things where “don’t try this in prod” is the whole point. Yes, that includes the morally questionable territory of aim-bot-shaped pedagogy — teaching, not cheating. Calm down.

Episode 0

Draft / scratch lives in the monorepo of chaos:

• Episode 0 (markdown) on GitHub

If that link rots, the internet deserved it.

References

• Microsoft Learn — ML.NET documentation hub
• Microsoft Learn — What is ML.NET?
• Microsoft Learn — Model Builder
• Microsoft Learn — ML.NET CLI
• Microsoft Learn — Install ONNX Runtime to use with ML.NET
• Microsoft Learn — Save and load a model in ML.NET (general persistence; ONNX loading is covered in ONNX-specific topics above)
• ONNX Runtime (GitHub)
• Microsoft — Responsible AI
• Microsoft Learn — Responsible machine learning (Azure ML)

Facts: what we thought we were assembling

ML.NET is Microsoft’s machine-learning stack for .NET—training via CLI / Model Builder / notebooks and inference loaded into apps using standardized loaders for ONNX / TF formats depending on scenario.¹

ONNX describes models so frameworks can exchange graphs; ML.NET documents ONNX as a first-class interchange path alongside native trainers.²

TensorFlow Object Detection API is Google’s Python-centric pipeline for training detectors—the tutorials assume coherent CUDA + protobuf stacks, which is exactly where “works on my laptop” dies.

tensorflow-onnx (tf2onnx) is the community converter we leaned on to escape TensorFlow graphs toward ONNX—silent failures in converters are doubly painful because you stare at success logs while files never appear.³

This factual scaffolding does not make the pain fake—it explains why “marketing-simple ≠ dependency-simple.”

“Do something with ml.net” was the task given by the cool guys and gals from the ML.NET community. That’s easy enough, right? WRONG!!! It’s stressful and frustrating.

The idea was to use a game that have been re-created as Open Source in C#. Two alternatives was the most promising: OpenRA, and ManagedDoom, (Red Alert and Doom). We quickly found it to be above our skill level to to something with Red Alert, so Doom it was, and what an apt title for our little team.

ML.net plays Doom

Having Ml.net play Doom seemed to be fun, and educational, it would also be a rare addition to the content people have been making, (not a lot of ml.net have been used for gaming, so it could really be something new and exciting). We found a great tutorial with code for object detection using onnx-models in ml.net, and having an algorithm that remembers how it moves forward, detects an enemy and learns that pattern can be achieved by other

The team

We were 4 people, (and beer), three “full” developers and one junior. The junior had some tutorials with machine learning under her belt and C# skills. One of the devs was mainly a Kotlin dev, and the remaining two was .net developers, one working for an AI/ML based fintech company. We called ourselves “Omega Force” because Frank already had created a GitHub organization with that name, and it’s cool. A small snag became apparent pretty quickly and that was that the Kotlin dev expected C# to be pretty simple, but found it confusing, and also other things came up that he had to take care of. One of the C# devs needed some RnR and threw in the towel almost immediately. There we were with 30% of the C# skills gone, and the moral-boosting Kotlin dev was suddenly also unavailable…

Keep calm and code on

A bit frustrated, we started attacking the issue, and five minutes after a good nights sleep it didn’t seem too bad, we had a nice example of how to use ml.net to identify objects in an image. The example used an object labeling tool called labelimg that require one to go through every image and created boxes around objects that are then tagged, and it saves an xml-file per image. Having sprites from Doom made it really easy to just write a few lines of C# code and make the XML based on the entire image being the “box” to be labeled. 1400 sprites took 15 minutes to process:2 minutes of manual tagging, 1 minute of thinking 10 minutes of programming, and 2 minutes for the app to run. Armed with XML-files and the sprites we got going trying to setup Anaconda, Tensorflow, NVidia CUDA-stuff, and a bunch more…

it didn’t go well…

Troubles with Tensorflow

When you look at tutorials and documentation it looks so easy, but we tried many times, but nothing seems to work… What do you do then??? Drink a lot, cry a lot, and yell at people for no reason a lot. It’s one thing to have a hard time doing something difficult, but when it seems so easy in the tutorials, making it seem like it takes ten minutes to get started. But error message like Python not finding object_detection.utils leads down a path of misery and self-loathing as you read the snarky answers to anyone brave enough to have asked a question online about it, (when you have done a pip install object_detection without errors, you expect it to just work). You finally build up the curage to ask the question to ask a question on stack overflow, and then there are no shortage of downvotes, (a small line encuraging downvoters to comment to help improve the question was edited away almost instantly), but you get that one comment that gets you over the hurdle, (turned out that ProtoBuf didn’t install correctly, and the errors are easy to miss).

A few more hours go on and we finally can start training… FOUR DAYS INTO THE HACKATHON!!! And the defaults take about 18 hours to train on a 95th percentile powerful computer… And paying a couple of hundred dollars for cloud computing to fastrack it, isn’t feasable

Houston we have a model

So finally we had a model, (we created a barely trained one just to experiment), now it’s just converting it from TF to ONNX, and that can’t be hard, right? It’s not according to the documentation… And we run it, it takes 15 minutes, with the Red Bull to blood ratio being about 2:1 in our bodies, we gather around and and then our moment of elation ends when the model.onnx file isn’t there… Maybe it was saved someplace weird? Start searching C:\ for *.onnx, and get a bunch of false positives… Now the tears are starting to well up as one realizes that there are not a single line of actual, functional, (as in working, not paradigmic), code and there is 30 hours left of the hackathon… When looking at the source code for tf2onnx, it’s aparent that it just quits at some random point without an error message or any kind of logging… Should we give up? Should we surrender to the dispair?? It’s so tempting…

Scope narrowing

Having reduced to the bearest of scopes, it seems like a win to have created an aimbot, and learned to at least use the tools available, but even that seems too abitious 30 hours before the deadline… Maybe this rant, blog, whatever, is the only actual result of the entire catastrophy

Exploring the Tensorflow model

Using Netron to view the created .pb-model file, which took 17 hours to train, 3 days to even start the training, and now it seems wrong, having 1400 “nodes” as inputs, error messages about unknown types and takes ten minutes to open. Something is crazy wrong and noone have any ideas… The internet keeps presenting these steps as easy and straight forward yet it’s anything but. We had the idea that since Tensorflow and all this ML stuff is presented as such plug-n-play -processes that anyone can do it, it shouldn’t be too hard to get a model going. But with two people spending hours each day reading, experimenting, and watching online tutorials, the easy part seems to be a marketing ploy from Google, and that Google as a service is hiding anything indicating it’s not super-duper-awesome-easy to do ML training and conversion… Also, I HATE PYTHON! The language is clumsy, (significant whitespace is an abomination, and herecy against the natural order of the univers), but the entire ecosystem is so fragile that you update one thing, that updates something else, that then breaks the functionality of the .py file you try to run, and you end up going into actual libraries and tweaking code… How can people rave about Python as the greatest thing since the invention of fire, I have no idea…

What to do now?

The original MASH movie, (that spawned the excellent TV show with the same name), has a theme song that has been stuck in my head for most of this process, it’s lyrics is very fitting for the situation, (look it up). Maybe, just maybe, there is a chance that someone can help us? Mayby @luisquintanilla or @briacht can assist? They seem like very nice an knowledgable people, only one snag.. How to contack them? O.o

Turns out email is a powerful tool! Bri was reasonably quick to answer and forward our plea for help to Luis, who was very helpful, (I have yet to interact with a Microsoft employee that isn’t service-minded and likable). Luis got us “on track” but with very little time remaining, and only 1.5 people of the initial 4 left on the team, delivering anything seems impossible.

Oh! Microsoft’s Model Builder has object detection <3

So as a last ditch effor to salvage this situation, I throw toghether some code to make Vott Json for my sprites, and lob it up into Azure, hoping I can afford it, (turns out that it’s not possible to setup anything really expensive for some reason). three hours later, it fails… I reduce the data complexity by only having one “label” and about 600 sprites. It takes almost two hours to finish, but when I plug in the model into my simplified WPF-app, (uses a still-image during development, in stead of capturing the game using OpenCvSharp), it give a 0,999876 score on the top left quadrant of the image. The area the model claim to have an enemy is

The surrender

Now it’s just me at 04:00 UTC with 4 hours left until the deadline and all there is to show for all this time is a lot of frustration, regret and self-loathing. I didn’t even get to drink as much beer as I planned… There will be no entry

, at least I have a lot of experiences to bring with me.

References

• Microsoft Learn — What is ML.NET?
• Microsoft Learn — ONNX models in ML.NET
• tensorflow-onnx (GitHub)
• TensorFlow Object Detection API tutorial (ReadTheDocs)
• ML.NET object detection sample (GitHub — fralik)
• ScreenRecorderLib (GitHub)
• VB Studio — Wolfenstein / NEAT article

Useful snippets

|Description|| |—|—| |Convert .pd to .onnx comand|python -m tf2onnx.convert --input /exported-models/doom1/saved_model/saved_model.pb --inputs input_1:0 --outputs probs/Softmax:0 --output model2.onnx| |Train model|python model_main_tf2.py --model_dir=models --pipeline_config_path=models/pipeline.config| |Convert *-xmls to tfrecords|python generate_tfrecord.py -x images/train -l annotations/label_map.pbtxt -o annotations/train.record|

Fair warning: this is not ISO-8601 fanfic. It is me being annoyed in a structured way.

TL;DR

Time and dates are hard. Store UTC instant (often as UNIX milliseconds or DateTimeOffset with explicit offset), render local with explicit timezone rules, and never pretend culture-specific strings round-trip.

Facts: what the standards actually say

RFC 3339 defines a profile of ISO 8601 for timestamps on the Internet—think 2012-10-03T12:13:00Z. It exists precisely because naive date strings caused interoperability pain.¹

ISO 8601 is the broader international standard for representing dates and times; many APIs colloquially say “ISO 8601” when they mean something closer to RFC 3339.²

POSIX time counts seconds since the Unix epoch (1970-01-01T00:00:00Z), ignoring leap seconds in the usual time_t encoding—so “Unix seconds” is not always identical to civil atomic clocks, but it is what most databases and APIs mean when they say unix.³

.NET specifics: DateTimeOffset captures an instant with an offset; plain DateTime can represent UTC, local, or “unspecified,” and mixing those modes is a historical footgun Microsoft documents explicitly.⁴ Internally .NET also exposes ticks (100 ns intervals since midnight 0001-01-01 UTC on the Gregorian calendar)—finer than milliseconds when you need monotonic-ish stamps inside one machine.⁵

Popular culture check: Patrick McKenzie’s Falsehoods programmers believe about time catalogs edge cases (DST, leap seconds, historical calendar reforms) that invalidate “just parse the string” optimism.⁶

Why is time important?

You might think that for a simple chat app, there’s no need to use time, but you should always include time. It’s a great way to sort, though this might be acheived by some auto-incremented number.

Fact: totally ordered message IDs can sort without clock sync; practice: you still want human-visible ordering and reconciliation when replicas diverge—timestamps (with sane collision handling) remain the default hammer.

What DateTime format to use?

There are plenty of libraries to convert time and dates to whatever format you want, so why not just use what you use in your daily life? Let me show you:

Some examples of the same DateTime (seconds an milliseconds omitted, mostly)

You might be confused by the “snowflaking” of the US in all of this, but it has it’s reasons, mostly the unwillingness to risk confusion among it’s citizens. However the US Military does use the the UTC time,

You might say “hey, how about my country/culture’s calendar? This is awefully eurocentric”, and yes it is completely correct and a good point to make. Here’s some examples of calendars from around the world that is in use today:

there are scores upon scores of others, some only used by tribes in micronesia or in the himalayas, (that there’s probably a conversion for anyway, because developers love a challange, or some social anthropologist needs it in their research

I will not denegrade the non-gregorian calanders, and they are useful for those who share them, but I don’t think I’ll be using Dragon-dog-18, (though if I were, I would have to have some logic to assume it’s the closest Dragon in the last 12 years)

But what about Timezones?

Short answer is: Ignore it, and use a universal time with conversion logic!

Great video about timezones every dev should watch:

Tom Scott’s piece on YouTube walks through why civil time is political—worth pairing with the Olson/tz database maintained as IANA Time Zone Data.⁷

Conclusion: use millisecond UNIX time

The computer counts in this time unit, (.net actually has a unit caller “ticks” that is MUCH smaller)

Practice recap:

1. Persist an unambiguous instant (UTC / offset-aware / epoch ms).
2. Convert for display with explicit timezone rules (TimeZoneInfo, Noda Time, etc.).
3. Never treat locale-formatted strings as canonical keys—they are lossy projections.

References

• RFC 3339
• Microsoft Learn — DateTime best practices
• Microsoft Learn — Time zones
• IANA Time Zone Database
• Patrick McKenzie — Falsehoods programmers believe about time
• Tom Scott — YouTube on timezones