Mastering URL‑Safe Encoding with .NET 9’s Base64Url Class: Examples & Best Practices

With .NET 9 Microsoft has introduced a dedicated Base64Url class to streamline URL‑safe Base64 encoding and decoding. In this post, you’ll learn: Why URL‑safe Base64 matters How to use the new Base64Url API in .NET 9 Real‑world use cases (tokens, query strings, data embedding) Best practices to avoid common pitfalls Let’s dive in! Table of Contents Introduction Why URL‑Safe Base64? The .NET 9 Base64Url Class Code Examples Encoding & Decoding Strings Working with Binary Data Integrating with ASP.NET Core Common Use Cases Best Practices Conclusion Introduction Base64 is a popular encoding mechanism for binary-to-text transformations. However, standard Base64 uses characters like +, /, and = which can break URLs or require extra escaping. URL‑safe Base64 replaces these with -, _, and omits padding, making it ideal for tokens, query parameters, and other web contexts. .NET 9’s new Base64Url class provides: Simple, zero‑allocation methods Consistent behavior across platforms Built‑in handling of padding and illegal characters Why URL‑Safe Base64? Standard Base64: Uses + and / in its alphabet Adds = padding at the end Requires URL‑encoding when used in query strings Can introduce parsing errors or double‑encoding URL‑safe Base64: Substitutes + → - and / → _ Omits or gracefully handles padding Safe to embed in URLs without extra encoding The .NET 9 Base64Url Class The new class lives in the System namespace: namespace System { public static class Base64Url { public static string Encode(byte[] data); public static byte[] Decode(string urlSafeBase64); } } Key points: Encode(byte[]) produces a URL‑safe string (no +, /, or trailing =). Decode(string) accepts padded or unpadded URL‑safe Base64 strings. Code Examples Encoding & Decoding Strings using System; using System.Text; class Program { static void Main() { string original = "Hello, .NET 9!"; byte[] bytes = Encoding.UTF8.GetBytes(original); // Encode to URL-safe Base64 string encoded = Base64Url.Encode(bytes); Console.WriteLine($"Encoded: {encoded}"); // e.g. "SGVsbG8sIC5ORGVDOSA" // Decode back to bytes byte[] decodedBytes = Base64Url.Decode(encoded); string decoded = Encoding.UTF8.GetString(decodedBytes); Console.WriteLine($"Decoded: {decoded}"); // "Hello, .NET 9!" } } Working with Binary Data using System; using System.Security.Cryptography; class BinaryExample { static void Main() { // Generate a random 32-byte key byte[] key = RandomNumberGenerator.GetBytes(32); // URL-safe encode the key string keyToken = Base64Url.Encode(key); Console.WriteLine($"Key Token: {keyToken}"); // Later: decode back to raw key byte[] rawKey = Base64Url.Decode(keyToken); Console.WriteLine($"Key Length: {rawKey.Length} bytes"); } } Integrating with ASP.NET Core Embed URL‑safe tokens in query strings or headers: app.MapGet("/token", () => { var payload = Encoding.UTF8.GetBytes("user-id=42;exp=1699999999"); var token = Base64Url.Encode(payload); return Results.Ok(new { token }); }); app.MapGet("/validate", (string token) => { try { var data = Base64Url.Decode(token); string text = Encoding.UTF8.GetString(data); return Results.Ok(new { valid = true, text }); } catch (FormatException) { return Results.BadRequest("Invalid token format."); } }); Common Use Cases JWT & OIDC – JSON Web Tokens use URL‑safe Base64 for header and payload segments. Query Parameters – Pass binary data or state tokens without further URL encoding. Short-Lived URLs – Sign URLs for temporary access (e.g., presigned file downloads). Embedded Metadata – Include user data in links or forms safely. Best Practices Validate Input: Always wrap Decode in try/catch to handle malformed input. Avoid Manual Padding: Let Base64Url handle padding rules automatically. Use in HTTPS: Although URL‑safe, still transmit sensitive tokens over secure channels. Log & Monitor: Track decode failures to detect tampering or abuse. Cache Heavy Operations: If encoding large blobs frequently, consider caching results. Conclusion .NET 9’s Base64Url class simplifies URL‑safe encoding and decoding with a clean, reliable API. Whether you’re building authentication tokens, passing data in query strings, or signing URLs, Base64Url should be your go‑to tool. Give it a try in your next .NET 9 project, and let me know how you use it! Happy coding!

Apr 23, 2025 - 01:41

Mastering URL‑Safe Encoding with .NET 9’s Base64Url Class: Examples & Best Practices

With .NET 9 Microsoft has introduced a dedicated Base64Url class to streamline URL‑safe Base64 encoding and decoding. In this post, you’ll learn:

Why URL‑safe Base64 matters
How to use the new Base64Url API in .NET 9
Real‑world use cases (tokens, query strings, data embedding)
Best practices to avoid common pitfalls

Let’s dive in!

Introduction
Why URL‑Safe Base64?
The .NET 9 Base64Url Class
Code Examples
- Encoding & Decoding Strings
- Working with Binary Data
- Integrating with ASP.NET Core
Common Use Cases
Best Practices
Conclusion

Introduction

Base64 is a popular encoding mechanism for binary-to-text transformations. However, standard Base64 uses characters like +, /, and = which can break URLs or require extra escaping. URL‑safe Base64 replaces these with -, _, and omits padding, making it ideal for tokens, query parameters, and other web contexts.

.NET 9’s new Base64Url class provides:

Simple, zero‑allocation methods
Consistent behavior across platforms
Built‑in handling of padding and illegal characters

Why URL‑Safe Base64?

Standard Base64:

Uses + and / in its alphabet
Adds = padding at the end
Requires URL‑encoding when used in query strings
Can introduce parsing errors or double‑encoding

URL‑safe Base64:

Substitutes + → - and / → _
Omits or gracefully handles padding
Safe to embed in URLs without extra encoding

The .NET 9 Base64Url Class

The new class lives in the System namespace:

namespace System
{
    public static class Base64Url
    {
        public static string Encode(byte[] data);
        public static byte[] Decode(string urlSafeBase64);
    }
}

Key points:

Encode(byte[]) produces a URL‑safe string (no +, /, or trailing =).
Decode(string) accepts padded or unpadded URL‑safe Base64 strings.

Code Examples

Encoding & Decoding Strings

using System;
using System.Text;

class Program
{
    static void Main()
    {
        string original = "Hello, .NET 9!";
        byte[] bytes = Encoding.UTF8.GetBytes(original);

        // Encode to URL-safe Base64
        string encoded = Base64Url.Encode(bytes);
        Console.WriteLine($"Encoded: {encoded}");
        // e.g. "SGVsbG8sIC5ORGVDOSA"

        // Decode back to bytes
        byte[] decodedBytes = Base64Url.Decode(encoded);
        string decoded = Encoding.UTF8.GetString(decodedBytes);

        Console.WriteLine($"Decoded: {decoded}");
        // "Hello, .NET 9!"
    }
}

Working with Binary Data

using System;
using System.Security.Cryptography;

class BinaryExample
{
    static void Main()
    {
        // Generate a random 32-byte key
        byte[] key = RandomNumberGenerator.GetBytes(32);

        // URL-safe encode the key
        string keyToken = Base64Url.Encode(key);
        Console.WriteLine($"Key Token: {keyToken}");

        // Later: decode back to raw key
        byte[] rawKey = Base64Url.Decode(keyToken);
        Console.WriteLine($"Key Length: {rawKey.Length} bytes");
    }
}

Integrating with ASP.NET Core

Embed URL‑safe tokens in query strings or headers:

app.MapGet("/token", () =>
{
    var payload = Encoding.UTF8.GetBytes("user-id=42;exp=1699999999");
    var token = Base64Url.Encode(payload);
    return Results.Ok(new { token });
});

app.MapGet("/validate", (string token) =>
{
    try
    {
        var data = Base64Url.Decode(token);
        string text = Encoding.UTF8.GetString(data);
        return Results.Ok(new { valid = true, text });
    }
    catch (FormatException)
    {
        return Results.BadRequest("Invalid token format.");
    }
});

Common Use Cases

JWT & OIDC – JSON Web Tokens use URL‑safe Base64 for header and payload segments.
Query Parameters – Pass binary data or state tokens without further URL encoding.
Short-Lived URLs – Sign URLs for temporary access (e.g., presigned file downloads).
Embedded Metadata – Include user data in links or forms safely.

Best Practices

Validate Input: Always wrap Decode in try/catch to handle malformed input.
Avoid Manual Padding: Let Base64Url handle padding rules automatically.
Use in HTTPS: Although URL‑safe, still transmit sensitive tokens over secure channels.
Log & Monitor: Track decode failures to detect tampering or abuse.
Cache Heavy Operations: If encoding large blobs frequently, consider caching results.

Conclusion

.NET 9’s Base64Url class simplifies URL‑safe encoding and decoding with a clean, reliable API. Whether you’re building authentication tokens, passing data in query strings, or signing URLs, Base64Url should be your go‑to tool.

Give it a try in your next .NET 9 project, and let me know how you use it!

Happy coding!