Csharp on ELL Blog

WinUI3 Single Instance and URI Protocol

Tue, 07 Jul 2026 23:22:09 -0400

For the last few months, I’ve been working with WinUI 3 and dealing with some of its quirks.

When following the WinUI 3 Single-Instance & Protocol Activation tutorial, our app had multiple issues regarding activation and URI handling.

Focus issue.
Crash after opening hidden window from URI (app was running in tray).

First I will provide the up to date code, and then I will provide some explanation behind what is going on.

Putting it all Together

Appxmanifest (for packaged apps or packaged with external location apps)

<Application ...>
<!-- ... -->
  <Extensions>
        <uap:Extension Category="windows.protocol">
          <uap:Protocol Name="obscuravpn">
            <uap:DisplayName>App Name</uap:DisplayName>
          </uap:Protocol>
        </uap:Extension>
      </Extensions>
      <!-- ... -->
</Application ...>

NativeMethods.txt assuming the use of CsWin32

SetForegroundWindow
ShowWindow

// MainWindow.xaml.cs
internal HWND GetWindowHandle()
    {
        return (HWND)WinRT.Interop.WindowNative.GetWindowHandle(this);
    }

internal async void HandleAppUrl(Uri uri)
    {
        Log.Info("HandleAppURL called");
        switch (uri.AbsolutePath)
        {
            case "/settings":
                SelectNavigationView(NavigationView.Account);
                break;
            default:
                Log.Warn($"Unhandled app path: {uri.AbsolutePath}");
                break;
        }
    }

// NavigationView is an enum, which is used by MainWindow.xaml (NavigationView tutorial coming later)
// Must be called on window's creation thread (e.g. via dispatcher queue)
// Note that there should be a way to have enums on the Tags. I have not gotten to that cleanup yet.
internal void SelectNavigationView(NavigationView view)
    {
        var item = NavView.MenuItems.Concat(NavView.FooterMenuItems)
            .OfType<NavigationViewItem>()
            .FirstOrDefault(i => i.Tag is int tag && tag == (int)view);
        if (item == null)
        {
            Log.Warn($"No navigation pane item for view: {view}");
            return;
        }
        NavView.SelectedItem = item;
    }

// App.xaml.cs
using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using log4net;
using log4net.Appender;
using log4net.Config;
using log4net.Layout;
using Microsoft.UI.Dispatching;
using Microsoft.UI.Xaml;
using Microsoft.Windows.AppLifecycle;
using Microsoft.Windows.AppNotifications;
using Microsoft.Windows.AppNotifications.Builder;
using Windows.Win32;
using Windows.Win32.Foundation;
using Windows.Win32.System.Com;
using Windows.Win32.UI.WindowsAndMessaging;

namespace AppName;

public partial class App : Application
{
    static readonly ILog Log = LogManager.GetLogger(typeof(App));
    public new static App Current => (App)Application.Current;
    MainWindow? _window;

    protected override void OnLaunched(LaunchActivatedEventArgs launchArgs)
    {
        _window = new MainWindow();

        var args = AppInstance.GetCurrent().GetActivatedEventArgs();
        if (args.Kind != ExtendedActivationKind.StartupTask)
        {
            ShowMainWindow();
        }
        HandleActivation(args);
    }

    private void HandleActivation(AppActivationArguments activationArgs)
    {
        if (activationArgs.Kind == ExtendedActivationKind.Protocol
            && activationArgs.Data is Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs protocolArgs)
        {
            Log.Info($"handling protocol activation: {protocolArgs.Uri}");
            _window?.DispatcherQueue.TryEnqueue(() => _window.HandleAppUrl(protocolArgs.Uri));
        }
    }

    internal void ShowMainWindow()
    {
        Log.Info("activating main window");

        //  This should only happen if  you allow it to be destroyed instead of hiding it on close
        if (_window == null)
        {
            Log.Warn("creating new main window");
            _window = new MainWindow();
        }

        PInvoke.ShowWindow(_window.GetWindowHandle(), SHOW_WINDOW_CMD.SW_NORMAL);
        PInvoke.SetForegroundWindow(_window.GetWindowHandle());
        Log.Info("activated main window");
    }

    /// <summary>
    /// Before booting the WinUI runtime, we claim the single-instance key. A redundant launch hands
    /// its activation to the primary instance and exits immediately; One UI process ever runs.
    /// </summary>
    [STAThread]
    static void Main()
    {
        ConfigureLogging();
        Log.Info("App instance launched; Logging initialized");
        try {
            WinRT.ComWrappersSupport.InitializeComWrappers();
            Log.Info("COM wrappers initialized");
        } catch (Exception ex)
        {
            Log.Error($"Failed to initialize COM wrappers. Not pumping COM. {ex}");
        }

        if (DecideRedirection())
        {
            // Activation has been handed to the primary instance
            return;
        }

        Start((p) =>
        {
            var context = new DispatcherQueueSynchronizationContext(DispatcherQueue.GetForCurrentThread());
            SynchronizationContext.SetSynchronizationContext(context);
            _ = new App();
        });
    }

    /// <summary>
    /// Claims the single-instance key. Returns true if this process is a redundant launch whose
    /// activation has been redirected to the primary instance (and should therefore exit).
    /// </summary>
    private static bool DecideRedirection()
    {
        var keyInstance = AppInstance.FindOrRegisterForKey("primary");
        if (keyInstance.IsCurrent)
        {
            // Handle redirect activations of subsequent launches
            keyInstance.Activated += OnRedirectActivated;
            return false;
        }
        // Subsequent launches will redirect activation to the primary instance
        var activationArgs = AppInstance.GetCurrent().GetActivatedEventArgs();
        RedirectActivationTo(activationArgs, keyInstance);
        return true;
    }

    private static void RedirectActivationTo(AppActivationArguments activationArgs, AppInstance keyInstance)
    {
        // A single-thread apartment (STA) must pump messages while idle to avoid jamming up window broadcasts
        // The redirect activation is waited using a method that continues dispatching messages
        using var redirectComplete = new ManualResetEvent(false);
        var redirectTimeout = TimeSpan.FromSeconds(32);
        using var cts = new CancellationTokenSource(redirectTimeout);
        Task.Run(() =>
        {
            try
            {
                keyInstance.RedirectActivationToAsync(activationArgs).AsTask(cts.Token).GetAwaiter().GetResult();
            }
            catch (OperationCanceledException)
            {
                Log.Error($"Failed to activate existing instance; timed out after {redirectTimeout}.");
            }
            catch (Exception ex)
            {
                Log.Error("Failed to activate existing instance", ex);
            }
            finally
            {
                redirectComplete.Set();
            }
        });
        var handle = new HANDLE(redirectComplete.SafeWaitHandle.DangerousGetHandle());
        PInvoke.CoWaitForMultipleObjects((uint)CWMO_FLAGS.CWMO_DEFAULT, PInvoke.INFINITE, [handle], out _);
    }

    private static async void OnRedirectActivated(object? sender, AppActivationArguments args)
    {
        Current.ShowMainWindow();
        Current.HandleActivation(args);
    }
}

Focus Issue

In the tutorials that existed/created before this one, the code would result in your window being shown without keyboard/input focus (greyed out titlebar title). The fix for this is to call SetForegroundWindow after Activate, and not on the dispatcher queue. Because activate has to be run on the dispatcher queue, we can simply replace activate with the native WinRT method ShowWindow.

Add methods to NativeMethods.txt (I recommend using CsWin32 to avoid having to manually write out DllImports).

SetForegroundWindow
ShowWindow

// App.xaml.cs
internal void ShowMainWindow()
  {
      Log.Info("activating main window");
      if (_window == null)
      {
          Log.Warn("creating new main window");
          _window = new MainWindow();
      }
      PInvoke.ShowWindow(_window.GetWindowHandle(), SHOW_WINDOW_CMD.SW_NORMAL);
      PInvoke.SetForegroundWindow(_window.GetWindowHandle());
      Log.Info("activated main window");
  }

private static async void OnRedirectActivated(object? sender, AppActivationArguments args)
{
  Current.ShowMainWindow();
  Current.HandleActivation(args);
}

// MainWindow.xaml.cs
internal HWND GetWindowHandle()
    {
        return (HWND)WinRT.Interop.WindowNative.GetWindowHandle(this);
    }

The Crash Bug I Was Facing

Opening appname:///location would crash the app when the app was running with the window closed. Here is a minimum reproducible of the crash. My guess is that activationArgs.Data causes issues.

// App.xaml.cs
// keyInstance.Activated += OnRedirectActivated;
private static async void OnRedirectActivated(object? sender, AppActivationArguments args)
    {
        Current.ShowMainWindow();
        Current._window?.DispatcherQueue.TryEnqueue(() => Current.HandleActivation(args));
    }

private void HandleActivation(AppActivationArguments activationArgs)
    {
        //CRASH
        Log.Info($"activationArgs.Kind: {activationArgs.Kind}");
        Log.Info($"activationArgs.Data Type: {activationArgs.Data.GetType()}");
        //CRASH
    }

WebView2's GetDevToolsProtocolEventReceiver Will Crash Your WinUI App if You Don't Store the Receiver

Mon, 25 May 2026 15:14:31 -0400

I spent the last week investigating a crash in a WinUI 3 + WebView2 app on Windows ARM64. I was encountering seemingly random Memory Access Violation exceptions thrown from inside the WebView2 DLLs, with no useful stack trace. The cause turned out to be due to not storing a event receiver.

What is a DevTools Protocol Event Receiver?

WebView2 lets you subscribe to Chrome DevTools Protocol (CDP) events from .NET — things like “the page logged something to the console,” “the page navigated,” “an uncaught exception was thrown in JavaScript.” The API for this looks like:

var receiver = WebView.CoreWebView2.GetDevToolsProtocolEventReceiver("Runtime.consoleAPICalled");
receiver.DevToolsProtocolEventReceived += MyHandler;

The class returned by GetDevToolsProtocolEventReceiver is a CoreWebView2DevToolsProtocolEventReceiver. I’ll just call it a receiver for the rest of this post.

A receiver is a managed (.NET) wrapper around a native WebView2 event source. You ask WebView2 “give me the receiver for event X,” and from then on, anything that happens in the embedded browser that matches event X fires the receiver’s DevToolsProtocolEventReceived event. You subscribe to that event in the normal C# way (+=), and your handler runs on the UI thread when WebView2 dispatches.

The whole API feels like any other .NET event publisher. It is not.

The Bug, in One Line

This is the minimal repro:

WebView.CoreWebView2
    .GetDevToolsProtocolEventReceiver("Runtime.consoleAPICalled")
    .DevToolsProtocolEventReceived += (s, e) => OnWebviewConsoleApiCall(e.ParameterObjectAsJson);

The bug is that nothing in my code holds a reference to the receiver. The expression chain calls GetDevToolsProtocolEventReceiver, subscribes a handler, and discards the receiver. From the GC’s perspective, the receiver is unreachable the instant the statement finishes.

Based on my conversation with Claude, I think I can understand what happened.

DevToolsProtocolEventReceived::add, the delegate, in this case a pointer to calling (s, e) => OnWebviewConsoleApiCall(e.ParameterObjectAsJson)does not store a reference to the pointer, but calls subscribe directly. This wasn’t always the case, since the definition for DevToolsProtocolEventReceived add calls something called Get_DevToolsProtocolEventReceived2.

When we store a reference to the receiver, we keep alive CoreWebView2DevToolsProtocolEventReceiver’s own fields. In particular _inner. So it seems that whatever pointer variable holds a reference to our callback function is dependent on the preservation of _inner. When we don’t hold a reference to _inner which is an ID, it seems that whatever inner is pointed to (Claude thinks a COM object) could also be freed.

So it ends up being on us to keep a reference to the receiver returned byGetDevToolsProtocolEventReceiver.

The Fix

Store the receiver in a field:

private CoreWebView2DevToolsProtocolEventReceiver? _consoleReceiver;

_consoleReceiver = WebView.CoreWebView2.GetDevToolsProtocolEventReceiver("Runtime.consoleAPICalled");
_consoleReceiver.DevToolsProtocolEventReceived += (s, e) => OnWebviewConsoleApiCall(e.ParameterObjectAsJson);

A field on the page or window keeps the receiver alive for the lifetime of that page or window, which is exactly what you want. The crash disappears completely. The handler — lambda or method group, doesn’t matter — fires correctly forever after.

For multiple subscriptions, just add more fields:

private CoreWebView2DevToolsProtocolEventReceiver? _logEventReceiver;
private CoreWebView2DevToolsProtocolEventReceiver? _consoleReceiver;
private CoreWebView2DevToolsProtocolEventReceiver? _exceptionReceiver;

_logEventReceiver = WebView.CoreWebView2.GetDevToolsProtocolEventReceiver("Log.entryAdded");
_logEventReceiver.DevToolsProtocolEventReceived += OnWebviewLogEntry;

_consoleReceiver = WebView.CoreWebView2.GetDevToolsProtocolEventReceiver("Runtime.consoleAPICalled");
_consoleReceiver.DevToolsProtocolEventReceived += (s, e) => OnWebviewConsoleApiCall(e.ParameterObjectAsJson);

_exceptionReceiver = WebView.CoreWebView2.GetDevToolsProtocolEventReceiver("Runtime.exceptionThrown");
_exceptionReceiver.DevToolsProtocolEventReceived += OnWebviewException;

If you’d rather not pollute your class with three fields, a list works too:

private readonly List<CoreWebView2DevToolsProtocolEventReceiver> _receivers = new();

CoreWebView2DevToolsProtocolEventReceiver Subscribe(
    string eventName,
    EventHandler<CoreWebView2DevToolsProtocolEventReceivedEventArgs> handler)
{
    var r = WebView.CoreWebView2.GetDevToolsProtocolEventReceiver(eventName);
    r.DevToolsProtocolEventReceived += handler;
    _receivers.Add(r);
    return r;
}

Subscribe("Log.entryAdded", OnWebviewLogEntry);
Subscribe("Runtime.consoleAPICalled", OnWebviewConsoleApiCall);
Subscribe("Runtime.exceptionThrown", OnWebviewException);

Whose Bug Is It?

I went back and forth on this one. My initial conclusion — that the bug was in my code — was based on the lambda-pinning theory, which turned out to be wrong. Once you take that explanation off the table, the case for “user code bug” gets much weaker.

The code that crashes is idiomatic C#. It follows the same pattern as every other event subscription in the BCL, in WPF, in WinForms, in WinUI. It produces no compiler warnings, no analyzer warnings, no documentation hint, nothing. The fact that it silently breaks because WebView2’s receiver doesn’t keep itself alive is a WebView2 API design issue, not a user code issue.

The strongest evidence for this is that Claude Code — trained on a vast corpus of C# code — wrote the buggy version by default. So did I, several times, over several days, while actively trying to fix the crash. That’s not a “one developer didn’t read the docs” problem; that’s “the API expects something the entire C# ecosystem doesn’t do.”

A correctly designed managed wrapper for a native event source should either keep itself alive while it has live subscriptions, or document the requirement loudly. WebView2 does neither.

I filed an issue on the WebView2Feedback repo.

Why Doesn’t Tooling Catch This?

Static analysis could in principle catch “you called a method that returned an object, subscribed to an event on it, and then discarded the reference.” But no current analyzer does this for events specifically, because for almost every other event in C#, that pattern is fine. The publisher is usually rooted by something else, so the discarded local doesn’t matter.

A WebView2-specific analyzer (a Roslyn analyzer shipped in the WebView2 NuGet package) could flag this. That would be the right place to fix it long-term — even if Microsoft never changes the receiver’s lifetime semantics, an analyzer catching [].DevToolsProtocolEventReceived += ... on a non-stored receiver would prevent the crash entirely.

The Takeaway

If you use WebView2’s DevTools Protocol event receivers in .NET, store them in fields. Don’t subscribe inline. Don’t store the receiver in a local. The compiler will not warn you. The runtime will not warn you. The app will simply crash randomly during normal use, and the stack trace will not point at your code.

It’s one line of code to fix and zero lines of code to introduce — exactly the shape of bug that wastes weeks of debugging.

C# Partial Json Deserialization

Sun, 24 Nov 2024 23:56:41 -0500

I started writing this article all the way back in March but only got to finishing it now since I needed it for an XUnit test I was writing.

Suppose we want to consume a REST API that has extra data for paging or something else but we just want to mutate or use the data portion.

{
  "_request_": {
    "url": "/collection",
    "count": 50,
    "pages": 20,
    "total": 200,
    "next": "/collection?page=:number",
    "prev": "/collection?page=:number",
    "first": "/collection?page=:number",
    "last": "/collection?page=:number"
  },
  "data": [
    {
      "id": 0,
      "name": "string"
    }
  ]
}

How do we only deserialize the data portion?

Relevant methods:

After using these methods to navigate the JSON, you can use deserialization methods or object instantiation to use types for the data you actually care about.

Real code example (not related to sample JSON).

var jsonObject = await JsonNode.ParseAsync(response.Content.ReadAsStream());
foreach (var car in jsonObject!["data"]!.AsArray()) {
    carModels.Add(new CarModel {
        TrimId = car!["id"]!.Deserialize<uint>(),
        TrimName = car["description"]!.ToString(),
        ModelName = car["make_model"]!["name"]!.ToString()
    });
}

Some notes regarding the code above: CarModel is defined elsewhere, Visual Studio will automatically add the necessary import statements, and it assumes that you already know how to make a request with error handling. If you are interested in how I consumed all the pages of this API, here is some more code.

uint page = 1, totalPages = 1;
List<CarModel> carModels = [];
while (page <= totalPages) {
    var requestUrl = $"trims?&page={page}&verbose=yes&limit=50&year={year}&make_id={makeId}";
    var request = new HttpRequestMessage(HttpMethod.Get, requestUrl);
    var response = await CarApiRequest(request);

    var jsonObject = await JsonNode.ParseAsync(response.Content.ReadAsStream());
    foreach (var car in jsonObject!["data"]!.AsArray()) {
        carModels.Add(new CarModel {
            TrimId = car!["id"]!.Deserialize<uint>(),
            TrimName = car["description"]!.ToString(),
            ModelName = car["make_model"]!["name"]!.ToString()
        });
    }
    totalPages = jsonObject["collection"]!["pages"]!.Deserialize<uint>();
    // Normally I would use the "next" property to figure out the next "resource" to request. However, with this particular API, their next URL was not correct (infinite loop), so I built the URL instead since I'm not delaying the time to release..
    // if (jsonObject["collection"]!["next"]!.AsValue().ToString() == "") break;
    page++;
}

C# How to Uri Encode Strings and Queries

Fri, 29 Mar 2024 15:01:59 -0400

Use System.Uri.EscapeDateString

// using System;
var email = "email@gmail.com";
var url = $"/send-email?email={Uri.EscapeDataString(email)}";

In an ASP.NET Integration test:

[Fact]
public async Task TestPayouts() {
    var client = _factory.CreateClient();
    var url = $"/test/inc-payout?email={Uri.EscapeDataString(Constants.PAYOUT_TEST_ACCOUNT)}";
    var response = await client.PostAsync(url, null);

    response.EnsureSuccessStatusCode();
}

ASP.NET Core Add Versioning to Endpoints

Thu, 07 Mar 2024 02:05:53 -0500

Introduction

Applicable .NET versions: .NET 9, .NET 8.

.NET 9 uses OpenAPI and Scaler (Swagger replacement) and requires hardcoding the versions in one file. I have provided a list of packages I installed in my project in case your project is missing a necessary package.
.NET 8 does not need to hardcode the applicable versions, but does use Swagger.

This tutorial will save you ~5 hours. I don’t know when I started adding API version support to my ASP.NET project, but I can tell you that the current documentation is atrocious if you strive for perfection like I do.

There are two main ways to do API versioning in my eyes. The first way, which is what I thought I would’ve added in the future, is to be one of those companies with apis like /v2/my-api but then I found out about header APIs where the client can select the version by using a header. This saves a lot of developing time because all of my endpoints were /name not /v1/name and there were already released/production clients which were calling them without a version specified in the header.

NuGet Packages

In .NET 9, I needed the following Asp.Versioning packages

Asp.Versioning.Http
Asp.Versioning.Http.Client
Asp.Versioning.Mvc.ApiExplorer
Scalar.AspNetCore

You can either use VSCode’s C# Dev Kit, Visual Studio’s Nuget Packages UI, or the dotnet CLI to install these packages. For example, dotnet add <PROJECT> package <PACKAGE_NAME>

If you’re using Visual Studio, you could also run nuget install Asp.Versioning.Mvc.ApiExplorer

.NET 9 Versioning

In .NET 9, we no longer need a ProgramAuxiliary.cs.

OpenApi.Extensions.cs

using Asp.Versioning;
using Scalar.AspNetCore;

namespace SttApi;

public static partial class Extensions {
    public static IApplicationBuilder UseDefaultOpenApi(this WebApplication app) {
        var configuration = app.Configuration;
        var builder = app.MapOpenApi().CacheOutput();
        var scalerBuilder = app.MapScalarApiReference(options => {
            // Disable default fonts to avoid download unnecessary fonts
            options.DefaultFonts = false;
            options.Title = "Split The Tank API Reference";
            options.EnabledClients = [ScalarClient.Fetch, ScalarClient.HttpClient, ScalarClient.Nsurlsession, ScalarClient.OkHttp];
            // TODO: add default berar
            // TODO: order actions by
            //     options.OrderActionsBy(apiDesc => {
            //         var priority = apiDesc.ActionDescriptor.RouteValues["controller"]!.Contains("Debug") ? "_" : "";
            //         return $"{priority}{apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.HttpMethod}";
            //     });
            // .WithHttpBearerAuthentication(bearer => bearer.Token = "");
        });
        if (app.Environment.IsDevelopment()) {
            app.MapGet("/", () => Results.Redirect("/scalar/v1")).ExcludeFromDescription();
        } else {
            // Return 404
            builder.RequireAuthorization("ApiDeveloperPolicy");
            scalerBuilder.RequireAuthorization  ("ApiDeveloperPolicy");
        }
        return app;
    }

    public static IHostApplicationBuilder AddDefaultOpenApi(
        this IHostApplicationBuilder builder,
        IApiVersioningBuilder? apiVersioning = default) {
        var openApi = builder.Configuration.GetSection("OpenApi");
        var identitySection = builder.Configuration.GetSection("Identity");

        var scopes = identitySection.Exists()
            ? identitySection.GetRequiredSection("Scopes").GetChildren().ToDictionary(p => p.Key, p => p.Value)
            : new Dictionary<string, string?>();

        if (apiVersioning is not null) {
            // the default format will just be ApiVersion.ToString(); for example, 1.0.
            // this will format the version as "'v'major[.minor][-status]"
            var versioned = apiVersioning.AddApiExplorer(options => options.GroupNameFormat = "'v'VVV");
            // Search code base for [ApiVersion(#.0)]
            string[] versions = ["v1", "v2"];
            foreach (var description in versions) {
                builder.Services.AddOpenApi(description, options => {
                    if (openApi.Exists()) {
                        options.ApplyApiVersionInfo(openApi.GetRequiredValue("Document:Title"), openApi.GetRequiredValue("Document:Description"));
                    }
                    options.ApplyAuthorizationChecks([.. scopes.Keys]);
                    options.ApplySecuritySchemeDefinitions();
                    options.ApplyOperationDeprecatedStatus();
                    options.ApplyApiVersionDescription();
                    options.ApplySchemaNullableFalse();
                    // Clear out the default servers so we can fallback to
                    // whatever ports have been allocated for the service by Aspire
                    options.AddDocumentTransformer((document, context, cancellationToken) => {
                        document.Servers = [];
                        return Task.CompletedTask;
                    });
                });
            }
        }

        return builder;
    }
}

This next file also includes Bearer Authentication information which is used by Scalar.

OpenApiOptionsExtensions.cs

using System.Text;
using Asp.Versioning.ApiExplorer;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Primitives;
using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;

namespace SttApi;

internal static class OpenApiOptionsExtensions
{
    public static OpenApiOptions ApplyApiVersionInfo(this OpenApiOptions options, string title, string description)
    {
        options.AddDocumentTransformer((document, context, cancellationToken) =>
        {
            var versionedDescriptionProvider = context.ApplicationServices.GetService<IApiVersionDescriptionProvider>();
            var apiDescription = versionedDescriptionProvider?.ApiVersionDescriptions
                .SingleOrDefault(description => description.GroupName == context.DocumentName);
            if (apiDescription is null)
            {
                return Task.CompletedTask;
            }
            document.Info.Version = apiDescription.ApiVersion.ToString();
            document.Info.Title = title;
            document.Info.Description = BuildDescription(apiDescription, description);
            return Task.CompletedTask;
        });
        return options;
    }

    private static string BuildDescription(ApiVersionDescription api, string description)
    {
        var text = new StringBuilder(description);

        if (api.IsDeprecated)
        {
            if (text.Length > 0)
            {
                if (text[^1] != '.')
                {
                    text.Append('.');
                }

                text.Append(' ');
            }

            text.Append("This API version has been deprecated.");
        }

        if (api.SunsetPolicy is { } policy)
        {
            if (policy.Date is { } when)
            {
                if (text.Length > 0)
                {
                    text.Append(' ');
                }

                text.Append("The API will be sunset on ")
                    .Append(when.Date.ToShortDateString())
                    .Append('.');
            }

            if (policy.HasLinks)
            {
                text.AppendLine();

                var rendered = false;

                foreach (var link in policy.Links.Where(l => l.Type == "text/html"))
                {
                    if (!rendered)
                    {
                        text.Append("<h4>Links</h4><ul>");
                        rendered = true;
                    }

                    text.Append("<li><a href=\"");
                    text.Append(link.LinkTarget.OriginalString);
                    text.Append("\">");
                    text.Append(
                        StringSegment.IsNullOrEmpty(link.Title)
                        ? link.LinkTarget.OriginalString
                        : link.Title.ToString());
                    text.Append("</a></li>");
                }

                if (rendered)
                {
                    text.Append("</ul>");
                }
            }
        }

        return text.ToString();
    }

    public static OpenApiOptions ApplySecuritySchemeDefinitions(this OpenApiOptions options)
    {
        options.AddDocumentTransformer<SecuritySchemeDefinitionsTransformer>();
        return options;
    }

    public static OpenApiOptions ApplyAuthorizationChecks(this OpenApiOptions options, string[] scopes)
    {
        options.AddOperationTransformer((operation, context, cancellationToken) =>
        {
            var metadata = context.Description.ActionDescriptor.EndpointMetadata;

            if (!metadata.OfType<IAuthorizeData>().Any())
            {
                return Task.CompletedTask;
            }

            operation.Responses.TryAdd("401", new OpenApiResponse { Description = "Unauthorized" });
            operation.Responses.TryAdd("403", new OpenApiResponse { Description = "Forbidden" });

            var oAuthScheme = new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
            };

            operation.Security = new List<OpenApiSecurityRequirement>
            {
                new()
                {
                    [oAuthScheme] = scopes
                }
            };

            return Task.CompletedTask;
        });
        return options;
    }

    public static OpenApiOptions ApplyOperationDeprecatedStatus(this OpenApiOptions options)
    {
        options.AddOperationTransformer((operation, context, cancellationToken) =>
        {
            var apiDescription = context.Description;
            operation.Deprecated |= apiDescription.IsDeprecated();
            return Task.CompletedTask;
        });
        return options;
    }

    public static OpenApiOptions ApplyApiVersionDescription(this OpenApiOptions options)
    {
        options.AddOperationTransformer((operation, context, cancellationToken) =>
        {
            // Find parameter named "api-version" and add a description to it
            var apiVersionParameter = operation.Parameters.FirstOrDefault(p => p.Name == "api-version");
            if (apiVersionParameter is not null) {
                apiVersionParameter.Description = "The API version, in the format 'major.minor'.";
                var versionNumber = context.DocumentName.TrimStart('v');
                if (int.TryParse(versionNumber, out var version)) {
                    apiVersionParameter.Schema.Example = new OpenApiString($"{version}.0");
                } else {
                    throw new ArgumentException("got invalid document name {context.DocumentName}. Expected format v#");
                }
            }
            return Task.CompletedTask;
        });
        return options;
    }

    // This extension method adds a schema transformer that sets "nullable" to false for all optional properties.
    public static OpenApiOptions ApplySchemaNullableFalse(this OpenApiOptions options)
    {
        options.AddSchemaTransformer((schema, context, cancellationToken) =>
        {
            if (schema.Properties is not null)
            {
                foreach (var property in schema.Properties)
                {
                    if (schema.Required?.Contains(property.Key) != true)
                    {
                        property.Value.Nullable = false;
                    }
                }
            }

            return Task.CompletedTask;
        });
        return options;
    }

#pragma warning disable 9113
    private class SecuritySchemeDefinitionsTransformer(IConfiguration configuration) : IOpenApiDocumentTransformer {
#pragma warning restore 9113
        public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken) {
            document.Components ??= new();
            document.Components.SecuritySchemes.Add("Bearer", new OpenApiSecurityScheme {
                In = ParameterLocation.Header,
                Description = "Please enter a valid token",
                Name = "Authorization",
                Type = SecuritySchemeType.Http,
                BearerFormat = "JWT",
                Scheme = "Bearer"
            });
            return Task.CompletedTask;
        }
    }
}

Program.cs

    var apiVersioning = builder.Services.AddApiVersioning(options => {
                options.DefaultApiVersion = new ApiVersion(1, 0);
                options.AssumeDefaultVersionWhenUnspecified = true;
                options.ApiVersionReader = new HeaderApiVersionReader("x-ms-version");
                options.ReportApiVersions = true;
                options.UnsupportedApiVersionStatusCode = 501;
            });
    builder.AddDefaultOpenApi(apiVersioning);
    builder.Services.AddSingleton<IAuthorizationMiddlewareResultHandler, Show404AuthorizationMiddlewareResultHandler>();
    builder.Services.AddAuthorizationBuilder()
                .AddPolicy("ApiDeveloperPolicy", policy => policy.RequireRole(["developer"])
                .AddRequirements(new ProtectedEndpoint404()));
    // after app.MapControllers().WithStaticAssets();
    app.UseDefaultOpenApi();

ProgramAuxiliary

public class Show404AuthorizationMiddlewareResultHandler : IAuthorizationMiddlewareResultHandler {
    private readonly AuthorizationMiddlewareResultHandler defaultHandler = new();

    public async Task HandleAsync(
        RequestDelegate next,
        HttpContext context,
        AuthorizationPolicy policy,
        PolicyAuthorizationResult authorizeResult) {
        if (!authorizeResult.Succeeded && policy.Requirements.Any(p => p is ProtectedEndpoint404)) {
            // Return a 404 to make it appear as if the resource doesn't exist.
            context.Response.StatusCode = StatusCodes.Status404NotFound;
            return;
        }
        await defaultHandler.HandleAsync(next, context, policy, authorizeResult);
    }
}

public class ProtectedEndpoint404 : IAuthorizationRequirement { }

csproj Partial - Packages

<ItemGroup>
    <PackageReference Include="Asp.Versioning.Http" Version="8.1.0" />
    <PackageReference Include="Asp.Versioning.Http.Client" Version="8.1.0" />
    <PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.1.0" />
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="6.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.1" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="9.0.1" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.1" />
    <PackageReference Include="Microsoft.Azure.AppConfiguration.AspNetCore" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.1">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.1" />
    <PackageReference Include="Microsoft.FeatureManagement.AspNetCore" Version="4.0.0" />
    <PackageReference Include="Microsoft.IdentityModel.Tokens" Version="8.3.1" />
    <PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.21.0" />
    <PackageReference Include="MongoDB.Analyzer" Version="1.5.0" />
    <PackageReference Include="MongoDB.Driver" Version="3.1.0" />
    <PackageReference Include="Postmark" Version="5.2.0" />
    <PackageReference Include="Scalar.AspNetCore" Version="2.0.9" />
    <PackageReference Include="Stripe.net" Version="47.3.0" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="7.2.0" />
    <PackageReference Include="System.IdentityModel.Tokens.Jwt" Version="8.3.1" />
    <PackageReference Include="System.Text.Json" Version="9.0.1" />
  </ItemGroup>

.NET 8 Versioning

Program.cs

Note that by default, ASP.NET will set each route as version 1 unless otherwise defined. Also note that if a client does not specify a version, the version 1 route will be used by default.

builder.Services.AddApiVersioning(options => {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new HeaderApiVersionReader("x-ms-version");
    options.ReportApiVersions = true;
    options.UnsupportedApiVersionStatusCode = 501;
})
// format the version as "'v'major[.minor][-status]"
.AddApiExplorer(options => {
    options.GroupNameFormat = "'v'VVV";
});

ProgramAuxiliary.cs

The following code allows the Swagger UI to work with the versioning.

Some of this code might be unused, this is because in my own ProgramAuxiliary.cs, I also have the code to enable kebab case routes.

// ProgramAuxiliary.cs is a supplementary to the startup code in Program.cs where this file contains some boilerplate to provide abstraction
using Asp.Versioning.ApiExplorer;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.AspNetCore.Mvc.ModelBinding;
using Microsoft.Extensions.Options;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Text.Json;
using System.Text.RegularExpressions;

namespace SttApi;

// all I know is that this is related to making swagger work with different versions of the API
public class ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) : IConfigureOptions<SwaggerGenOptions> {
    readonly IApiVersionDescriptionProvider _provider = provider;
    readonly string _apiName = "Split The Tank";

    public void Configure(SwaggerGenOptions options) {
        foreach (var description in _provider.ApiVersionDescriptions) {
            options.SwaggerDoc(
              description.GroupName,
                new OpenApiInfo() {
                    Title = $"{_apiName} API {description.ApiVersion}",
                    Version = description.ApiVersion.ToString(),
                });
        }
    }
}

// All I know is that this bunch of code is related to making sure the API version is set in the header by default
public class SwaggerDefaultValues : IOperationFilter {
    /// <inheritdoc />
    public void Apply(OpenApiOperation operation, OperationFilterContext context) {
        var apiDescription = context.ApiDescription;

        operation.Deprecated |= apiDescription.IsDeprecated();

        // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1752#issue-663991077
        foreach (var responseType in context.ApiDescription.SupportedResponseTypes) {
            // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/b7cf75e7905050305b115dd96640ddd6e74c7ac9/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs#L383-L387
            var responseKey = responseType.IsDefaultResponse ? "default" : responseType.StatusCode.ToString();
            var response = operation.Responses[responseKey];

            foreach (var contentType in response.Content.Keys) {
                if (!responseType.ApiResponseFormats.Any(x => x.MediaType == contentType)) {
                    response.Content.Remove(contentType);
                }
            }
        }

        if (operation.Parameters == null) return;

        // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/412
        // REF: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/413
        foreach (var parameter in operation.Parameters) {
            var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);

            parameter.Description ??= description.ModelMetadata?.Description;

            if (parameter.Schema.Default == null && description.DefaultValue != null &&
                 description.DefaultValue is not DBNull && description.ModelMetadata is ModelMetadata modelMetadata) {
                // REF: https://github.com/Microsoft/aspnet-api-versioning/issues/429#issuecomment-605402330
                var json = JsonSerializer.Serialize(description.DefaultValue, modelMetadata.ModelType);
                parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson(json);
            }

            parameter.Required |= description.IsRequired;
        }
    }
}

Controller Example

[Route("[controller]/[action]")]
[ApiController]
[Authorize]
// since we are defining a version 2, we want to inform ASP.NET that the other routes are version 1, you can experiment without this at first just to see the result
[ApiVersion(1.0)]
public class PaymentController : ControllerBase {
  // this is Version 1
  [HttpGet]
  public async Task<ActionResult<string>> Invoice(string payee) {
      // implementation omitted
  }

  [HttpGet]
  [ApiVersion(2.0)]
  [ActionName(nameof(Invoice))]
  public async Task<ActionResult<PaymentSheetProps>> InvoiceV2(string payee) {
      // implementation omitted
  }
}

// gate-keep entire API to reduce possibility of unofficial clients
[Route("[controller]/[action]")]
[ApiController]
[Authorize]
public class CarsController : Controller {
    private readonly CarService _carService;

    public CarsController(CarService carService) {
        _carService = carService;
    }
    // this is implicitly Version 1
    [HttpGet]
    public async Task<List<OwnedCar>> Owned() {
        var cars = await _carService.GetOwned(User.FindFirstValue(ClaimTypes.Email)!);
        return cars!;
    }
}

Client Example

In the future, I will provide samples in Kotlin and Swift as well. For now, here’s a JS implementation. Just use an LLM to get code for the language of the client you are writing.

// note that jwtFetch is just a wrapper around fetch that does auto logging out and .json() conversion when applicable
export async function paymentInvoice(jwt, logout, payee) {
  const response = await jwtFetch(`payment/invoice?payee=${payee}`, logout, {
    method: 'GET',
    headers: { ...buildAuthHeader(jwt), 'x-ms-version': '2.0' },
  });
  return response;
}

C# MongoDB Add Item to Dictionary

Sat, 12 Aug 2023 11:12:03 -0400

To add an item to a Dictionary field in a MongoDB collection - say JoinRequests of the Ride collection - treat the dictionary field an array and utilize the $push operator. I do not like the k, v extra outlining, but this is the only way I found that works with dots in the key. If you find an atomic way that can treat the dictionary as a Document and not as an array of documents, please let me know.

Here is an example.

using Microsoft.Extensions.Options;
using MongoDB.Driver;

class Ride {
    // ..
    [BsonDictionaryOptions(DictionaryRepresentation.ArrayOfDocuments)]
    public Dictionary<Email, Passenger> Passengers { get; set; } = new();
/*
{
    "Passengers": [{ "k": Email, "v": Passenger }]
}
*/
}


public async Task<bool> AcceptJoinRequest(string rideId, string driver, string user) {
    var updatePull = Builders<Ride>.Update.Pull(r => r.JoinRequests, user);

    var update = updatePull.Update.Push(r => r.Passengers, new KeyValuePair<string, Passenger>(user, new Passenger()));

    var res = await _ridesCollection.UpdateOneAsync(x => x.Driver == driver && x.Id == rideId && x.JoinRequests.Contains(user), update);
    return res.IsModifiedCountAvailable && res.ModifiedCount > 0;
}

ASP.NET Core Global Json Options

Sun, 23 Jul 2023 15:48:46 -0400

When adding JSON options to an ASP.NET controller, these options do not apply to manual uses of the json serializer. Therefore, if you want to use the same options for other serializing or deserializing, you can use dependency injection.

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

namespace Api.Services;

public Constructor(IOptions<JsonOptions> jsonOptions) {
    var serializerOptions = jsonOptions.Value.JsonSerializerOptions;
}

If you don’t know how to set default Json serializer options for the controller, read ASP.NET Core Optional Json Fields.

I’m not sure why this was a draft, but I made it public again.

ASP.NET Core Add HTML to Web Api

Sat, 15 Jul 2023 12:45:48 -0400

Suppose you wanted to add html to your asp.net web api project, how would you go about it?

Sure you may just write the HTML in the controller, but that’s not good enough if you want to return an actual webpage.

We need to integrate Razor pages to our application. In Program.cs,

builder.Services.AddRazorPages();  // add this
builder.Services.AddHttpContextAccessor();  // add this
var app = builder.Build();

app.MapControllers();
app.MapRazorPages(); // add this, it doesn't matter if it is before or after MapControllers
app.Run();

Suppose we want to serve a page for website.com/about

In your project folder, create Pages/About.cshtml

@page
@inject Microsoft.AspNetCore.Http.IHttpContextAccessor HttpContextAccessor

<!DOCTYPE html>
<style>
    @Html.Raw("@")media only screen and (min-width: 950px) {
        .center {
            width: 30%;
        }
    }
</style>

<a href="@(HttpContextAccessor.HttpContext.Request.Path)@(HttpContextAccessor.HttpContext.Request.QueryString.ToUriComponent())">This pages url</a>
<p>a get request query for field name: @HttpContextAccessor.HttpContext.Request.Query["name"]</p>

How to escape @ in Razor Pages (cshtml)

To escape the @ in Razor pages, use @Html.Raw("@").

ASP.NET Core HTTP Error Responses Best Practice?

Sat, 01 Jul 2023 17:29:24 -0400

How do you return a bad request or an unauthorized response in ASP.NET while also being able to return a strongly typed response? I present to you ActionResult<T>. Here is an example of me using ActionResult to validate the request as well as to check authorization. Since this is an example, is it not for copy-pasting but rather to show you how to use ActionResult<T> in practice.

// one of these is imports may be relevant
using System.Security.Claims;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[HttpPost]
public async Task<ActionResult<string>> New(StartRideRequest startRideRequest) {
    var email = User.FindFirstValue(ClaimTypes.Email);
    if (email == null) return Unauthorized();
    if (!_dataValidationService.validCurrency(startRideRequest.Currency)) {
        HttpContext.Features.Set(new ArgumentException("invalid currency"));
        return BadRequest("invalid currency");
    }
    // ...
    return Ok("id");
}

ASP.NET Core Serve Embedded Resource

Fri, 02 Jun 2023 14:09:28 -0400

You really shouldn’t be serving static files from the server but rather a reverse proxy like NGINX or something like an S3 bucket. However, what if you are just doing some debugging? In that case, here are three examples of reading an embedded resource in different contexts.

The embedded resource that needs to be accessed are SttApi/Assets/SwaggerDark.css and SttApi/Assets/getmakes.json where SttApi is the project name.

First we need to make the resource embedded. You can either do this through the properties panel in Visual Studio or by manually editing the Proj/Proj.csproj like so:

<Project Sdk="Microsoft.NET.Sdk.Web">
    <!-- ... -->
    <ItemGroup>
        <!-- other embedded resources -->
        <EmbeddedResource Include="Assets/getmakes.json" />
        <EmbeddedResource Include="Assets/SwaggerDark.css" />
    </ItemGroup>
    <!-- ... -->
</Project>

At least on Windows, it doesn’t matter if the path separator is \ or /.

Example 1 Program.cs

// Program.cs
using System.Reflection;
// scope skipped for conciseness
            app.MapGet("/css/SwaggerDark.css", () => {
                var assembly = Assembly.GetExecutingAssembly();
                return Results.Stream(assembly.GetManifestResourceStream("SttApi.Assets.SwaggerDark.css")!, "text/css");
            }).ExcludeFromDescription();

Example 2 Controller.cs

// ExampleController.cs
using System.Reflection;
// scope skipped for conciseness
    [HttpGet]
    public IResult EmbeddedResource() {
        var assembly = Assembly.GetExecutingAssembly();
        return Results.Stream(assembly.GetManifestResourceStream("SttApi.Assets.SwaggerDark.css")!, "text/css");
    }

Example 3 Service.cs

// ExampleService.cs
using System.Reflection;
// scope skipped for conciseness
    var assembly = Assembly.GetExecutingAssembly();
    IEnumerable<CarMake> carMakes = JsonSerializer.Deserialize<IEnumerable<CarMake>>(assembly.GetManifestResourceStream("SttApi.Assets.getmakes.json")!)!;

ASP.NET Core Swagger Dark Theme

Fri, 02 Jun 2023 12:49:14 -0400

Note. Starting in .NET 9, ASP.NET ships OpenAPI and thus I suggest using Scalar instead which comes with a built-in dark theme. I will add a Scalar tutorial for WebAPI / Authentication.

For the SEO: How to add dark theme to Swagger UI ASP.NET? Follow these instructions.

If you have guidelines for other frameworks, feel free to email me your code so I can add it to the README.md

There’s two ways to accomplish this. One is to use serve static files and the other is to only serve the static file (through embedded resource). I’ll give instructions just in case.

Serving From Static Folder

Create ProjectName/wwwroot/css/SwaggerDark.json in your project. You need to create these folders if they do not exist. If you have guidelines for other frameworks, feel free to email me your code so I can add it to the README.md

In Program.cs:

app.UseStaticFiles();  // ADD THIS LINE
if (app.Environment.IsDevelopment()) {
            app.UseHttpLogging();
            app.UseSwagger();
            app.UseSwaggerUI(c => {
                c.EnableTryItOutByDefault();
                c.InjectStylesheet("/css/SwaggerDark.css");  // ADD THIS LINE
            });
        }

Serving From an Embedded Resource

I don’t really recommend this route anymore, as it adds complexity for serving static files.

Create ProjectName/Assets/SwaggerDark.json in your project. You need to create the asset folder if it does not exist.

In Program.cs:

using System.Reflection;

if (app.Environment.IsDevelopment()) {
            app.UseHttpLogging();
            app.UseSwagger();
            app.UseSwaggerUI(c => {
                c.EnableTryItOutByDefault();
                c.InjectStylesheet("/css/SwaggerDark.css");  // ADD THIS LINE
            });
            // add this:
            app.MapGet("/css/SwaggerDark.css", () => {
                var assembly = Assembly.GetExecutingAssembly();
                // SttApi to ProjectName
                return Results.Stream(assembly.GetManifestResourceStream("SttApi.Assets.SwaggerDark.css")!, "text/css");
            }).ExcludeFromDescription();
        }

In ProjectName/ProjectName.csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">
    <!-- ... -->
    <ItemGroup>
        <!-- other embedded resources -->
        <EmbeddedResource Include="Assets/SwaggerDark.css" />
    </ItemGroup>
    <!-- ... -->
</Project>

You may need to hard restart your app for the changes to take effect.

ASP.NET Core Name Routes After Methods

Sun, 28 May 2023 18:10:09 -0400

Suppose you want to avoid using decorators for every public method you write and you just want the route to following the same convention as your methods in your controller. Adapt the following for your own use. The Route decorator indicates that the route for the following will be auth/request-token if your API is using the kebab-case route configuration. If you aren’t using kebab-case routing, then the expected route below would be something like Auth/RequestToken.

NOTE: If you are writing a backend that serves a frontend (HTML or a webapp), then I suggest using an “api” prefix like so: [Route("api/[controller]/[action]")].

[ApiController]
[Route("[controller]/[action]")]
public class AuthController : ControllerBase {
    // CODE
    [HttpGet]
    public async Task<RequestTokenResponse> RequestToken(string email) {
        // CODE
    }
}

ASP.NET Core JWT Authorization

Wed, 03 May 2023 13:14:55 -0400

Don’t feel like explaining my code, so just copy and modify it for yourself as I can assure you it’s one of the cleanest you can find.

I removed my login handling code since you can do that yourself. My login code was send login code to email via postmark and verify it. I was also using a MongoDB database.

The project is called “SttApi” so replace that with your own project name.

appsettings.json

{
    ...
    "Jwt": {
        "Key": "Generate a key using Python secrets.token_hex(64) or similar",
        "Issuer": "https://localhost:44355/",           // url of the project, am using development settings
        "Audience": "https://localhost:44355/"
    }
}

Program.cs

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using Microsoft.OpenApi.Models;

//  ---------------- OTHER CODE ----------------

public static void Main(string[] args) {
        var builder = WebApplication.CreateBuilder(args);

        //  ---------------- OTHER CODE ----------------

        // Swagger UI Authorization
        builder.Services.AddSwaggerGen(option => {
            option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme {
                In = ParameterLocation.Header,
                Description = "Please enter a valid token",
                Name = "Authorization",
                Type = SecuritySchemeType.Http,
                BearerFormat = "JWT",
                Scheme = "Bearer"
            });
            option.AddSecurityRequirement(new OpenApiSecurityRequirement{{
                        new OpenApiSecurityScheme { Reference = new OpenApiReference {
                                Type=ReferenceType.SecurityScheme,
                                Id="Bearer"
                            }},
                        Array.Empty<string>()
                    }
                });
        });

        //JWT Authentication
        builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(options => {
            options.TokenValidationParameters = new TokenValidationParameters {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = builder.Configuration["Jwt:Issuer"],
                ValidAudience = builder.Configuration["Jwt:Audience"],
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
            };
        });
    //  ---------------- OTHER CODE ----------------
    var app = builder.Build();
    //  ---------------- OTHER CODE ----------------
}
//  ---------------- OTHER CODE ----------------

AuthController.cs

// Controllers/AuthController.cs
using System.IdentityModel.Tokens.Jwt;
using System.Linq;
using System.Security.Claims;
using System.Text;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.IdentityModel.Tokens;
using SttApi.Models;
using SttApi.Services;

// Controller for handling user signup and login with code sent to email
// https://learn.microsoft.com/aspnet/core/tutorials/first-mongo-app?WT.mc_id=dotnet-35129-website&view=aspnetcore-7.0&tabs=visual-studio
// https://learn.microsoft.com/aspnet/core/tutorials/first-web-api?view=aspnetcore-7.0&tabs=visual-studio

namespace SttApi.Controllers;

[ApiController]
[Route("[controller]/[action]")]
public class AuthController : ControllerBase {
    private readonly SigningCredentials credentials;
    private readonly string jwtIssuer;
    private readonly string jwtAudience;
    private readonly JwtSecurityTokenHandler jwtSecurityTokenHandler;

    public AuthController(IConfiguration config) {
        jwtIssuer = config["Jwt:Issuer"];
        jwtAudience = config["Jwt:Audience"];
        jwtSecurityTokenHandler = new JwtSecurityTokenHandler();
        var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(config["Jwt:Key"]));
        credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
    }

    [HttpPost]
    public string Login() {
        // LOGIN VERIFICATION CODE GOES HERE
        //  in general you will have to add a RequestBody parameter (just a Class)
        //  and you will need to make the return type another class
        // you will also most likely need to return Task<ResponseType> because of await/async usages
        //  and JsonWebToken will be just a field of that type
        return GenerateToken("email");
    }

#if DEBUG
    [HttpGet]
    [Authorize(Roles = "User")]
    public string TestAuthorization() {
        var email = User.FindFirstValue(ClaimTypes.Email);
        return $"Your email is {email}";
    }
#endif

    private string GenerateToken(string email) {
        var claims = new[] { new Claim(ClaimTypes.Email, email), new Claim(ClaimTypes.Role, "User") };
        var token = new JwtSecurityToken(jwtIssuer, jwtAudience, claims, signingCredentials: credentials);
        // client needs to save JWT as well incldue it in the Authorization Bearer Token header of subsequent requests
        return jwtSecurityTokenHandler.WriteToken(token);
    }
}

DO NOT USE JwtRegisteredClaimNames AS YOU WILL SPEND OVER AN HOUR DEBUGGING ISSUES!!

Gate-keeping Routes and Reading User Claims

I’m making this separate because it’s a common issue and the following way is the best way to get a claim. You can use [Authorize(Roles = "...")] in order to gate keep a single route or all routes of a controller (put the macro before the controller in the latter case).

This is a method I have in my auth controller for faster debugging since I’m doing backend and frontend for a new project.

#if DEBUG
    [HttpGet]
    [Authorize(Roles = "User")]
    public string TestAuthorization() {
        // JwtRegisteredClaimNames
        var email = User.FindFirstValue(ClaimTypes.Email);
        return $"Your email is {email}";
    }
#endif

Uno Platform Logging

Fri, 17 Feb 2023 21:59:46 -0500

Note that you will need to run with debugging (F5) for some logging and breakpoints/tracepoints to work.

If you want to log regardless of debugging, then using the info function may work for you better.

Tracepoints

First, if you simply need to debug something, try using Visual Studio Tracepoints which is nothing but a breakpoint as shown below (use curly braces to print variables). Click the the light grey part on the extreme left, add an action, and voila.

Logging

In your Page.xaml.cs, add the differences

using Uno.Extensions;
using Uno.Logging;

public sealed partial class YourPage : Page {

    private static ILogger _logger { get; } = typeof(YourPage).Log();

    private void ButtonClick(object sender, RoutedEventArgs e) {

        _logger.LogTrace("wont show up, cause we set the LogLevel to be Debug in the next step");
        _logger.Debug("asd");
        _logger.Error("qwe", new Exception("zxc"));
    }
}

In App.xaml.cs and AppHead.xaml.cs, in InitializeLogging above the default filters, modify the first line of code below. I have provided this code in context and it works regardless of where the page is located in your project. For example, the page this blog post is based on is located in a Views directory.

// Custom filters
builder.AddFilter("YourProject.YourPage", LogLevel.Debug);
// Default filters for Uno Platform namespaces [THIS IS ALREADY IN THE FILE]
builder.AddFilter("Uno", LogLevel.Warning);
builder.AddFilter("Windows", LogLevel.Warning);
builder.AddFilter("Microsoft", LogLevel.Warning);

This blog post is adapted from this GitHub discussion

ASP.NET Core Hyphen Separated (Kebab) Routes

Sun, 29 Jan 2023 14:37:16 -0500

See docs for the latest way to do it. Here is how you would do it for ASP.NET Core 7.0:

// Program.cs
// EXISTING IMPORTS
using System.Text.RegularExpressions;

namespace YourApi;

public class Program {
    public static void Main(string[] args) {
        // replace builder.Services.AddControllers() with the following
        builder.Services.AddControllersWithViews(options => {
            options.Conventions.Add(new RouteTokenTransformerConvention(new SlugifyParameterTransformer()));
        });
        // EXISTING CODE
    }
}

// https://learn.microsoft.com/aspnet/core/mvc/controllers/routing#use-a-parameter-transformer-to-customize-token-replacement
public class SlugifyParameterTransformer : IOutboundParameterTransformer {
    public string? TransformOutbound(object? value) {
        if (value == null) { return null; }

        return Regex.Replace(value.ToString(),
                                "([a-z])([A-Z])",
                                "$1-$2",
                                RegexOptions.CultureInvariant,
                                TimeSpan.FromMilliseconds(100)).ToLowerInvariant();
    }

}

ASP.NET Core Serialize Enum as String

Sun, 29 Jan 2023 14:05:19 -0500

ASP.NET Backend

builder.Services.AddControllersWithViews(options => {
            options.Conventions.Add(new RouteTokenTransformerConvention(
                                         new SlugifyParameterTransformer()));

        }).AddJsonOptions(options => {
            options.JsonSerializerOptions.NumberHandling = JsonNumberHandling.AllowReadingFromString;
            options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;               // JSON response is in  camelCase
            options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;  // null not serialized
            options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());                        // enums to string
        });

Client Side

internal class Api {
    // Insert variables below here
    protected static HttpClient _client;
    protected static string BASE_URL = "http://10.0.2.2:5284/";
    // protected static string BASE_URL = "https://api.domain.com/";
    private static readonly ILogger _logger = typeof(Api).Log();
    private static JsonSerializerOptions _serializerOptions;

    static Api() {
        _client = new HttpClient();
        _serializerOptions = new() {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
        };
        _serializerOptions.Converters.Add(new JsonStringEnumConverter());
    }

    public string serializePayload<T>(T value) {
        return JsonSerializer.Serialize(value, _serializerOptions);
    }

    public T deserializePayload<T>(string payload) {
        return JsonSerializer.Deserialize<T>(payload, _serializerOptions);
    }
}

Generalized

using System.Text.Json.Serialization;

namespace MyApi.Models;

public enum LoginErrors {
    InvalidEmail,
    TooManyRequests,
}

public class StartLoginResponse {
    // this right here:
    [JsonConverter(typeof(JsonStringEnumConverter))]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public LoginErrors? Error { get; set; }
}

ASP.NET Core Optional Json Fields

Sun, 29 Jan 2023 14:03:20 -0500

Also featured in this article is enum to string converter.

ASP.NET Backend

builder.Services.AddControllersWithViews(options => {
            options.Conventions.Add(new RouteTokenTransformerConvention(
                                         new SlugifyParameterTransformer()));

        }).AddJsonOptions(options => {
            options.JsonSerializerOptions.NumberHandling = JsonNumberHandling.AllowReadingFromString;
            options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;               // JSON response is in  camelCase
            options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;  // null not serialized
            options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());                        // enums to string
            //  options.JsonSerializerOptions.IncludeFields = true;  // if you want to [de]serialize fields (i.e. get or set are omitted in the class)
        });

Client Side

internal class Api {
    // Insert variables below here
    protected static HttpClient _client;
    protected static string BASE_URL = "http://10.0.2.2:5284/";
    // protected static string BASE_URL = "https://api.domain.com/";
    private static readonly ILogger _logger = typeof(Api).Log();
    private static JsonSerializerOptions _serializerOptions;

    static Api() {
        _client = new HttpClient();
        _serializerOptions = new() {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
        };
        _serializerOptions.Converters.Add(new JsonStringEnumConverter());
    }

    public string serializePayload<T>(T value) {
        return JsonSerializer.Serialize(value, _serializerOptions);
    }

    public T deserializePayload<T>(string payload) {
        return JsonSerializer.Deserialize<T>(payload, _serializerOptions);
    }
}

Generalized

Fields

Field	Description
Always	Property is always ignored
Never	Property is always serialized and deserialized, regardless of IgnoreNullValues configuration
WhenWritingDefault	Property is ignored only if it equals the default value for its type
WhenWritingNull	Property is ignored if its value is null. This is applied only to reference-type properties and fields

For readers in a decade or so, see JsonIgnoreCondition

using System.Text.Json.Serialization;

namespace MyApi.Models;

public enum LoginErrors {
    InvalidEmail,
    TooManyRequests,
}

public class StartLoginResponse {
    [JsonConverter(typeof(JsonStringEnumConverter))]
    // this right here:
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    public LoginErrors? Error { get; set; }
}

ASP.NET WEB API launch.json for Visual Studio Code

Sun, 29 Jan 2023 13:03:33 -0500

Suppose you want to be able to work on your ASP.NET application in Visual Studio as well as Visual Studio Code. Sure you can use the run feature of the Solution Explorer extension in Visual Studio Code, but that’s not a native feeling.

Create the following file:

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            // Use IntelliSense to find out which attributes exist for C# debugging
            // Use hover for the description of the existing attributes
            // For further information visit https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "dotnet",
            // alternative program: if you have changed target frameworks, make sure to update the program path.
            // "program": "${workspaceFolder}/SttApi/bin/Debug/net7.0/SttApi.dll",
            "args": ["watch"],
            "cwd": "${workspaceFolder}/SttApi",
            "stopAtEntry": false,
            "console": "integratedTerminal",
            // Enable launching a web browser when ASP.NET Core starts. For more information: https://aka.ms/VSCode-CS-LaunchJson-WebBrowser
            "serverReadyAction": {
                "action": "openExternally",
                "pattern": "\\bNow listening on:\\s+(https?://\\S+)",
                "uriFormat": "%s/swagger"
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "http://localhost:5284",
                // restart instead of prompt if a non-hot reloadable edit was made
                "DOTNET_WATCH_RESTART_ON_RUDE_EDIT": "true"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach"
        }
    ]
}

Press F5 and enjoy.

Automate Unity Building

Sun, 21 Jun 2020 11:11:24 -0500

It took me hours to figure out how to create a simple build script in Unity, even after watching videos, I was really confused. So why not write an article so that other developers won’t need to spend that much time themselves.

Getting Started

Before we get started make sure you have the necessary build supports needed. In Unity Hub you can see your installations.

If not, you’ll have to click the three dots, and then click “Add Modules.” Next, we will need to create a script named something like BuildScript.cs. Make sure this file is placed in Assets/Editor. This file will be responsible in calling Unity BuildPlayer as well as adding menu items for you to quickly build for your platform(s) of choice.

BuildScript.cs

Next copy the code below. Disclaimer: this code uses the scenes from your build settings so make sure the scenes there are correct. You can ignore the last function if you want, I just kept it there in case you need to use Asset Bundles (I did not). With this script you can call the build methods from “File > Build All” and Unity will build the players to the “Builds” directory in your project root.

This takes care of building from the editor but what if you were using CI/server to build it for you? You will need to make a shell/batch script or you can use Python so that the OS won’t matter.

UnityBuild.py

You may have to modify some variables such as UNITY and also the zipping process if you don’t want to zip the builds. You may also pair this up with an Ino setup script like so iscc setup_script.iss. I hope you found this tutorial helpful because I sure would’ve.

Resources

Build Player Pipeline

Unity Command line arguments