What follows is a walk through one set of solutions: a Tokio runtime owned by the .NET process, an FFI callback bridge that completes a Task on the C# side, and a lock-free state machine that keeps cancellation safe across the boundary. The running example is DataFusionSharp, a .NET binding for Apache DataFusion — DataFusion is async to its core (every query, file scan, and object-store request returns a Future), and the binding’s whole job is to expose that as idiomatic Task<T>-returning C# methods. Tokio sits on one end, the .NET task scheduler on the other, with no shared notion of “completion” between them.

Async in Rust and C#

Both Rust and C# settled on the same fundamental design: async functions compile to state machines that drive an external object (Future in Rust, Task in C#). The state machine yields control whenever it would block, and resumes when an “awaitable” completes. The vocabulary differs but the mechanics are basically the same.

In Rust, async fn foo() is sugar that the compiler rewrites into a function returning impl Future<Output = T>. A Future is a trait with a single method: poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T>. Polling either returns Ready(value) or Pending, and on Pending the future has registered a Waker somewhere so it can be polled again later. Crucially, nothing polls a Future until you hand it to an executor. The most popular executor is Tokio, a multi-threaded scheduler that owns a thread pool, drives futures to completion, and provides timers and an I/O reactor.

In C#, async Task<T> is also sugar — the compiler rewrites the body into a state machine implementing IAsyncStateMachine, with MoveNext() standing in for Rust’s poll (almost, C# is push-based while Rust is pull-based). The difference is that the state machine is wired up automatically: continuations land on the .NET thread pool by default, awaiters are part of the BCL, and there is no executor to choose. You just call an async method and await what it returns.

Both compilers are doing the similar transformation, but the resulting state machine has to be driven by something, and Rust and C# don’t share an executor, a poll loop, or a notion of completion. A Rust Future can’t be awaited from C# directly, and shipping Tokio’s runtime into .NET as a managed scheduler is not on the table either. So something has to bridge the two sides.

The Bridge: Callbacks at the FFI Boundary

The lowest common denominator both sides understand is a C-style callback. The pattern looks like this:

1. C# calls a native function and that function returns immediately.
2. Native code spawns a Tokio task that does the actual async work.
3. When the task finishes, it invokes a callback function pointer the C# side passed in.
4. The callback unblocks a TaskCompletionSource on the C# side, which completes the Task the original caller is awaiting.

The native function returns synchronously and immediately — it’s just a “start this work” message. Everything else happens through the callback.

Here’s the possible callback signature on the Rust side:

pub type Callback = unsafe extern "C" fn(
    result: *const std::ffi::c_void,
    error: *const ErrorInfoData,
    user_data: isize,
);

Three pieces:

• result — pointer to whatever the operation produced, or null on error.
• error — pointer to error info, or null on success.
• user_data — an opaque isize the caller passed in. Native code never looks at it, it’s just round-tripped back to C#. This is how we identify which operation just completed, and the callback later turns it back into a managed object — the section on GCHandle below covers that part.

Wire Format and Lifetimes

Two #[repr(C)] structs do all the heavy lifting for data crossing the boundary:

#[repr(C)]
pub struct BytesData {
    data: *const u8,
    len: u32,
}

#[repr(C)]
pub struct ErrorInfoData {
    pub code: ErrorCode,
    pub message: BytesData,
}

#[repr(C)] makes the layout byte-identical to C# structs declared with [StructLayout(LayoutKind.Sequential)], which means they pass through P/Invoke with zero marshalling — the bytes on the stack on one side are the bytes on the stack on the other.

BytesData is a pointer-and-length pair. It carries arguments going into native code (Protobuf-encoded options, query parameters, raw bytes), and it carries bulk results coming back through the callback’s result slot. ErrorInfoData packages a numeric error code with a message in the same shape; the callback’s error slot is a pointer to one of these when an operation failed.

The general rule for FFI lifetimes here:

• Inputs: pinned on the C# side, consumed by Rust before the call returns or before the spawned task finishes. Either way, Rust never holds onto an input pointer past the immediate operation.
• Outputs: owned by Rust, exposed to C# only during the callback. C# copies what it needs (Marshal.PtrToStructure for whole structs, Marshal.ReadIntPtr for a single pointer, plain copy loops for BytesData payloads), then Rust frees the original as the callback returns.

This is similar to how borrow checking works in pure Rust — the pointer’s “lifetime” is the duration of the call. The only twist is that the borrow checker can’t see across the FFI boundary, so the convention is enforced by hand on both sides.

Owning Tokio from C#

DataFusionSharp creates and owns the Tokio runtime explicitly, so the C# side has full control over its lifetime.

pub type RuntimeHandle = Arc<tokio::runtime::Runtime>;

#[unsafe(no_mangle)]
pub unsafe extern "C" fn datafusion_runtime_new(
    runtime_ptr: *mut *mut RuntimeHandle,
) -> ErrorCode {
    let mut builder = tokio::runtime::Builder::new_multi_thread();

    builder.enable_all();

    match builder.build() {
        Ok(runtime) => {
            let runtime_handle: RuntimeHandle = Arc::new(runtime);
            unsafe { *runtime_ptr = Box::into_raw(Box::new(runtime_handle)); }
            ErrorCode::Ok
        }
        Err(_) => ErrorCode::RuntimeInitializationFailed,
    }
}

A few things worth pointing out:

• The runtime is wrapped in Arc, then boxed and returned as a raw pointer. The Arc lets multiple objects hold their own reference without complex lifetime management. The raw pointer is what crosses the FFI boundary.
• new_multi_thread().enable_all() gives us a real, multi-threaded Tokio with timers, I/O, and the works. enable_all() is a single call that turns on every optional Tokio feature: the timer wheel, the I/O reactor for sockets and files, and the signal handlers. Without it, tokio::time::sleep would panic at runtime.

On the C# side, we wrap the raw pointer in a SafeHandle so it gets cleaned up even if the C# code forgets to dispose explicitly. SafeHandle makes the handle GC-aware. It also guarantees that the handle is not freed while another thread is in the middle of a P/Invoke that uses it — the runtime ref-counts active calls and only allows ReleaseHandle once the count drops to zero. That eliminates a whole category of use-after-free bugs at the FFI boundary, with no extra code on our part.

The Smallest Async Operation: Ping

Before tackling SQL, file I/O, and cancellation, here is the simplest possible async FFI call: a ping that sleeps for a specified number of milliseconds and then signals completion. It exercises every piece of the Rust-side machinery — runtime, spawn, select, callback. The next section covers the matching C# half.

Rust side:

#[unsafe(no_mangle)]
pub unsafe extern "C" fn datafusion_ping(
    runtime_ptr: *mut RuntimeHandle,
    timeout_millis: u64,
    callback: Callback,
    user_data: isize,
    cancellation_token_out_ptr: *mut *mut CancellationToken,
) -> ErrorCode {
    let runtime = ffi_ref!(runtime_ptr);

    let cancellation_token = CancellationToken::new();
    crate::cancellation::into_raw_ptr(&cancellation_token, cancellation_token_out_ptr);

    runtime.spawn(async move {
        let result = tokio::select! {
            () = tokio::time::sleep(Duration::from_millis(timeout_millis)) => Ok(()),
            () = cancellation_token.cancelled() => Err(crate::cancellation::error()),
        };

        crate::invoke_callback(result, callback, user_data);
    });

    ErrorCode::Ok
}

Four things happen here:

1. A Tokio CancellationToken is created and a pointer to it is written back through the out parameter (more on this in the cancellation section).
2. runtime.spawn(async move { ... }) schedules the actual work on the Tokio thread pool. spawn returns immediately; the closure runs on a worker thread.
3. Inside the spawned task, tokio::select! races two futures: the sleep and the cancellation signal. Whichever finishes first wins; the other is dropped. Dropping a future is how Rust says “stop polling it” — tokio::time::sleep cleans up its timer entry as it’s dropped, so the abandoned branch costs nothing.
4. When done, the C-style callback fires with either the result or an error, passing back the same user_data we received.

The extern "C" function itself returns ErrorCode::Ok synchronously. From C#’s perspective, it just got a “scheduled” acknowledgment — the result will arrive later via the callback.

The C# Side: From Callback to Task

The C# side is more involved. Callers expect a Task they can await, not a callback, so bridging the two takes three pieces.

1. A TaskCompletionSource

TaskCompletionSource gives us a Task whose completion we control imperatively. We hand the Task to the caller, then later call TrySetResult, TrySetException, or TrySetCanceled from inside the callback.

The cross-cutting plumbing — the GCHandle that pins the operation across the FFI call, the CancellationTokenRegistration, and the three-state pointer slot for the native cancellation handle — lives on an abstract base class that the typed leaf types inherit from:

internal abstract class AsyncOperation
{
    private readonly CancellationToken _cancellationToken;
    private CancellationTokenRegistration _cancellationRegistration;
    private GCHandle _handle;
    private IntPtr _cancellationTokenHandle;

    protected AsyncOperation(CancellationToken cancellationToken)
    {
        _cancellationToken = cancellationToken;
    }

    internal IntPtr GetHandle() { /* lazy GCHandle.Alloc, returns a stable IntPtr */ }
    internal void EnsureNativeCall(...) { /* validates result, stores the native cancel pointer,
                                              registers OnCancelled, throws if the call failed */ }
    protected void Cleanup()       { /* free GCHandle, destroy native token, unregister */ }
}

Two leaf types specialise it: AsyncVoidOperation for fire-and-forget completion, and AsyncOperation<TResult> for callbacks that yield a typed value. Each adds a TaskCompletionSource of the matching shape and a Complete(...) method that translates the callback’s result or exception into the right TrySet* call:

internal sealed class AsyncVoidOperation : AsyncOperation
{
    private readonly TaskCompletionSource _taskCompletionSource =
        new(TaskCreationOptions.RunContinuationsAsynchronously);

    internal Task Task => _taskCompletionSource.Task;

    internal void Complete(Exception? exception = null)
    {
        Cleanup();

        switch (exception)
        {
            case null:
                _taskCompletionSource.TrySetResult();
                break;
            case DataFusionException { ErrorCode: DataFusionErrorCode.Canceled }:
                _taskCompletionSource.TrySetCanceled();
                break;
            default:
                _taskCompletionSource.TrySetException(exception);
                break;
        }
    }
}

TaskCreationOptions.RunContinuationsAsynchronously matters here. Without it, calling TrySetResult synchronously dispatches the awaiter’s continuation on whatever thread invoked the callback — which is a Tokio worker thread. Continuations belong on the .NET thread pool, not on Tokio’s; running them inline can starve Tokio workers and even deadlock if the continuation does any blocking I/O of its own. With the flag set, the runtime queues the continuation through ThreadPool.UnsafeQueueUserWorkItem, the Tokio worker returns to its scheduler immediately, and the C# code wakes up on a managed thread. Both sides go back to running their own jobs.

2. A GCHandle as user_data

How does the native callback know which AsyncVoidOperation to complete? Answer is user_data: isize slot. It’s perfect for an opaque managed-object identifier — and GCHandle is exactly that.

internal IntPtr GetHandle()
{
    if (!_handle.IsAllocated)
        _handle = GCHandle.Alloc(this, GCHandleType.Normal);

    return GCHandle.ToIntPtr(_handle);
}

GCHandle.Alloc does two things: it keeps the C# object alive even when nothing managed references it, and it gives us a stable IntPtr we can hand to native code. When the callback fires, it passes that IntPtr back, we call GCHandle.FromIntPtr to recover the original object, and free the handle.

This is the standard way to round-trip a managed object identity through unmanaged code. Without it, the GC could collect the AsyncVoidOperation between the call and the callback, leaving the callback with nothing valid to complete. GCHandleType.Normal keeps the object alive but does not pin its memory — there’s no need to, because we never read its bytes from native code, only its identity.

3. An UnmanagedCallersOnly Callback

The actual callback function needs to be a plain function pointer with the C calling convention.

[UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
internal static void CallbackForVoid(IntPtr _, IntPtr error, IntPtr handle)
{
    var ex = error != IntPtr.Zero
        ? ErrorInfoData.FromIntPtr(error).ToException()
        : null;
    var op = AsyncVoidOperation.FromHandle(handle);
    op?.Complete(ex);
}

[UnmanagedCallersOnly] tells the runtime: this method must be callable directly as a C function pointer. The compiler verifies that all parameter types are blittable and that the body doesn’t take a managed reference to itself. The result is a function pointer you can hand to native code with no marshalling overhead.

FromHandle does the inverse of GetHandle: it converts the IntPtr back to the managed object.

Putting It Together

With those three pieces, the entire managed PingAsync looks like this:

internal Task PingAsync(TimeSpan timeout, CancellationToken cancellationToken = default)
{
    unsafe
    {
        var op = new AsyncVoidOperation(cancellationToken);
        var result = NativeMethods.Ping(
            _handle,
            (ulong) timeout.TotalMilliseconds,
            &GenericCallbacks.CallbackForVoid,
            op.GetHandle(),
            out var cancellationTokenHandle);
        op.EnsureNativeCall(result, cancellationTokenHandle, "Failed to start ping.");

        return op.Task;
    }
}

The &GenericCallbacks.CallbackForVoid syntax produces a real function pointer (this is C# 9’s function-pointer feature, which works with [UnmanagedCallersOnly] methods). We pass the GCHandle as user_data, and we get back a Task the caller can await.

EnsureNativeCall does the post-call bookkeeping that the snippet hides: it stores the cancellation-token pointer the native side returned, registers a callback on the user’s token (_cancellationToken.Register(OnCancelled)) so user-side cancellation flows back into Rust, and throws if the native call returned an error code instead of Ok. Why that bookkeeping is non-trivial becomes clear in the cancellation section below.

That’s the complete request → spawn → callback → Task lifecycle. For an operation returning a value, only one piece changes: a typed AsyncOperation<TResult> wraps a TaskCompletionSource<TResult>, and the matching callback parses the result pointer into a TResult before completing.

Returning a Typed Result: SQL

Once the void case is in place, returning a typed result is mostly mechanical. Here’s what SqlAsync looks like — a query that produces a DataFrame:

public async Task<DataFrame> SqlAsync(string sql, CancellationToken cancellationToken = default)
{
    Task<DataFrameSafeHandle> sqlTask;

    unsafe
    {
        var op = new AsyncOperation<DataFrameSafeHandle>(cancellationToken);
        var result = NativeMethods.ContextSql(
            _handle,
            sql,
            BytesData.Empty,
            &CallbackForSqlAsync,
            op.GetHandle(),
            out var cancellationTokenHandle);
        op.EnsureNativeCall(result, cancellationTokenHandle, "Failed to start executing SQL query.");
        sqlTask = op.Task;
    }

    var dataFrameSafeHandle = await sqlTask.ConfigureAwait(false);
    return new DataFrame(this, dataFrameSafeHandle);
}

[UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
private static void CallbackForSqlAsync(IntPtr result, IntPtr error, IntPtr handle)
{
    var op = AsyncOperation<DataFrameSafeHandle>.FromHandle(handle);

    if (error != IntPtr.Zero)
    {
        op?.Complete(ErrorInfoData.FromIntPtr(error).ToException());
        return;
    }

    var dataFrameHandle = Marshal.ReadIntPtr(result);
    var safe = new DataFrameSafeHandle(dataFrameHandle);

    if (op is null)
        safe.Dispose(); // Nobody's waiting — free the native handle ourselves.
    else
        op.Complete(safe);
}

The Rust side pushes a *mut DataFrameWrapper through result. On the C# side we read the pointer with Marshal.ReadIntPtr, wrap it in a DataFrameSafeHandle, and complete the operation.

The pattern of “callback receives a raw pointer to a result struct, C# wraps it” generalizes to anything: bytes, integers, strings, even FFI Apache Arrow schemas. Each result type gets its own callback function but they all share the same shape.

Cancellation

Now the reverse direction: a C# caller wants to cancel an in-flight operation by triggering its .NET CancellationToken. The cancellation needs to flow back through the FFI boundary into the running Tokio task.

(A naming note before going further: both Rust and .NET happen to call this primitive CancellationToken. To keep them straight, I’ll prefix every mention as either Tokio or .NET below.)

Tokio already has the right primitive in tokio_util::sync::CancellationToken — a token whose cancelled() future resolves when cancel() is called from anywhere. Plug that into tokio::select! (you saw it in the ping function above), and you have an async operation that races real work against an external cancel signal.

The piece that’s missing is letting C# call cancel() on that Tokio token. So we expose two more FFI functions:

#[unsafe(no_mangle)]
pub unsafe extern "C" fn datafusion_cancellation_token_cancel(
    token_ptr: *mut CancellationToken,
) -> ErrorCode {
    if token_ptr.is_null() { return ErrorCode::InvalidArgument; }
    let token = unsafe { Box::from_raw(token_ptr) };
    token.cancel();
    ErrorCode::Ok
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn datafusion_cancellation_token_destroy(
    token_ptr: *mut CancellationToken,
) -> ErrorCode {
    if token_ptr.is_null() { return ErrorCode::InvalidArgument; }
    unsafe { drop(Box::from_raw(token_ptr)) };
    ErrorCode::Ok
}

When a Rust async function starts, it creates a Tokio CancellationToken, clones it (cloning a Tokio token shares the same internal cancellation state — it doesn’t make a separate token), and writes a raw pointer to the clone back through the out parameter. The C# side stores that pointer. If the user’s .NET CancellationToken fires, C# P/Invokes datafusion_cancellation_token_cancel, which cancels the Tokio token, which makes cancellation_token.cancelled() resolve in tokio::select!, which preempts the real future.

If the operation completes normally, C# P/Invokes datafusion_cancellation_token_destroy instead, freeing the Tokio token without firing it.

The C# wiring looks straightforward: register a callback on the user’s .NET token that triggers the native cancel function.

_cancellationRegistration = _cancellationToken.Register(OnCancelled);

private void OnCancelled() => Cancel();

Except it isn’t, because there’s a race, and I had to redo this twice before it stopped flaking in tests.

The Race

Step by step, the ping flow goes:

1. C# calls Ping, passing a callback and a slot for the cancellation-token pointer.
2. Native code creates the cancellation token, writes its pointer to the out parameter, and spawns the Tokio task.
3. The native function returns to C#.
4. C# wires up cancellationToken.Register(OnCancelled) so cancellation will trigger the native Cancel.

The problem: between step 2 and step 4, the Tokio task can start, complete, and fire the callback. If that happens, the callback completes the Task — but the C# side hasn’t yet decided what to do with the cancellation-token pointer. Worse, if the user cancels right after step 4 wires up cancellation, C# might call Cancel on a token that’s already been freed by the completion path.

With a ping(0) call, the spawned future completes essentially synchronously on a Tokio worker, so this race fires in practice. By the time the calling thread gets back to step 4, the callback has already run, the GC handle has been freed, and the cancellation token would be gone if we destroyed it eagerly.

The simplest fix is to take a lock. But this is a hot path; we don’t want a mutex on every async call.

The Three-State Pointer

Instead, the C# AsyncOperation treats the native cancellation-token pointer as a tiny lock-free state machine with three states:

• IntPtr.Zero — no native token registered yet (initial state).
• A real pointer — token is alive, cancellation can fire.
• IntPtr(-1) — operation has finished (completed, errored, or cancelled), token has been or will be destroyed.

The transitions are atomic, using Interlocked.CompareExchange and Interlocked.Exchange:

private bool TryInitializeCancellationTokenHandle(IntPtr handle)
{
    var prev = Interlocked.CompareExchange(
        ref _cancellationTokenHandle,
        handle,
        EmptyCancellationTokenHandle);
    return prev == EmptyCancellationTokenHandle;
}

private IntPtr TakeCancellationTokenHandle()
{
    return Interlocked.Exchange(
        ref _cancellationTokenHandle,
        FinishedCancellationTokenHandle);
}

TryInitialize runs in EnsureNativeCall on the calling thread. Take runs in two places: the cleanup path inside Complete (callback thread), and the cancellation path inside Cancel (whichever thread fires the user’s CancellationToken).

Now the race is well-defined. Two scenarios cover what can happen:

• C# wins (the spawned task hasn’t completed yet): TryInitialize succeeds (CAS from Zero → real handle), and the cancellation registration is wired. Whichever path fires next — completion or cancellation — calls Take to read the live pointer, transitions to Finished, and acts on it.
• Tokio task wins (it completes immediately, runs the callback, which transitions the slot to Finished via cleanup): TryInitialize sees Finished, the CAS fails, and C# destroys the token it had been about to register. Cleanup is a no-op.

In both scenarios, cancellation and completion can never both Take the same live pointer, because Exchange is atomic — exactly one of them sees the real handle; the other sees Finished and walks away.

The takeaway I’d hold onto from this: whenever an FFI handle has both a completion path and a from-the-outside path that can fire at the same time, two states aren’t enough. A third state — “done, hands off” — and an atomic CAS into the pointer slot itself is usually cheaper than reaching for a mutex.

Production Notes

A few practical things worth mentioning:

• [LibraryImport] over [DllImport]. The [LibraryImport] source generator produces marshalling code at compile time, which makes the bindings AOT-compatible.
• [SuppressGCTransition] on cheap, non-blocking native functions like CancellationTokenCancel. Skipping the GC transition shaves a few hundred nanoseconds per call. The trade-off is that the call must not block, allocate, or take any time at all in native code, because the GC is effectively paused for its duration. Cancellation is a simple atomic store on Tokio’s side, so it qualifies.

Wrapping Up

The pattern in five points:

• One Tokio runtime, owned by C# for its full lifetime, holding a raw pointer wrapped in a SafeHandle.
• Every async FFI call accepts a (callback, user_data, cancellation_token_out) triple and returns immediately. Real work runs on the Tokio pool.
• The managed side keeps its operation object alive across the call via GCHandle, completes a TaskCompletionSource from a static [UnmanagedCallersOnly] callback, and frees the handle on the way out.
• Cancellation flows the other way through a Tokio CancellationToken whose pointer is round-tripped through a three-state lock-free machine on the C# side, robust against the obvious “callback fires before C# wires cancellation” race.
• Inputs and outputs cross the FFI boundary as #[repr(C)] structs of pointers and lengths, with strict ownership rules: inputs are pinned by C#, outputs are owned by Rust and live only for the duration of the callback.

The code lives at github.com/nazarii-piontko/datafusion-sharp — the runtime and cancellation pieces are in native/src/runtime.rs, native/src/cancellation.rs, and src/DataFusionSharp/Interop/AsyncOperations.cs if you want to see all the production warts (memory-test instrumentation, finalizers, edge cases) that I trimmed for this post.

That’s a lot of plumbing for what looks like a simple await. The payoff is that once it’s set up, the C# side is just await context.SqlAsync(...) and the Tokio executor is doing real multi-core async work underneath. If you’re binding any other Tokio-based Rust library to .NET, you’ll probably end up with a fairly close variant of this same wiring — the specifics change but the shape is the same.

DataFusionSharp’s ADO.NET provider changes that. It wraps the Apache DataFusion query engine in a standard DbConnection, which means Dapper’s QueryAsync<T>, anonymous parameter objects, and strongly-typed result mapping all work out of the box. Same patterns you already know — pointed at S3 instead of a database.

This post builds a real example: querying the U.S. Energy Information Administration’s power plant data — three related Parquet files stored in a public S3 bucket. We’ll write three-way JOINs across utilities, power plants, and generators to answer questions like: which utilities have the most generation capacity? What does the energy mix look like across states? What are the largest generators in the country?

The ADO.NET Provider

The previous two posts covered DataFusionSharp’s core API — runtime, session context, DataFrame — and querying S3 data using Arrow batches. That works well for data pipelines, but most .NET application code doesn’t work with Arrow batches. Service layers, reporting code, controllers — they all expect List<T>.

The DataFusionSharp.Data package bridges this with a standard ADO.NET provider:

• DataFusionSharpConnection extends DbConnection
• DataFusionSharpCommand extends DbCommand
• DataFusionSharpDataReader extends DbDataReader
• DataFusionSharpParameter extends DbParameter

Because it implements System.Data.Common interfaces, any library built on ADO.NET works with DataFusionSharp. Dapper is the obvious one, but it also works with libraries like Insight.Database, or your own repository abstractions built on DbConnection.

The Dataset

We’ll use data from the Public Utility Data Liberation (PUDL) project, which publishes cleaned U.S. energy data as Parquet files in a public S3 bucket. The three tables we need:

Utilities (out_eia__yearly_utilities.parquet, 2.3 MB) — utility company records: name, state, entity type. Primary key: utility_id_eia + report_date.

Plants (out_eia__yearly_plants.parquet, 3.2 MB) — power plant records: name, city, state, coordinates, NERC region. Links to its operating utility via utility_id_eia. Primary key: plant_id_eia + report_date.

Generators (out_eia__yearly_generators.parquet, 10.3 MB) — individual generator units within plants: capacity in MW, fuel type, technology description, net generation, capacity factor. Links to its plant via plant_id_eia. Primary key: plant_id_eia + generator_id + report_date.

The relationship chain is Utility → Plants → Generators. A utility operates one or more plants, and each plant has one or more generators. This is a textbook relational structure — exactly the kind of data that JOINs are made for.

Setting Up

Install the packages:

dotnet add package DataFusionSharp.Data
dotnet add package Dapper

DataFusionSharp.Data pulls in the core DataFusionSharp package as a dependency.

Connect to S3, register the Parquet tables, and create a Dapper-compatible connection:

using DataFusionSharp;
using DataFusionSharp.Data;
using DataFusionSharp.ObjectStore;
using Dapper;

using var runtime = DataFusionRuntime.Create();
using var session = runtime.CreateSessionContext();

// Register public S3 bucket - no credentials needed
session.RegisterS3ObjectStore("s3://pudl.catalyst.coop", new S3ObjectStoreOptions
{
    BucketName = "pudl.catalyst.coop",
    Region = "us-west-2",
    SkipSignature = true,
});

// Register Parquet tables from S3
await session.RegisterParquetAsync(
    "utilities",
    "s3://pudl.catalyst.coop/stable/out_eia__yearly_utilities.parquet");
await session.RegisterParquetAsync(
    "plants",
    "s3://pudl.catalyst.coop/stable/out_eia__yearly_plants.parquet");
await session.RegisterParquetAsync(
    "generators",
    "s3://pudl.catalyst.coop/stable/out_eia__yearly_generators.parquet");

// Create ADO.NET connection - this is what Dapper uses
await using var connection = session.AsConnection();

Three Parquet files registered as SQL tables, backed by S3, queryable through a standard DbConnection. The AsConnection() extension method wraps the session context in an ADO.NET connection that Dapper knows how to work with.

Defining Models

Dapper maps query results to C# types by matching column aliases to property names. Define records for each query shape:

public record UtilityCapacity(
    string UtilityName,
    string? State,
    long PlantCount,
    double TotalCapacityMw);

public record StateEnergyMix(
    string State,
    string FuelType,
    long GeneratorCount,
    double TotalCapacityMw,
    double? AvgCapacityFactor);

public record TopGenerator(
    string PlantName,
    string? City,
    string? State,
    string UtilityName,
    string? Technology,
    float CapacityMw,
    double? NetGenerationMwh,
    double? CapacityFactor);

Querying with Dapper

Which utilities have the most generation capacity?

A three-way JOIN across all three tables to rank utilities by total installed capacity:

var topUtilities = await connection.QueryAsync<UtilityCapacity>("""
    SELECT
        u.utility_name_eia AS UtilityName,
        u.state AS State,
        COUNT(DISTINCT p.plant_id_eia) AS PlantCount,
        ROUND(CAST(SUM(g.capacity_mw) AS DOUBLE), 1) AS TotalCapacityMw
    FROM generators g
        JOIN plants p
            ON g.plant_id_eia = p.plant_id_eia
            AND g.report_date = p.report_date
        JOIN utilities u
            ON p.utility_id_eia = u.utility_id_eia
            AND p.report_date = u.report_date
    WHERE g.report_date = '2026-01-01'
        AND g.operational_status = 'existing'
    GROUP BY u.utility_name_eia, u.state
    ORDER BY TotalCapacityMw DESC
    LIMIT 15
    """);

foreach (var utility in topUtilities)
    Console.WriteLine($"{utility.UtilityName} ({utility.State}): {utility.TotalCapacityMw:N1} MW across {utility.PlantCount} plants");

This is standard Dapper — QueryAsync<T> with a SQL string. The SQL runs inside DataFusion’s query engine, reading Parquet data from S3 on the fly. Dapper sees a DbDataReader and maps columns to record properties by name. The query joins across three files totaling 16 MB, filters to currently operating generators as of the 2026 reporting year, aggregates by utility, and returns the top 15.

What does the energy mix look like?

Join generators with plants to analyze installed capacity by fuel type and state:

var energyMix = await connection.QueryAsync<StateEnergyMix>("""
    SELECT
        p.state AS State,
        CAST(g.fuel_type_code_pudl AS VARCHAR) AS FuelType,
        COUNT(*) AS GeneratorCount,
        ROUND(CAST(SUM(g.capacity_mw) AS DOUBLE), 1) AS TotalCapacityMw,
        ROUND(CAST(AVG(g.capacity_factor) AS DOUBLE), 3) AS AvgCapacityFactor
    FROM generators g
        JOIN plants p
            ON g.plant_id_eia = p.plant_id_eia
            AND g.report_date = p.report_date
    WHERE g.report_date = '2026-01-01'
        AND g.operational_status = 'existing'
        AND p.state IS NOT NULL
    GROUP BY p.state, g.fuel_type_code_pudl
    ORDER BY TotalCapacityMw DESC
    LIMIT 20
    """);

foreach (var row in energyMix)
    Console.WriteLine($"{row.State} - {row.FuelType}: {row.TotalCapacityMw:N1} MW ({row.GeneratorCount} generators)");

Notice the CAST(g.fuel_type_code_pudl AS VARCHAR) — some Parquet columns use Arrow’s dictionary encoding for efficient storage of repeated strings. The ADO.NET provider doesn’t expose dictionary types directly, so casting to VARCHAR in the query is the simplest way to handle them. This shows where capacity is concentrated — which states have the most gas, coal, wind, or solar, and how their capacity factors compare.

The largest generators in the country

A three-way JOIN to find the biggest individual generators with full context — plant name, location, operator, and technology:

var largestGenerators = await connection.QueryAsync<TopGenerator>("""
    SELECT
        p.plant_name_eia AS PlantName,
        p.city AS City,
        p.state AS State,
        u.utility_name_eia AS UtilityName,
        g.technology_description AS Technology,
        g.capacity_mw AS CapacityMw,
        ROUND(CAST(g.net_generation_mwh AS DOUBLE), 0) AS NetGenerationMwh,
        ROUND(CAST(g.capacity_factor AS DOUBLE), 3) AS CapacityFactor
    FROM generators g
        JOIN plants p
            ON g.plant_id_eia = p.plant_id_eia
            AND g.report_date = p.report_date
        JOIN utilities u
            ON p.utility_id_eia = u.utility_id_eia
            AND p.report_date = u.report_date
    WHERE g.report_date = '2026-01-01'
        AND g.operational_status = 'existing'
        AND g.capacity_mw IS NOT NULL
    ORDER BY g.capacity_mw DESC
    LIMIT 10
    """);

foreach (var gen in largestGenerators)
    Console.WriteLine($"{gen.PlantName} ({gen.State}): {gen.CapacityMw:N0} MW - {gen.Technology} [{gen.UtilityName}]");

Parameterized Queries

Dapper’s anonymous parameter objects work with DataFusionSharp. The ADO.NET provider translates @param syntax to DataFusion’s native $param format automatically:

var state = "TX";
var minCapacityMw = 100f;

var texasPlants = await connection.QueryAsync<TopGenerator>("""
    SELECT
        p.plant_name_eia AS PlantName,
        p.city AS City,
        p.state AS State,
        u.utility_name_eia AS UtilityName,
        g.technology_description AS Technology,
        g.capacity_mw AS CapacityMw,
        ROUND(CAST(g.net_generation_mwh AS DOUBLE), 0) AS NetGenerationMwh,
        ROUND(CAST(g.capacity_factor AS DOUBLE), 3) AS CapacityFactor
    FROM generators g
        JOIN plants p
            ON g.plant_id_eia = p.plant_id_eia
            AND g.report_date = p.report_date
        JOIN utilities u
            ON p.utility_id_eia = u.utility_id_eia
            AND p.report_date = u.report_date
    WHERE g.report_date = '2026-01-01'
        AND g.operational_status = 'existing'
        AND p.state = @state
        AND g.capacity_mw >= @minCapacityMw
    ORDER BY g.capacity_mw DESC
    LIMIT 10
    """,
    new { state, minCapacityMw });

foreach (var plant in texasPlants)
    Console.WriteLine($"{plant.PlantName}: {plant.CapacityMw:N0} MW - {plant.Technology} [{plant.UtilityName}]");

The @state and @minCapacityMw parameters are passed as a standard Dapper anonymous object. Under the hood, DataFusionSharpCommand rewrites them to $state and $minCapacityMw, maps their .NET types to DataFusion scalar values, and injects them into the query plan.

Scalar queries work the same way — ExecuteScalarAsync returns a single value:

var totalCapacity = await connection.ExecuteScalarAsync<double>("""
    SELECT ROUND(CAST(SUM(g.capacity_mw) AS DOUBLE), 1)
    FROM generators g
        JOIN plants p
            ON g.plant_id_eia = p.plant_id_eia
            AND g.report_date = p.report_date
    WHERE g.report_date = '2026-01-01'
        AND g.operational_status = 'existing'
        AND p.state = @state
    """,
    new { state = "CA" });

Console.WriteLine($"California total installed capacity: {totalCapacity:N1} MW");

The complete example from this post is available in the DataFusionSharp repository under examples/QueryS3DataWithDapper. The dataset is publicly available — no AWS credentials required. The PUDL project publishes cleaned EIA data at s3://pudl.catalyst.coop/stable/ under a CC-BY-4.0 license.

If you’re already using Dapper with a database today, adding DataFusionSharp as a second data source is straightforward: the same QueryAsync<T> calls, the same parameter passing, the same result mapping — just pointed at files in S3 instead of rows in a table.

DataFusionSharp is on GitHub at github.com/nazarii-piontko/datafusion-sharp. If you’re new to the library, the introductory post covers the fundamentals — runtime, sessions, and local file queries. The S3 querying post goes deeper on object store configuration, Hive partitioning, and Arrow batch processing. If you run into issues or have ideas for the API, open an issue or a pull request.

The typical path forward is to leave .NET. Fire up a Jupyter notebook with PyArrow, spin up an Athena query, or download the files locally and process them with something else. If you’ve done this enough times, the friction becomes familiar: context-switching between languages, waiting for infrastructure, or managing local copies of data that already lives perfectly well in the cloud.

When I built DataFusionSharp, the first version only worked with local files — CSV, Parquet, and JSON on disk. That was useful, but it didn’t address the reality that most analytical data lives in object stores. The latest release changes that. DataFusionSharp now supports S3, Azure Blob Storage, Google Cloud Storage, and HTTP endpoints as data sources. Register a store, register a table, write SQL. The data stays where it is.

This post walks through querying Parquet data in S3 from a .NET console application. The dataset is public, so everything here runs without AWS credentials.

Connecting to S3

The pattern is two steps: register an object store for a URL scheme, then register tables using URLs instead of local paths. Here’s what connecting to a public S3 bucket looks like:

using var runtime = DataFusionRuntime.Create();
using var context = runtime.CreateSessionContext();

// Register public S3 bucket (no credentials needed)
context.RegisterS3ObjectStore("s3://arrow-datasets", new S3ObjectStoreOptions
{
    BucketName = "arrow-datasets",
    Region = "us-east-1",
    SkipSignature = true,
});

SkipSignature = true tells the client to skip request signing, which is how you access public buckets anonymously. For private buckets, you’d set AccessKeyId and SecretAccessKey, or provide a session Token for temporary credentials. If you’re running on EC2 or ECS with an IAM role, leave the credentials out entirely and the AWS credential chain handles it.

The same pattern works for S3-compatible services like MinIO — just set the Endpoint property to your service URL and AllowHttp = true if you’re not using TLS.

Hive Partitioning

The dataset we’ll query is the diamonds dataset from the Apache Arrow test data registry. It’s stored as Parquet files using Hive-style partitioning, where directory names encode column values:

s3://arrow-datasets/diamonds/
  cut=Fair/
    part-0.parquet
  cut=Good/
    part-0.parquet
  cut=Ideal/
    part-0.parquet
  cut=Premium/
    part-0.parquet
  cut=Very Good/
    part-0.parquet

Each subdirectory contains rows for one value of the cut column. The column itself doesn’t exist inside the Parquet files — DataFusion reconstructs it from the directory structure. To use this, you declare partition columns when registering the table:

await context.RegisterParquetAsync("diamonds", "s3://arrow-datasets/diamonds/",
    new ParquetReadOptions
    {
        TablePartitionCols = [new PartitionColumn("cut", StringType.Default)],
        ParquetPruning = true,
    });

TablePartitionCols tells DataFusion which directory levels map to which columns and their types. ParquetPruning = true enables predicate pushdown at the partition level: when your query filters on cut, DataFusion only reads the matching partition directories. A WHERE cut = 'Ideal' skips four out of five partitions entirely. For large datasets with many partitions, this is the difference between scanning everything and scanning almost nothing.

Querying the Data

Once the table is registered, everything works exactly like querying local files. The SQL is standard, the results come back as Arrow batches, and you can use the same DataFrame API from my previous post.

A useful first step with an unfamiliar dataset is inspecting its schema:

using (var df = await context.SqlAsync("SELECT * FROM diamonds LIMIT 0"))
{
    var schema = df.GetSchema();
    foreach (var field in schema.FieldsList)
        Console.WriteLine($"  {field.Name}: {field.DataType.Name}");
}

The LIMIT 0 trick returns no rows but still resolves the full schema, including the cut partition column that DataFusion injects. This is a fast way to understand what columns are available before writing any real queries.

With the schema in hand, we can run aggregations. Here’s a breakdown of price statistics by cut:

using (var df = await context.SqlAsync("""
    SELECT
        cut,
        count(*) AS cnt,
        ROUND(avg(price), 2) AS avg_price,
        min(price) AS min_price,
        max(price) AS max_price,
        ROUND(stddev(price), 2) AS price_stddev
    FROM diamonds
    GROUP BY cut
    ORDER BY avg_price DESC
    """))
    Console.WriteLine(await df.ToStringAsync());

DataFusionSharp also supports parameterized queries. Parameters are passed as a list of name-value tuples, and DataFusion substitutes them before execution:

using (var df = await context.SqlAsync("""
    SELECT carat, color, clarity, price
    FROM diamonds
    WHERE cut = $cut
      AND carat >= $min_carat
    ORDER BY price DESC
    LIMIT 10
    """,
    [("cut", "Ideal"), ("min_carat", 2.0)]))
    Console.WriteLine(await df.ToStringAsync());

Notice that the $cut parameter filters on the partition column. Because partition pruning is enabled, DataFusion resolves the parameter value before planning the scan and only reads the cut=Ideal/ directory. The other partitions are never touched.

Query results can also be written back to files. If you want to materialize an aggregation as a local Parquet file:

using (var df = await context.SqlAsync("""
    SELECT
        cut,
        color,
        count(*) AS cnt,
        ROUND(avg(price), 2) AS avg_price,
        ROUND(avg(carat), 3) AS avg_carat
    FROM diamonds
    GROUP BY cut, color
    ORDER BY cut, color
    """))
{
    var outputPath = Path.Combine(Directory.GetCurrentDirectory(), "output", "diamond_summary.parquet");
    Directory.CreateDirectory(Path.GetDirectoryName(outputPath)!);
    await df.WriteParquetAsync(outputPath);
    Console.WriteLine($"Written to: {outputPath}");
}

This reads from S3, aggregates in-process, and writes the result locally — a one-way ETL step in a dozen lines.

Working with Arrow Batches

When you need to process results programmatically rather than printing them, CollectAsync gives you Apache Arrow RecordBatch objects with typed column arrays:

using (var df = await context.SqlAsync("""
    SELECT
        carat,
        cut,
        color,
        clarity,
        price,
        ROUND(CAST(price AS DOUBLE) / carat, 2) AS price_per_carat
    FROM diamonds
    WHERE carat > 0.5
    ORDER BY price_per_carat ASC
    LIMIT 5
    """))
{
    using var collected = await df.CollectAsync();
    foreach (var batch in collected.Batches)
    {
        for (var r = 0; r < batch.Length; r++)
        {
            for (var c = 0; c < batch.ColumnCount; c++)
            {
                var v = batch.Column(c) switch
                {
                    StringArray a => (object?)a.GetString(r),
                    DoubleArray a => a.GetValue(r),
                    Int64Array a => a.GetValue(r),
                    FloatArray a => a.GetValue(r),
                    _ => batch.Column(c).GetType().Name
                };
                Console.Write($"{v}\t");
            }
            Console.WriteLine();
        }
    }
}

These are the same Arrow RecordBatch objects you’d get from querying local files. The Apache.Arrow NuGet package gives you typed arrays (StringArray, DoubleArray, Int64Array, etc.), schema introspection, and interoperability with other Arrow-compatible tools in the .NET ecosystem.

Beyond S3

The same object store pattern works for other cloud storage backends. Azure Blob Storage uses the az:// scheme:

context.RegisterAzureBlobStorage("az://my-container", new AzureBlobStorageOptions
{
    ContainerName = "my-container",
    AccountName = "myaccount",
    AccessKey = "base64key...",
});

Google Cloud Storage uses gs://:

context.RegisterGoogleCloudStorage("gs://my-bucket", new GoogleCloudStorageOptions
{
    BucketName = "my-bucket",
    CredentialsPath = "/path/to/service-account.json",
});

Each backend has its own options class with the authentication methods you’d expect: access keys, SAS tokens, service principals for Azure; service account credentials for GCS. HTTP endpoints are also supported for read-only access to data served over plain HTTPS.

The query code doesn’t change — once a table is registered, SQL works the same regardless of where the data lives. This is one of the things I appreciate about DataFusion’s architecture: the storage layer is fully decoupled from the query engine.

Getting Started

dotnet add package DataFusionSharp

The complete example from this post is available in the DataFusionSharp repository under examples/QueryS3Data. The public arrow-datasets bucket needs no AWS credentials, so you can run it as-is.

DataFusionSharp is on GitHub at github.com/nazarii-piontko/datafusion-sharp. If you’re new to the library, the introductory post covers the basics — runtime, sessions, and local file queries. If you run into issues or have ideas for the API, open an issue or a pull request.

The options in the .NET ecosystem have historically been limited. You could use System.Data with a file-backed SQLite database, wire up DuckDB, or ship data over the network to an external query engine. None of these feel right as a first-class .NET solution. What’s missing is an idiomatic, embeddable, high-performance SQL query engine that works directly on columnar data — something .NET has never really had.

That gap is what motivated me to build DataFusionSharp.

What Is Apache DataFusion?

Apache DataFusion is a query engine written in Rust, built on top of Apache Arrow. It’s designed for high-performance analytical workloads: think scanning large files, aggregating millions of rows, joining multiple tables — all processed in-process without a server.

What makes DataFusion stand out is the combination of things it brings together:

• Vectorized execution — it processes data in columnar batches using Apache Arrow’s in-memory format, which maps naturally to modern CPU cache behavior and SIMD instructions
• SQL query optimizer — a full logical and physical query planner with rule-based and cost-based optimizations
• Datasource abstraction — read from CSV, Parquet, JSON, or plug in a custom source
• Async, parallel execution — built on Tokio, DataFusion can execute queries using a thread pool with true async I/O

DataFusion has become the foundation for a number of serious data tools in the Rust ecosystem. The Python community got datafusion-python — official Apache-maintained bindings. The Java community got datafusion-java. The .NET community had nothing. Until now.

Introducing DataFusionSharp

DataFusionSharp is a .NET library that exposes Apache DataFusion through idiomatic C# APIs. The approach is straightforward: a thin Rust FFI layer bridges the managed and native worlds, and C# P/Invoke calls drive it from the .NET side. Results are exchanged using Apache Arrow’s C Data Interface, so you get native Arrow RecordBatch objects on the .NET side.

The library is organized around three types that map directly to how DataFusion works:

DataFusionRuntime — wraps a Tokio async runtime and manages the native library’s lifecycle. Create one per application and keep it alive for the duration of your process. It owns the thread pool that executes your queries.

SessionContext — an isolated query execution environment. Register your data sources here and execute SQL. Multiple contexts can coexist on the same runtime, and each is independent: tables registered in one context are not visible in another. Create one per logical session or per query workflow.

DataFrame — a lazy handle to a query result. The actual computation happens when you call a terminal operation. Available terminal operations are:

• CollectAsync() — execute the query and return all results as Arrow RecordBatch objects
• ExecuteStreamAsync() — execute the query and stream results as an IAsyncEnumerable<RecordBatch>
• CountAsync() — count result rows without materializing data
• GetSchemaAsync() — inspect the result schema before executing
• ShowAsync() / ToStringAsync() — print results, useful during development

The library ships prebuilt native binaries for Linux x64, Linux arm64, Windows x64, and macOS arm64, so you don’t need a Rust toolchain to use it. Add it with:

dotnet add package DataFusionSharp

A Quick Example

Let’s say we have two CSV files: customers.csv with customer records and orders.csv with order data, and we want to find the total completed order value per customer. Here is the full program:

using Apache.Arrow;
using DataFusionSharp;

// Create runtime — one per application, owns the Tokio thread pool
using var runtime = DataFusionRuntime.Create();

// Create session — one per logical query workflow
using var context = runtime.CreateSessionContext();

// Register CSV tables (Parquet and JSON work the same way)
await context.RegisterCsvAsync("customers", "data/customers.csv");
await context.RegisterCsvAsync("orders", "data/orders.csv");

// Execute SQL — returns a lazy DataFrame
using var df = await context.SqlAsync(
    """
    SELECT
        c.customer_name,
        sum(o.order_amount) AS total_amount
    FROM orders AS o
        JOIN customers AS c ON o.customer_id = c.customer_id
    WHERE o.order_status = 'Completed'
    GROUP BY c.customer_name
    ORDER BY c.customer_name
    """);

// Print a formatted table to console — handy for development
Console.WriteLine(await df.ToStringAsync());

// Inspect the result schema
var schema = await df.GetSchemaAsync();
foreach (var field in schema.FieldsList)
    Console.WriteLine($"{field.Name}: {field.DataType}");

Notice the structure: create runtime, create session, register sources, execute SQL, consume results. The SQL is standard — the same query would run unchanged in PostgreSQL or DuckDB.

For use cases where you need to process rows as they come rather than loading everything into memory at once, ExecuteStreamAsync gives you an async enumerable of RecordBatch objects:

using var stream = await df.ExecuteStreamAsync();
await foreach (var batch in stream)
{
    for (var row = 0; row < batch.Length; row++)
    {
        var name = ((StringArray)batch.Column(0)).GetString(row);
        var total = ((Int64Array)batch.Column(1)).GetValue(row);
        Console.WriteLine($"{name}: {total}");
    }
}

If you prefer to collect all data at once and then process it in memory, CollectAsync returns a collection of batches:

using var result = await df.CollectAsync();
foreach (var batch in result.Batches)
{
    // process batch...
}

Both paths give you Apache Arrow RecordBatch objects. The Arrow ecosystem in .NET — via the Apache.Arrow NuGet package — gives you typed arrays, schema introspection, and interoperability with other Arrow-compatible tools.

For Parquet files, the registration is a single method swap:

await context.RegisterParquetAsync("orders", "data/orders.parquet");

The rest of the query code stays identical. Same for JSONL files:

await context.RegisterJsonAsync("orders", "data/orders.json");

This is one of the things I appreciate about DataFusion’s design: the query layer is completely decoupled from the storage layer.

Current State

DataFusionSharp is early-stage software. Here is an honest picture of what works today and what doesn’t:

The practical implication: if you want to query CSV, Parquet, or JSON files using SQL and consume the results as Arrow batches, that works today and works well. If you need to push in-memory Arrow data into DataFusion, or register custom functions, or manage catalogs — those are on the roadmap.

Note that this is an independent community project. It is not affiliated with or endorsed by the Apache Software Foundation.

What’s Next

The most impactful things on the near-term roadmap:

• In-memory table registration — push an Arrow RecordBatch directly into a session context as a table, no files required
• Catalog management — expose APIs to create and manage catalogs, schemas, and tables programmatically
• UDF support — register C# functions that DataFusion can call during query execution

If any of these are interesting to you, contributions are very welcome.

DataFusionSharp is on GitHub at github.com/nazarii-piontko/datafusion-sharp. If you try it and run into something unexpected, open an issue. If you have ideas for the API design or want to contribute, pull requests are open.

For simplification, let’s assume we need to pack 1024 64-bit unsigned integer values using 8 bits each in C++. Bitpacking is a common operation in compression algorithms and data serialization, where we want to squeeze multiple small values into a single machine word to save space.

The Naive Approach

What most of us would write first is a straightforward nested loop that processes values one at a time, something like this (simplified, no error checking, no bounds checking):

constexpr size_t ARRAY_SIZE = 1024; // Total number of input values

void bitpack_naive(const uint64_t* __restrict input, uint64_t* __restrict output) {
    for (size_t i = 0, j = 0; i < ARRAY_SIZE; ) {
        uint64_t acc = 0;

        for (size_t k = 0, shift = 0; k < 8; ++k, ++i, shift += 8)
            acc |= (input[i] & 0xFF) << shift;

        output[j++] = acc;
    }
}

This code reads 8 consecutive input values, masks each to 8 bits, shifts them into appropriate position in accumulator, and combines them into a single 64-bit output word using bitwise OR. It’s simple, clean, readable, and… surprisingly effective when compiled with -O3 (-O3 option enables aggressive optimizations, additionally -msse4 for SSE or -mavx2 for AVX2 can be used to enable specific SIMD instruction sets).

Note: SSE (Streaming SIMD Extensions) allows to process multiple data points in parallel using 128-bit registers. It uses xmm CPU registers and instructions like pand, psllq, or por to manipulate data in parallel. Another common SIMD instruction set is AVX, which uses 256-bit ymm CPU registers.

Looking at the generated assembly, we can see the compiler (clang-21 in my case) has done something remarkable. Instead of the simple scalar operations we wrote, it’s generated SIMD code using SSE instructions. Here’s a snippet of the generated assembly:

; Load pre-computed mask constants into XMM registers
movdqa  .LCPI7_0(%rip), %xmm0       ; xmm0 = mask for bytes 0 and 8 [255,0,0,0,0,0,0,0,255,0,0,0,0,0,0,0]
movdqa  .LCPI7_1(%rip), %xmm1       ; xmm1 = mask for bytes 1 and 9 [0,255,0,0,0,0,0,0,0,255,0,0,0,0,0,0]
; ... (additional masks loaded for other byte positions)

.LBB7_1:                            ; Main loop starts here
  ; Load two 64-bit values from different locations into XMM registers
  movq       64(%rdi,%rax,8), %xmm7 ; Load value at input index 8 (64-bit data at address 64 + base, 64 = skip 8 values * 8 bytes each, base = %rdi + %rax*8) into xmm7 - second value
  movq       (%rdi,%rax,8), %xmm8   ; Load value at input index 0 (64-bit data at address 0 + base, base = %rdi + %rax*8) into xmm8 - first value
  punpcklqdq %xmm7, %xmm8           ; Combine the two values into a single 128-bit register xmm8
  pand       %xmm0, %xmm8           ; Apply mask to extract only the bytes we want, bitwise AND, result in xmm8

  ; Repeat for next pair of values
  movq       72(%rdi,%rax,8), %xmm7 ; Load value at input index 9 (64-bit data at address 72 + base, 72 = skip 9 values * 8 bytes each, base = %rdi + %rax*8) into xmm7
  movq       8(%rdi,%rax,8), %xmm9  ; Load value at input index 1 (64-bit data at address 8 + base, 8 = skip 1 value * 8 byte, base = %rdi + %rax*8) into xmm9
  punpcklqdq %xmm7, %xmm9           ; Combine the two values into a single 128-bit register xmm9
  psllq      $8, %xmm9              ; Shift left by 8 bits to position the byte correctly, result in xmm9
  pand       %xmm1, %xmm9           ; Apply mask to extract only the bytes we want, bitwise AND, result in xmm9

  por        %xmm8, %xmm9           ; Combine with previous result using bitwise OR, result in xmm9

  ; ... (similar operations for remaining bytes)

  movdqu     %xmm8, (%rsi,%rax)     ; Store the final packed result into output array

  ; Loop counter increment and check
  addq       $16, %rax              ; Move base forward by 16
  cmpq       $1024, %rax            ; Compare base with 1024
  jne        .LBB7_1                ; Jump back if not done

Note: The exact instruction mix, register allocation, and masks will vary by compiler version, target CPU, and flags. The snippets are representative of the optimization strategy rather than a byte-for-byte listing.

The compiler has done two clever optimizations here:

1. Loop unrolling. The compiler unrolls the outer loop by a factor of 2, processing two output words per iteration (one from input indices 0-7, another from 8-15). The next iteration processes input indices 16-23 and 24-31, and so on. The inner loop is effectively eliminated through vectorization. This reduces loop overhead and increases instruction-level parallelism.

2. Auto-vectorization. It’s using SIMD SSE instructions to process multiple values in parallel. The punpcklqdq instruction interleaves data, psllq performs parallel shifts, pand performs bitwise AND with mask, and por combines results.

The compiler is working hard to vectorize a pattern that wasn’t originally written with SIMD in mind. While the memory accesses are actually sequential (reading consecutive elements 0, 1, 2, 3…), the compiler must use intricate shuffle operations (punpcklqdq) to reorganize this data into SIMD-friendly positions, which adds overhead.

The Vectorization-Friendly Approach

Now, let’s restructure the code slightly. Instead of reading consecutive elements and packing them together, we’ll change the access pattern together with manual loop unrolling:

void bitpack_vectorized(const uint64_t* __restrict input, uint64_t* __restrict output) {
    for (int i = 0; i < 128; ++i) {
        uint64_t acc = input[i] & 0xFF;
        acc |= (input[i + 128] & 0xFF) << 8;
        acc |= (input[i + 256] & 0xFF) << 16;
        acc |= (input[i + 384] & 0xFF) << 24;
        acc |= (input[i + 512] & 0xFF) << 32;
        acc |= (input[i + 640] & 0xFF) << 40;
        acc |= (input[i + 768] & 0xFF) << 48;
        acc |= (input[i + 896] & 0xFF) << 56;
        output[i] = acc;
    }
}

So what’s changed? Instead of reading 8 consecutive input values, we’re now reading values that are 128 elements apart: i, i + 128, i + 256, and so on.

Why this particular pattern? We’re processing 1024 values, packing 8 bits from each value. This means we’ll produce 128 output values (1024 / 8 = 128). Each iteration handles one output value by reading from 8 locations spaced 128 elements apart. This stride length (128) isn’t arbitrary - it’s the number of output values we’re producing, which ensures each iteration processes one value from each “slice” of the input array.

The generated assembly for this version looks like this:

; Same mask setup as before
movdqa  .LCPI8_0(%rip), %xmm0      ; Load masks into XMM registers
; ... (other masks)

.LBB8_1:                           ; Main loop
  ; Load 16 bytes (2 uint64_t values) with simple, contiguous access
  movdqu  (%rdi,%rax,8), %xmm7     ; Load 2 contiguous values from indices 0 and 1 (data address 0 + base, base = %rdi + %rax*8) into xmm7
  pand    %xmm0, %xmm7             ; Apply mask to extract relevant bytes, result in xmm7

  ; Load from next stride - still contiguous relative to loop counter
  movdqu  1024(%rdi,%rax,8), %xmm8 ; Load 2 contiguous values from indices 128 and 129 (1024 + base, 1024 = 128 values * 8 bytes each, base = %rdi + %rax*8) into xmm8
  psllq   $8, %xmm8                ; Shift left by 8 bits to position byte correctly, result in xmm8
  pand    %xmm1, %xmm8             ; Apply mask to extract relevant bytes, result in xmm8

  por     %xmm7, %xmm8             ; Combine with previous, result in xmm8

  ; ... (similar operations for remaining bytes)

  movdqu  %xmm8, (%rsi,%rax,8)     ; Store packed result into output

  ; Loop counter increment and check
  addq    $2, %rax                 ; Increment index by 2
  cmpq    $128, %rax               ; Compare index with 128
  jne     .LBB8_1                  ; Jump back if not done

Why Is This Faster?

To visualize the difference:

• Naive approach - reads consecutive elements, requires shuffling:

  Iteration i=0,1: read [0,8] [1,9] [2,10]... [7,15] → shuffle → pack → output[0,1]
  Iteration i=2,3: read [16,24] [17,25] [18,26]... [23,31] → shuffle → pack → output[2,3]
  ...
  Iteration i=126,127: read [1008,1016] [1009,1017]... [1015,1023] → shuffle → pack → output[126,127]
  

  Problem: To vectorize, must load [0] and [8] together, [1] and [9] together, etc. Requires punpcklqdq to interleave non-adjacent values.

• Vectorized approach - reads strided elements, naturally aligned. Input conceptually divided into 8 slices of 128 elements:

  Iteration i=0,1: read [0,1] [128,129] [256,257]... [896,897] → pack → output[0,1]
  Iteration i=2,3: read [2,3] [130,131] [258,259]... [898,899] → pack → output[2,3]
  ...
  Iteration i=126,127: read [126,127] [254,255]... [1022,1023] → pack → output[126,127]
  

  Advantage: Loading [0,1] or [128,129] is a single movdqu instruction. Values naturally align to SIMD lanes - no shuffling needed.

The key differences from the naive version:

1. Simpler memory access pattern. While the accesses are strided rather than sequential, they map naturally to SIMD lanes without requiring shuffle operations. Instead of the complex punpcklqdq instructions, we now have straightforward movdqu (move unaligned double quadword) loads from predictable offsets: base, base+1024, base+2048, etc.

2. No data reorganization needed. The naive version had to use punpcklqdq to interleave data from different memory locations. The vectorized version eliminates this entirely - the data is already in the right layout for SIMD processing.

3. Better instruction-level parallelism. The simpler instruction sequence allows the CPU’s out-of-order execution to work more effectively. There are fewer dependencies between operations.

4. Cache-friendly for this workload. While strided access can sometimes have worse cache behavior than sequential access, our working set (1024 × 8 = 8KB) fits comfortably in L1 cache, so the strided pattern doesn’t introduce cache penalties. For much larger datasets, this trade-off would need careful consideration.

The benchmark results speak for themselves: the vectorized version is approximately 2x faster than the naive implementation.

Benchmark Results produced with nanobench on Debian GNU/Linux 12 bookworm (x86-64) with Intel© Core™ i7-10510U CPU @ 1.80GHz × 4:

| relative |  ns/op |         op/s | err% | total | benchmark
|---------:|-------:|-------------:|-----:|------:|:------------
|   100.0% | 499.44 | 2,002,232.02 | 0.0% |  0.12 | `naive`
|   212.9% | 234.64 | 4,261,819.64 | 0.2% |  0.06 | `vectorized`

This example demonstrates a counterintuitive principle in performance optimization: the way we access our data matters more than we might think. By restructuring array accesses to align with how SIMD instructions operate, we can help the compiler generate dramatically more efficient code - even when the change seems to make the algorithm “worse” from a traditional optimization perspective.

Bonus: The Same Principle in C#

While we’ve been exploring C++ throughout this article, the principle of SIMD-friendly access patterns applies to other languages as well. C# provides explicit SIMD support through the System.Runtime.Intrinsics namespace, allowing to write vectorized code directly.

Unlike C++, where the compiler often auto-vectorizes loops, C# typically requires to write explicit SIMD code using intrinsics. However, the core insight remains the same: the strided access pattern we discovered translates directly to better SIMD performance in C# as well.

Here’s how both approaches look in C#:

public static class BitPacker
{
    public const int ArraySize = 1024;
    
    public static void PackNaive(ReadOnlySpan<ulong> input, Span<ulong> output)
    {
        for (int i = 0, j = 0; i < input.Length; )
        {
            ulong acc = 0;
            
            for (int k = 0, shift = 0; k < 8; ++k, ++i, shift += 8)
                acc |= (input[i] & 0xFF) << shift;
            
            output[j++] = acc;
        }
    }
    
    public static unsafe void PackSIMD(ReadOnlySpan<ulong> input, Span<ulong> output)
    {
        // We need unsafe code to work with pointers for intrinsics
        fixed (ulong* inputPtr = input) // Pin input span to get a pointer
        fixed (ulong* outputPtr = output) // Pin output span to get a pointer
        {
            // Pre-create mask vectors for each byte position
            var mask0 = Vector128.Create(0xFF, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0, 0, 0, 0, 0, 0, 0).AsUInt64();
            var mask1 = Vector128.Create(0, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0, 0, 0, 0, 0, 0).AsUInt64();
            var mask2 = Vector128.Create(0, 0, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0, 0, 0, 0, 0).AsUInt64();
            var mask3 = Vector128.Create(0, 0, 0, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0, 0, 0, 0).AsUInt64();
            var mask4 = Vector128.Create(0, 0, 0, 0, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0, 0, 0).AsUInt64();
            var mask5 = Vector128.Create(0, 0, 0, 0, 0, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0, 0).AsUInt64();
            var mask6 = Vector128.Create(0, 0, 0, 0, 0, 0, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0).AsUInt64();

            for (int i = 0; i < 128; i += 2)
            {
                Sse2.Or( // Combine two output values
                    Sse2.Or( // Combine first four loads
                        Sse2.Or( // Combine first four loads
                            Sse2.And(Sse2.LoadVector128(inputPtr + i), mask0), // First 128-bit load
                            Sse2.And(Sse2.ShiftLeftLogical(Sse2.LoadVector128(inputPtr + i + 128), 8), mask1)), // Second 128-bit load
                        Sse2.Or( // Combine third and fourth loads
                            Sse2.And(Sse2.ShiftLeftLogical(Sse2.LoadVector128(inputPtr + i + 256), 16), mask2), // Third 128-bit load
                            Sse2.And(Sse2.ShiftLeftLogical(Sse2.LoadVector128(inputPtr + i + 384), 24), mask3))), // Fourth 128-bit load
                    Sse2.Or( // Combine last four loads
                        Sse2.Or( // Combine fifth and sixth loads
                            Sse2.And(Sse2.ShiftLeftLogical(Sse2.LoadVector128(inputPtr + i + 512), 32), mask4), // Fifth 128-bit load
                            Sse2.And(Sse2.ShiftLeftLogical(Sse2.LoadVector128(inputPtr + i + 640), 40), mask5)), // Sixth 128-bit load
                        Sse2.Or( // Combine seventh and eighth loads
                            Sse2.And(Sse2.ShiftLeftLogical(Sse2.LoadVector128(inputPtr + i + 768), 48), mask6), // Seventh 128-bit load
                            Sse2.ShiftLeftLogical(Sse2.LoadVector128(inputPtr + i + 896), 56)))) // Eighth 128-bit load
                    .Store(outputPtr + i); // Store the packed result
            }
        }
    }
}

This is the straightforward translation of original assembly code - reading consecutive elements and packing them together.

The SIMD version follows the same pattern we discovered:

• We access the input array with strides of 128 elements
• Load pairs of values into Vector128<ulong> registers
• Apply shifts and masks using SSE2 intrinsics
• Combine the results with bitwise OR operations

The notable differences from C++ is explicit intrinsics. While the C++ compiler is able to auto-vectorize code, in C# we’re directly calling methods like Sse2.ShiftLeftLogical and Sse2.And. This gives us fine-grained control but requires more verbose code. Of course, it is possible to be that explicit in C++ as well using intrinsics, but auto-vectorization is often more convenient, nevertheless understanding how to write SIMD-friendly code is crucial.

Benchmarking with BenchmarkDotNet on Debian GNU/Linux 12 bookworm (x86-64) with Intel© Core™ i7-10510U CPU @ 1.80GHz × 4:

| Method | Mean       | Error   | StdDev  | Ratio |
|------- |-----------:|--------:|--------:|------:|
| Naive  | 1,358.0 ns | 3.00 ns | 2.50 ns |  1.00 |
| SIMD   |   311.5 ns | 3.47 ns | 3.07 ns |  0.23 |

SIMD implementation significantly (about 4.3x) outperforms the naive scalar approach, demonstrating that the principle of SIMD-friendly access patterns is language-agnostic. The lesson carries across: whether you’re writing C++, C#, or any other language with SIMD support, thinking about how your data access patterns align with SIMD operations is crucial for achieving optimal performance.

This article shows the pattern: one Aspire Host project that switches between local emulation and real AWS deployment based on execution context. When running locally, Aspire wires up LocalStack and containers. When publishing, the same file hands off to an AWS CDK stack that provisions VPC, Aurora Serverless, DynamoDB, Lambda, and API Gateway. Same logical service architecture (API → Database, API → DynamoDB), slightly different infrastructure implementations.

Before diving into code, the key constraint: Aspire today (late 2025) doesn’t have a native publisher for AWS. It can’t package a .NET project into a Lambda-compatible zip, manage versions, or model AWS-specific resources like RDS Proxy or VPC endpoints. Luckily, AWS CDK already solves all of this. So the pattern is: Aspire orchestrates (decides local vs publish, wires references), CDK provisions (synthesizes CloudFormation, bundles Lambda assets, deploys to AWS). This keeps everything in one place without waiting for Aspire to grow full AWS deployment primitives. Think of it as Aspire being the high-level orchestrator that knows about services and their relationships, while CDK is the specialized tool that knows exactly how to package .NET code for Lambda, create VPC configurations, and wire up security groups. Each tool does what it does best.

What We’ll Build

We’ll deploy a sample application based on a serverless services: a Lambda function running our API, Aurora Serverless v2 for PostgreSQL, DynamoDB for auxiliary storage, and API Gateway routing HTTP traffic. Everything runs in a private VPC with no direct internet access except the API Gateway endpoint.

During local development, Aspire spins up LocalStack to emulate DynamoDB and other AWS services, plus a Postgres container for the database. When publishing, we’ll provision real AWS resources.

Local mode:

• LocalStack emulates DynamoDB
• Local Postgres container for the database
• AWS Lambda emulator runs the API locally
• API Gateway emulator routes HTTP requests

AWS mode:

• CDK stack provisions real AWS resources
• VPC
• Aurora Serverless v2 + RDS Proxy
• DynamoDB table
• Lambda function
• HTTP API Gateway

The Aspire Host

Now that we’ve outlined the architectural differences, let’s see how Aspire orchestrates this dual-mode behavior. The key insight is that Aspire can detect whether it’s running in local development mode or publish mode (when deploying to AWS), and conditionally wire up different infrastructure providers based on that context.

The entire orchestration logic lives in a single host file. There’s no separate deployment configuration, no CI/CD YAML with infrastructure definitions scattered across multiple files. Instead, we use Aspire’s ExecutionContext.IsPublishMode to branch between local emulation and AWS deployment:

Here’s the complete branching logic:

// Select between local emulation and AWS deployment
// IsPublishMode is true when running 'dotnet run --project Host -- --publisher ...'
if (builder.ExecutionContext.IsPublishMode)
{
    // AWS SDK configuration
    var awsConfig = builder.AddAWSSDKConfig()
        .WithProfile(builder.Configuration.GetValue("AWS:Profile"))
        .WithRegion(RegionEndpoint.GetBySystemName(builder.Configuration.GetValue("AWS:Region")));

    // CDK stack provisioning full production infrastructure
    builder.AddAWSCDKStack("AwsSampleStack", s => new SampleStack(s))
        .WithReference(awsConfig);
}
else
{
    // AWS SDK configuration for LocalStack
    var awsConfig = builder.AddAWSSDKConfig()
        .WithProfile(builder.Configuration.GetValue("AWS:Profile"))
        .WithRegion(RegionEndpoint.GetBySystemName(builder.Configuration.GetValue("AWS:Region")));
    
    // LocalStack setup
    var awsLocal = builder.AddLocalStack("AwsLocal", awsConfig: awsConfig);
    
    // CDK stack provisioning subset of resources for LocalStack
    var awsStack = builder.AddAWSCDKStack("AwsSampleBaseStack", s => new SampleBaseStack(s))
        .WithReference(awsConfig);

    // Local Postgres container
    var postgres = builder.AddPostgres("Postgres");

    // Lambda function running the API locally
    var api = builder.AddAWSLambdaFunction<Projects.Api>("Api", "Api")
        .WithReference(awsStack)
        .WithReference(postgres);

    // API Gateway emulator routing all requests to the Lambda
    builder.AddAWSAPIGatewayEmulator("ApiGatewayEmulator", APIGatewayType.HttpV2)
        .WithReference(api, Method.Any, "/{proxy+}");
    
    // Wire up LocalStack
    builder.UseLocalStack(awsLocal);
}

Key differences:

• CDK Stack: Publish provisions SampleStack (full production infrastructure with VPC, Aurora, Lambda, API Gateway); local provisions SampleBaseStack (just a subset of AWS services for LocalStack to emulate, DynamoDB table)
• Database: Local adds an explicit Postgres container resource; publish mode relies on the RDS Aurora cluster defined in the CDK stack
• Lambda Reference: Local mode uses .AddAWSLambdaFunction<Projects.Api> to run the API as a Lambda emulator locally

That single IsPublishMode check is the seam between emulation and deployment. When we run dotnet run --project Host, we get local mode. When we run dotnet run --project Host -- --publisher ..., we get publish mode and CDK takes over.

The Environment Parity Trade-Off

Here’s the elephant in the room: this approach technically violates the principle of environment parity. Local mode uses Postgres in a container; production uses Aurora Serverless v2 with RDS Proxy. Local uses LocalStack’s DynamoDB emulation; production uses real DynamoDB. Local runs the API in a Lambda emulator; production runs it in actual Lambda with VPC networking, security groups, and IAM roles.

So why accept this split?

Perfect parity between local and cloud is rarely worth the cost. Emulating every managed service nuance (full VPC routing, Aurora serverless scaling behavior, RDS Proxy, IAM evaluation, realistic latency) on a laptop adds friction and slows the inner loop. The alternative - developing directly against live AWS - slows feedback (deploy per change), consumes budget, requires constant connectivity, and blocks offline work.

So we aim for logical parity over physical parity: same code paths, dependency graph, configuration keys, contracts (HTTP/data/events), and instrumentation; different implementations tuned for their environment. Local maximizes iteration speed; production maximizes reliability, scalability, and security.

What makes this work:

• Same application code: The services code runs identically in both environments. We use a small provider pattern: a startup flag selects which dependencies to register (LocalStack endpoints + static Postgres password OR real AWS SDK clients + IAM auth token generator). Endpoints only depend on abstractions like IDynamoDBContext and NpgsqlDataSource, so no code changes are needed when swapping providers (we’ll see the API configuration details later).
• Single repository ownership: Infrastructure and application code live together. No separate IaC repo, no coordination between teams, no deployment scripts scattered across CI/CD pipelines.
• Reduced maintenance burden: When we add a new service (e.g., SQS queue), we add it once in the CDK stack. LocalStack automatically emulates it locally; CloudFormation provisions it in production. No duplicate YAML files, no drift.
• Developer autonomy: Developers can iterate locally without AWS credentials, network access, or cloud costs. When ready, they deploy the same codebase with one command, either manually, either via CI/CD.

The cost is awareness: developers need to know that Postgres and Aurora aren’t byte-for-byte identical (e.g., Aurora-specific features won’t work locally), and that LocalStack’s emulation has limitations. But this is a manageable trade-off compared to maintaining separate infrastructure repositories or forcing developers to develop against live AWS.

The CDK Stack: AWS Infrastructure

Now that we understand the orchestration strategy and trade-offs, let’s examine how CDK provisions the actual AWS infrastructure. Remember, in publish mode, the Aspire Host hands off to SampleStack, which defines all the production resources. Here’s what gets created:

1. VPC with isolated subnets → no internet gateway, no public IPs
2. Aurora Serverless v2 cluster → auto-scaling Postgres (0.5-1 ACU)
3. RDS Proxy → connection pooling + IAM auth for Lambda
4. DynamoDB table → table with partition key
5. Lambda function → .NET 8 runtime, bundled via Docker (AWS currently supports .NET 8 as bundled runtime)
6. HTTP API Gateway → single catch-all route /{proxy+} to Lambda

The Full CDK Code

// Base stack: Shared resources used by both LocalStack (local dev) and AWS (production).
// This stack only creates resources that LocalStack can emulate (e.g., DynamoDB).
public class SampleBaseStack : Stack
{
    public Table DynamoDbTable { get; }
    
    public SampleBaseStack(Construct scope)
        : this(scope, "SampleBaseStack")
    {
    }

    protected SampleBaseStack(Construct scope, string id)
        : base(scope, id)
    {
        DynamoDbTable = new Table(this,
            "Table",
            new TableProps
            {
                TableName = "sample-records",
                PartitionKey = new Attribute
                {
                    Name = "id",
                    Type = AttributeType.STRING
                },
                RemovalPolicy = RemovalPolicy.DESTROY // Demo only - use RETAIN in production
            });
    }
}

// Production stack: Inherits shared resources, adds AWS-specific infrastructure.
// VPC, Aurora, RDS Proxy, Lambda, and API Gateway only exist in production.
public class SampleStack : SampleBaseStack
{
    public CfnOutput PgConnectionString { get; }
    public CfnOutput ApiUrl { get; }
    
    public SampleStack(Construct scope)
        : base(scope, "SampleStack")
    {
        // --- VPC: Isolated Network ---
        // PRIVATE_ISOLATED = no internet gateway, no NAT gateway, no public IPs.
        // Lambda and Aurora can only communicate within VPC or through VPC endpoints.
        // DynamoDB access via VPC endpoint (no internet traversal).
        var privateSubnets = new SubnetSelection { SubnetType = SubnetType.PRIVATE_ISOLATED };

        var vpc = new Vpc(this,
            "ClusterVPC",
            new VpcProps
            {
                MaxAzs = 2, // High availability across 2 availability zones
                VpcName = "sample-cluster-vpc",
                SubnetConfiguration =
                [
                    new SubnetConfiguration
                    {
                        Name = "private",
                        SubnetType = SubnetType.PRIVATE_ISOLATED,
                        CidrMask = 24
                    }
                ],
                // VPC Gateway Endpoint for DynamoDB: Lambda can reach DynamoDB without internet access.
                // Traffic stays within AWS network, improves security and reduces latency.
                GatewayEndpoints = new Dictionary<string, IGatewayVpcEndpointOptions>
                {
                    {
                        "DynamoDbEndpoint",
                        new GatewayVpcEndpointOptions
                        {
                            Service = GatewayVpcEndpointAwsService.DYNAMODB,
                            Subnets = [privateSubnets]
                        }
                    }
                }
            });
        
        // --- Security Groups: Firewall Rules ---
        // Separate security groups follow least-privilege principle.
        // We'll configure rules later to allow Lambda → RDS Proxy communication.
        var dbSg = new SecurityGroup(this,
            "DatabaseSecurityGroup",
            new SecurityGroupProps
            {
                SecurityGroupName = "db-sg",
                Vpc = vpc
            });
        
        var lambdaSg = new SecurityGroup(this,
            "LambdaSecurityGroup",
            new SecurityGroupProps
            {
                SecurityGroupName = "lambda-sg",
                Vpc = vpc
            });

        // --- RDS Aurora PostgreSQL Cluster ---
        // Aurora Serverless v2: Scales capacity automatically based on load (0.5-1 ACU here).
        // Pay only for what you use, ideal for variable workloads.
        const string pgUser = "lambda";
        const string? pgDatabaseName = "sample";

        var pg = new DatabaseCluster(this,
            "DatabaseCluster",
            new DatabaseClusterProps
            {
                Engine = DatabaseClusterEngine.AuroraPostgres(new AuroraPostgresClusterEngineProps
                {
                    Version = AuroraPostgresEngineVersion.VER_17_5
                }),
                Writer = ClusterInstance.ServerlessV2("SampleDatabaseClusterWriter",
                    new ServerlessV2ClusterInstanceProps
                    {
                        PubliclyAccessible = false, // Must be false for PRIVATE_ISOLATED subnets
                        EnablePerformanceInsights = false
                    }),
                ServerlessV2MinCapacity = 0.5,
                ServerlessV2MaxCapacity = 1,
                Vpc = vpc,
                VpcSubnets = privateSubnets,
                SecurityGroups = [dbSg],
                Credentials = Credentials.FromGeneratedSecret(pgUser), // Password stored in Secrets Manager
                DefaultDatabaseName = pgDatabaseName,
                EnableDataApi = true,
                RemovalPolicy = RemovalPolicy.DESTROY, // Demo only - use RETAIN in production
                DeletionProtection = false
            });

        // --- RDS Proxy: Connection Pooling + IAM Auth ---
        // Why RDS Proxy? Lambda might create many concurrent connections. Without pooling,
        // Aurora will quickly exhaust max_connections. Proxy multiplexes Lambda connections
        // into a smaller pool, prevents "too many connections" errors.
        // IAM auth eliminates password management - Lambda uses its role to authenticate.
        var pgProxy = new DatabaseProxy(this,
            "DatabaseClusterProxy",
            new DatabaseProxyProps
            {
                DbProxyName = "sample-db-proxy",
                ProxyTarget = ProxyTarget.FromCluster(pg),
                Vpc = vpc,
                VpcSubnets = privateSubnets,
                SecurityGroups = [dbSg],
                RequireTLS = true,    // Enforce encrypted connections
                IamAuth = true,       // Enable IAM database authentication (no passwords)
                Secrets = [pg.Secret!] // Proxy uses this secret to connect to Aurora
            });
        
        // Connection string points to RDS Proxy endpoint, not Aurora directly.
        // Lambda will generate IAM auth tokens at runtime (see Api/Program.cs).
        PgConnectionString = new CfnOutput(this, "DatabaseConnectionString", new CfnOutputProps
        {
            Value = $"Host={pgProxy.Endpoint};Port=5432;Username={pgUser};Database={pgDatabaseName};Ssl Mode=Require;Trust Server Certificate=true;"
        });
        
        // Security group rule: Lambda can connect to RDS Proxy on port 5432
        pgProxy.Connections.AllowFrom(lambdaSg, Port.POSTGRES, "Lambda to Proxy");

        // --- IAM Role for Lambda ---
        // Least-privilege principle: Lambda needs CloudWatch Logs, VPC networking, 
        // RDS IAM auth, and DynamoDB access. Nothing more.
        var lambdaRole = new Role(this,
            "LambdaRole",
            new RoleProps
            {
                RoleName = "sample-lambda-execution-role",
                AssumedBy = new ServicePrincipal("lambda.amazonaws.com"),
                ManagedPolicies =
                [
                    ManagedPolicy.FromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
                    ManagedPolicy.FromAwsManagedPolicyName("service-role/AWSLambdaVPCAccessExecutionRole")
                ]
            });
        
        // Grant fine-grained permissions: Lambda can generate RDS auth tokens and access DynamoDB table.
        // No wildcards, no overly broad policies.
        pgProxy.GrantConnect(lambdaRole, pgUser);
        DynamoDbTable.GrantReadWriteData(lambdaRole);
        
        // --- Lambda Function: Bundling Strategy ---
        // Build vs Runtime split: We use .NET 9 SDK to build (latest tooling, optimizations),
        // but need to deploy to .NET 8 runtime (current latest AWS Lambda support with LTS, .NET 10 will arrive January 2026).
        // The bundle-lambda.sh script runs inside a .NET 9 container to:
        // 1. Install Amazon.Lambda.Tools CLI
        // 2. Run `dotnet lambda package` with Lambda-specific settings
        // 3. Output function.zip ready for deployment
        var buildOption = new BundlingOptions
        {
            Image = Runtime.DOTNET_9.BundlingImage, // Build-time: .NET 9 SDK
            User = "root",
            OutputType = BundlingOutput.ARCHIVED,
            Command = ["/bin/bash", "bundle-lambda.sh"],
            BundlingFileAccess = BundlingFileAccess.VOLUME_COPY
        };
        
        // Find solution root (bundle-lambda.sh expects to run from solution directory)
        var solutionPath = Path.GetDirectoryName(Path.GetDirectoryName(new Projects.Api().ProjectPath)!)!;

        var lambda = new Function(this,
            "Lambda",
            new FunctionProps
            {
                FunctionName = "sample-lambda-function",
                Runtime = Runtime.DOTNET_8, // Runtime: .NET 8 (AWS Lambda support)
                Handler = "Api", // Assembly name (entry point)
                Code = Code.FromAsset(solutionPath,
                    new Amazon.CDK.AWS.S3.Assets.AssetOptions
                    {
                        Bundling = buildOption
                    }),
                Role = lambdaRole,
                Vpc = vpc,
                VpcSubnets = privateSubnets,
                SecurityGroups = [lambdaSg],
                MemorySize = 512,
                Timeout = Duration.Seconds(10),
                Environment = new Dictionary<string, string>
                {
                    // Lambda reads connection string from environment.
                    // Api/Program.cs uses this to configure Npgsql + IAM auth.
                    ["ConnectionStrings__Postgres"] = PgConnectionString.Value.ToString()!
                }
            });

        // --- API Gateway: Public HTTP Endpoint ---
        // HTTP API (v2) is simpler and cheaper than REST API (v1).
        // Catch-all route /{proxy+} forwards ALL requests to Lambda.
        // Lambda (ASP.NET Core) handles routing internally.
        var httpApi = new HttpApi(this,
            "Api",
            new HttpApiProps
            {
                ApiName = "api",
                Description = "HTTP API"
            });
        
        // Catch-all integration: API Gateway doesn't need to know about routes.
        // /{proxy+} matches /users, /products/123, etc.
        // Lambda's ASP.NET Core app handles routing via controllers/endpoints.
        httpApi.AddRoutes(new AddRoutesOptions
        {
            Path = "/{proxy+}",
            Methods = [Amazon.CDK.AWS.Apigatewayv2.HttpMethod.ANY],
            Integration = new HttpLambdaIntegration("LambdaIntegration", lambda)
        });
        
        ApiUrl = new CfnOutput(this,
            "ApiUrl",
            new CfnOutputProps
            {
                Value = httpApi.Url!,
            });
    }
}

Bundling Script Details: The bundle-lambda.sh script runs during cdk deploy. It installs Amazon.Lambda.Tools, runs dotnet lambda package with Lambda-specific optimizations, and outputs function.zip to /asset-output/. CDK uploads this zip to S3, then CloudFormation deploys it to Lambda.

Inheritance in Stacks: SampleStack inherits from SampleBaseStack. This allows us to share common resources (like the DynamoDB table) between local and production stacks, while adding production-specific resources (VPC, Aurora, Lambda, API Gateway) in the derived class. This reduces duplication and keeps shared definitions in one place. Alternatively, we can use concept of nested stacks. Nested stacks allow us to compose stacks within stacks, promoting reuse and modularity. However, for simplicity, inheritance suffices here. Nested stacks can be explored in more complex scenarios.

API Project: Environment-Aware Configuration

With the infrastructure defined, we need to make the application code aware of which environment it’s running in. The CDK stack creates the infrastructure, but the API itself needs to connect to the right services - LocalStack when running locally, real AWS when deployed.

The Program.cs adapts to its environment using a simple config flag. UseLocalStack determines whether to use emulated services or real AWS (while it is possible to use only LocalStack configuration which will automatically fallback to real AWS services, but I prefer to be explicit here). Also, the Postgres connection uses either a static password (local) or IAM auth tokens (production) via a periodic password provider.

if (builder.Configuration.GetValue("LocalStack:UseLocalStack", false))
{
    // Local: Use LocalStack endpoints and static DB password
    builder.Services.AddLocalStack(builder.Configuration);
    builder.Services.AddAWSServiceLocalStack<IAmazonDynamoDB>();
    builder.Services.AddNpgsqlDataSource(builder.Configuration.GetConnectionString("Postgres")!);
}
else
{
    // AWS: Use real AWS and IAM auth tokens for DB
    builder.Services.AddAWSService<IAmazonDynamoDB>();
    builder.Services.AddNpgsqlDataSource(builder.Configuration.GetConnectionString("Postgres")!,
        b => {
            b.UsePeriodicPasswordProvider((cs, _) =>
                ValueTask.FromResult(RDSAuthTokenGenerator.GenerateAuthToken(cs.Host, cs.Port, cs.Username)),
            TimeSpan.FromMinutes(10),  // Refresh every 10 minutes
            TimeSpan.FromSeconds(5));  // Refresh after 5 seconds in case of failure
        });
}

Why periodic password provider?

RDS Proxy with IAM authentication doesn’t use static passwords. Instead, the Lambda generates a temporary authentication token (valid for 15 minutes) signed with its IAM credentials. The RDSAuthTokenGenerator.GenerateAuthToken method creates this token on-demand using the Lambda’s IAM role.

The periodic provider automatically handles token refresh:

• Generates a fresh token every 10 minutes (before the 15-minute expiry)
• Handles token refresh transparently - application code sees a normal connection, never knows tokens are being rotated
• Eliminates secrets management entirely (no passwords stored in environment variables, config files, or secrets managers)

Locally, the Postgres container uses a static password from the connection string (simpler for development). Same application queries, different credential strategy.

Deploying to AWS

Before deploying for the first time, we need to bootstrap CDK in AWS account and region. Bootstrapping is a one-time setup that creates:

• An S3 bucket to store CloudFormation templates and Lambda deployment packages
• IAM roles that allow CloudFormation to create resources on our behalf
• An ECR repository for Docker images (if needed)

If AWS environment is set up and cdk is installed, we can just run the bootstrap command:

cdk bootstrap

We only need to run this once per account/region combination. If we deploy to multiple regions (e.g., us-east-1, eu-west-1), bootstrap each one separately.

What happens during bootstrap:

1. CDK creates a CloudFormation stack named CDKToolkit
2. An S3 bucket (named like cdk-hnb659fds-assets-ACCOUNT-REGION) is created to store deployment artifacts
3. IAM roles are created with permissions to deploy infrastructure
4. The bootstrap stack is versioned, allowing CDK to upgrade its own infrastructure over time

Important

• CDK requires cdk.json file to be present in the project root. If it is missing, it can be created with cdk init app --language csharp command and then copied to the Aspire Host project root.
• cdk.json has to contain correct app command to run the Aspire Host project to get the CDK stack. Example content: "app": "dotnet run -- --publisher manifest --output-path ./manifest.json"

As long as bootstrap is done, we can deploy the stack. One command triggers publish mode:

cdk deploy --outputs-file ./cdk-outputs.json

When we run the deployment command, here’s the step-by-step process:

1. Aspire evaluates resources in publish mode → IsPublishMode = true, so the publish branch runs
2. CDK synthesizes CloudFormation template → CDK compiles our C# infrastructure code into a CloudFormation template, saved in the cdk.out/ directory along with any assets (like Lambda zip files)
3. Lambda code is bundled → A Docker container with the .NET SDK runs bundle-lambda.sh, which builds the Api project with Lambda-specific settings and packages it into a zip file
4. CDK deploys stack → CloudFormation creates all the resources: VPC (with isolated subnets, route tables, security groups), Aurora Serverless v2 cluster (with auto-scaling capacity), RDS Proxy (with IAM auth configuration), DynamoDB table, Lambda function (uploaded from the bundled zip), and HTTP API Gateway (with routing configuration)
5. Stack outputs are displayed → After deployment completes, CDK shows the outputs we defined: ApiUrl (the public endpoint to test) and DatabaseConnectionString (for diagnostics)
6. Stack outputs saved to file → The --outputs-file option saves the outputs to cdk-outputs.json

First deployment takes 5-10 minutes, mostly waiting for the Aurora cluster to provision. Subsequent updates are much faster (30-60 seconds) because CloudFormation only updates changed resources. If we only modify Lambda code, CloudFormation just updates the function, leaving the database and VPC untouched.

After deployment, we can test the API by sending HTTP requests to the ApiUrl endpoint using Postman, curl, or a web browser.

Why This Pattern Works

• Single Language, Full Stack. Stay in C# for both application logic and infrastructure. We get IntelliSense, compile-time checks, and refactoring tools for infrastructure code - benefits we don’t get with YAML or HCL.
• Dev/Prod Parity for Services. The same service Program.cs defines both environments. Only the providers change (LocalStack vs real AWS), not the topology. This reduces the probability of “works on my machine” issues.
• Application-Centric Infrastructure. Infrastructure lives next to code. Adding a new service means: add project reference + add infra fragment in the same file. No separate IaC repo to keep in sync.
• Simplified CI/CD. One command deploys everything. PRs can bundle code + infrastructure changes atomically. No risk of “infra merged, app not deployed” or vice versa.

Current Limitations and Future Direction

Why Not “Just Aspire Deploy” Today?

Aspire (as of late 2025) doesn’t have native AWS publishers that handle:

• Building and zipping .NET projects for Lambda runtime
• Modeling AWS services with first-class abstractions
• Modeling AWS-specific constructs, RDS Proxy, VPCs, VPC endpoints, IAM roles, etc.
• Advanced deployment strategies (blue/green, canary)

AWS CDK already solves these problems. So the division of labor is:

• Aspire Orchestrates: decides mode, wires dependencies, manages service references
• CDK Provisions: synthesizes CloudFormation, bundles assets, deploys to AWS

What Could Improve

If Aspire evolves to include first-class resource abstractions for common AWS services (Aurora, DynamoDB, API Gateway, Lambda, etc.), then this pattern could simplify: fewer explicit CDK constructs, more declarative Aspire resource definitions. But we don’t need to wait for that future to ship productively today.

Good news: There’s active work happening in this space. AWS and the .NET team are collaborating on improving AWS integration with Aspire. The initiative aims to create first-class AWS resource support, native deployment primitives, and streamlined workflows - exactly the kind of improvements outlined above.

That’s where LocalStack comes in. Think of it as AWS running on our computer - S3, Lambda, DynamoDB, SQS, SNS, etc. The community edition is free and covers almost everything needed for typical development. No more spinning up separate AWS environments for each developer or dealing with resource cleanup across multiple accounts. Plus, we get faster feedback loops, can work offline, and can reset entire environment with a simple container restart.

In this article, we’ll build a practical example that many developers encounter: an API service that uploads files to Amazon S3 and serves them via static website hosting. Similar pattern appears everywhere: profile picture uploads, document storage, media galleries, etc. We’ll configure everything through .NET Aspire and LocalStack, so the same code works locally and in production without changes.

Before diving into the configuration, let’s make sure our starting point is clear. We have a .NET Aspire application with one API service. The service exposes HTTP endpoints. Our solution structure looks like this (standard Aspire layout):

- AppHost - the Aspire host project
  - Program.cs - Aspire host entry point
  - appsettings.json - Aspire host configuration file
  - other Aspire host files...
- Api
  - Program.cs - API service entry point
  - appsettings.json - API service configuration file
  - other API service files...
- ServiceDefaults - common service configuration
  - Extensions.cs - common service extensions

AppHost/Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.Api>("api")
    .WithHttpHealthCheck("/health");

await builder.Build().RunAsync();

Api/Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();

var app = builder.Build();

app.MapDefaultEndpoints();

// Health check endpoint
app.MapGet("/health", () => "Healthy");

app.Run();

Having this structure in place, we can now enhance the AppHost to integrate LocalStack and AWS services. First, we need to add the necessary Aspire LocalStack package LocalStack.Aspire.Hosting to AppHost project via NuGet. In the AppHost.csproj file this looks like this:

<PackageReference Include="LocalStack.Aspire.Hosting" />

This package includes everything: LocalStack container management, AWS CDK integration, and CloudFormation orchestration.

Next, we need to configure the AWS SDK by adding a shared AWS configuration context:

var awsConfig = builder.AddAWSSDKConfig()
    .WithProfile("default")
    .WithRegion(RegionEndpoint.EUCentral1);

The profile leverages AWS credential chains - local development can use AWS CLI profiles, while production uses IAM roles. The region specification ensures correct endpoints. We can make this more flexible with configuration:

var awsConfig = builder.AddAWSSDKConfig()
    .WithProfile(builder.Configuration["AWS:Profile"] ?? "default")
    .WithRegion(RegionEndpoint.GetBySystemName(builder.Configuration["AWS:Region"] ?? "eu-central-1"));

Next, we need to set up LocalStack itself. We’ll tell Aspire to manage a LocalStack container for us, configure its lifetime, and set logging levels for debugging:

var awsLocal = builder.AddLocalStack("aws-local", // Name of the LocalStack instance
    awsConfig: awsConfig, // Link to AWS config created above
    configureContainer: c => // Configure LocalStack container options
    {
        c.Lifetime = ContainerLifetime.Session; // Reset container on app restart
        c.DebugLevel = 1; // Enable detailed logging
        c.LogLevel = LocalStackLogLevel.Debug; // Show debug information
    });

Key settings here:

• Lifetime:
  • Session: container resets every time we restart the app (default for testing)
  • Persistent: container survives app restarts, keeping our data
• LogLevel: see exactly what’s happening with AWS calls
• DebugLevel: 1 - detailed request/response logging for troubleshooting

The persistent lifetime is important; we don’t want to recreate S3 buckets every time we restart debugging. While Session lifetime is useful for testing setups, Persistent lifetime is better for day-to-day development.

The important part here is the AppHost configuration file. AddLocalStack will use the LocalStack:UseLocalStack setting to determine whether it should run in local mode. It looks for this setting in our configuration (appsettings.json, environment variable LocalStack__UseLocalStack, etc.). So in AppHost/appsettings.json, we can add:

{
  "LocalStack": {
    "UseLocalStack": true
  }
}

Without this setting, LocalStack integration is disabled, and our services will try to connect to real AWS. This approach makes it easy to switch between local development and production without code changes.

After that, we can start defining AWS infrastructure. We can define AWS infrastructure as code and have it work with both LocalStack and real AWS. We’ll use the AWS CDK (Cloud Development Kit) for this. Think of it as a way to write our infrastructure using familiar programming languages instead of YAML or JSON. CDK lets us define AWS resources like S3 buckets, SQS queues, or Lambda functions using C# classes, complete with IntelliSense, type safety, and all the benefits of a real programming language. When we build our CDK code, it generates CloudFormation templates that AWS (or LocalStack) can deploy.

var awsStack = builder.AddAWSCDKStack("aws-stack", s => new AwsStack(s))
    .WithReference(awsConfig); // Link to AWS configuration

var awsStackOutputs = AwsStackOutputs.Create(awsStack); // Get typed access to stack outputs

AwsStack is a custom class where we define AWS resources. To define the actual infrastructure, here’s how we can create an Amazon S3 bucket with website hosting:

public sealed class AwsStack : Amazon.CDK.Stack
{
    // Expose the S3 bucket as a property for output references
    public IBucket Bucket { get; }

    public AwsStack(Constructs.Construct scope)
        : base(scope, "bucket")
    {
        // Create S3 bucket with website hosting enabled
        Bucket = new Bucket(this,
            "bucket",
            new BucketProps
            {
                BucketName = "test-data-bucket",
                WebsiteIndexDocument = "index.html" // Enable static website hosting
            });

        // Allow public read access for static website hosting
        Bucket.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps
        {
            Actions = ["s3:GetObject"], // Allow public read access to objects
            Effect = Effect.ALLOW, // Allow access
            Principals = [new AnyPrincipal()], // Anyone can access
            Resources = [Bucket.ArnForObjects("*")] // All objects in the bucket
        }));
    }
    
}

// The AwsStackOutputs class provides type-safe access to stack resources.
// Instead of handling raw strings in Program.cs, this gives compile-time validation
// and prevents typos from becoming runtime errors.
public sealed class AwsStackOutputs
{
    private readonly IResourceBuilder<IStackResource<AwsStack>> _stack;

    private AwsStackOutputs(IResourceBuilder<IStackResource<AwsStack>> stack)
    {
        _stack = stack;
    }
        
    // Output reference for the bucket name
    public StackOutputReference BucketName => _stack.GetOutput(nameof(BucketName));
    
    // Output reference for the bucket website URL
    public StackOutputReference BucketWebsiteUrl => _stack.GetOutput(nameof(BucketWebsiteUrl));

    // Factory method to create AwsStackOutputs and register outputs
    public static AwsStackOutputs Create(IResourceBuilder<IStackResource<AwsStack>> stack)
    {
        stack.AddOutput(nameof(BucketName), s => s.Bucket.BucketName);
        stack.AddOutput(nameof(BucketWebsiteUrl), s => s.Bucket.BucketWebsiteUrl);
        return new AwsStackOutputs(stack);
    }
}

The bucket configuration sets up static website hosting with public read access. The resource policy allows public access to objects while keeping the bucket itself private. Similarly, we can define other AWS resources as needed. For example, for Amazon SQS queues, we can call new Queue(this, "queue", new QueueProps { ... }) and expose outputs like QueueUrl and/or QueueArn. For Amazon DynamoDB tables, we can define new Table(this, "table", new TableProps { ... }) and expose outputs like TableName.

Once the infrastructure is defined, we can reference these resources in our services. Here’s how to configure an API service to use the Amazon S3 bucket we created:

var apiService = builder.AddProject<Projects.ApiService>("api")
    .WithHttpHealthCheck("/health")
    .WithReference(awsStack) // Reference the AWS stack for automatic configuration
    .WithEnvironment("Storage__BucketName", awsStackOutputs.BucketName) // Inject bucket name as config
    .WithEnvironment("Storage__PublicBaseUrl", awsStackOutputs.BucketWebsiteUrl); // Inject bucket URL as config

The WithEnvironment(...) calls inject these values as environment variables. Storage__BucketName becomes Storage:BucketName in our service’s configuration.

It’s also important to note that WithReference(awsStack) will automatically inject AWS resource outputs under the AWS__Resources__* configuration section, so we can access them directly as well. However, providing explicit configuration like Storage:BucketName in the service is often preferable to relying on generic output access. This approach also decouples our service configuration from the underlying infrastructure implementation, making it easier to change infrastructure without affecting service code.

Just before building the host, we need to enable LocalStack integration:

// Enable LocalStack integration for all services which reference AWS resources
builder.UseLocalStack(awsLocal);

This one line does a lot of heavy lifting. It configures all AWS resources in the application to use the specified LocalStack instance, automatically detects CloudFormation templates and CDK stacks, and handles CDK bootstrap if needed. This method scans all resources in the application and automatically configures AWS resources and projects that reference AWS resources to use LocalStack for local development. It:

• Detects all CloudFormation templates and CDK stack resources
• Creates a CDK bootstrap resource automatically if CDK stacks are present
• Configures all AWS resources to use LocalStack endpoints
• Sets up proper dependency ordering for CDK bootstrap
• Automatically configures projects that reference AWS resources
• Adds annotation tracking to prevent duplicate configuration

Here’s where it gets really interesting. When we call WithReference(awsStack) and enable LocalStack, Aspire automatically injects configuration into our services. We don’t have to manage any of this ourselves.

Our service gets all these environment variables automatically:

LocalStack Configuration (Example):

LocalStack__UseLocalStack = True
LocalStack__Config__EdgePort = 33895
LocalStack__Config__LocalStackHost = localhost
LocalStack__Config__UseLegacyPorts = False
LocalStack__Config__UseSsl = False
LocalStack__Session__AwsAccessKey = secretKey
LocalStack__Session__AwsAccessKeyId = accessKey
LocalStack__Session__AwsSessionToken = token
LocalStack__Session__RegionName = eu-central-1

AWS Resource References (Example):

AWS__Resources__ProfileBucketName = test-data-bucket
AWS__Resources__ProfileBucketWebsiteUrl = http://test-data-bucket.s3-website.localhost:33895

Application Configuration (Example):

Storage__BucketName = test-data-bucket
Storage__PublicBaseUrl = http://test-data-bucket.s3-website.localhost:33895

This maps to a equivalent JSON configuration structure:

{
  "LocalStack": {
    "UseLocalStack": true,
    "Config": {
      "EdgePort": 33895,
      "LocalStackHost": "localhost",
      "UseLegacyPorts": false,
      "UseSsl": false
    },
    "Session": {
      "AwsAccessKey": "secretKey",
      "AwsAccessKeyId": "accessKey", 
      "AwsSessionToken": "token",
      "RegionName": "eu-central-1"
    }
  },
  "AWS": {
    "Resources": {
      "ProfileBucketName": "test-data-bucket",
      "ProfileBucketWebsiteUrl": "http://test-data-bucket.s3-website.localhost:33895"
    }
  },
    "Storage": {
    "BucketName": "test-data-bucket",
    "PublicBaseUrl": "http://test-data-bucket.s3-website.localhost:33895"
  }
}

It’s also interesting that LocalStack handles URL rewriting for Amazon S3 website endpoints automatically. When we access, for example, http://test-data-bucket.s3-website.localhost:33895, LocalStack knows to route this to the correct S3 bucket in the LocalStack container. So if application code uploads an object to S3 and then constructs a URL using the bucket’s website URL, it will work seamlessly with LocalStack without any additional configuration. Similarly, we can use Amazon CloudFront in front of S3 by creating a Distribution object, and that will work with LocalStack as well.

So, after all this setup, the final version of Program.cs in our AppHost might looks like this:

using Amazon;
using Amazon.CDK.AWS.IAM;
using Amazon.CDK.AWS.S3;
using Aspire.Hosting.AWS.CDK;
using Aspire.Hosting.AWS.CloudFormation;
using Aspire.Hosting.LocalStack.Container;

var builder = DistributedApplication.CreateBuilder(args);

// AWS Resources

var awsConfig = builder.AddAWSSDKConfig()
    .WithProfile("default")
    .WithRegion(RegionEndpoint.EUCentral1);

var awsLocal = builder.AddLocalStack("aws-local",
    awsConfig: awsConfig,
    configureContainer: c =>
    {
        c.Lifetime = ContainerLifetime.Session;
        c.DebugLevel = 1;
        c.LogLevel = LocalStackLogLevel.Debug;
    });

var awsStack = builder.AddAWSCDKStack("aws-stack", s => new AwsStack(s))
    .WithReference(awsConfig);
var awsStackOutputs = AwsStackOutputs.Create(awsStack);

// Services

builder.AddProject<Projects.Api>("api")
    .WithHttpHealthCheck("/health")
    .WithReference(awsStack)
    .WithEnvironment("Storage__BucketName", awsStackOutputs.BucketName)
    .WithEnvironment("Storage__PublicBaseUrl", awsStackOutputs.BucketWebsiteUrl);

// Run

builder.UseLocalStack(awsLocal);

await builder.Build().RunAsync();

public sealed class AwsStack : Amazon.CDK.Stack
{
    public IBucket Bucket { get; }

    public AwsStack(Constructs.Construct scope)
        : base(scope, "bucket")
    {
        Bucket = new Bucket(this,
            "bucket",
            new BucketProps
            {
                BucketName = "test-data-bucket",
                WebsiteIndexDocument = "index.html" // Enable static website hosting
            });

        Bucket.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps
        {
            Actions = ["s3:GetObject"],
            Effect = Effect.ALLOW,
            Principals = [new AnyPrincipal()],
            Resources = [Bucket.ArnForObjects("*")]
        }));
    }
}

public sealed class AwsStackOutputs
{
    private readonly IResourceBuilder<IStackResource<AwsStack>> _stack;

    private AwsStackOutputs(IResourceBuilder<IStackResource<AwsStack>> stack)
    {
        _stack = stack;
    }
        
    public StackOutputReference BucketName => _stack.GetOutput(nameof(BucketName));
    
    public StackOutputReference BucketWebsiteUrl => _stack.GetOutput(nameof(BucketWebsiteUrl));

    public static AwsStackOutputs Create(IResourceBuilder<IStackResource<AwsStack>> stack)
    {
        stack.AddOutput(nameof(BucketName), s => s.Bucket.BucketName);
        stack.AddOutput(nameof(BucketWebsiteUrl), s => s.Bucket.BucketWebsiteUrl);
        return new AwsStackOutputs(stack);
    }
}

And now when we run the AppHost, Aspire will start LocalStack, deploy CDK stack to it, and inject all the necessary configuration into API service. Here is a screenshot of the Aspire dashboard showing LocalStack running and the CDK stack deployed:

Now the AppHost is configured. It’s time to set up the service itself to use the AWS SDK with LocalStack. First, add the necessary package reference to the service: LocalStack.Client, LocalStack.Client.Extensions, AWSSDK.S3. In Api.csproj file, this looks like this:

<PackageReference Include="AWSSDK.S3" />
<PackageReference Include="LocalStack.Client" />
<PackageReference Include="LocalStack.Client.Extensions" />

Then, in the API service Program.cs, we add LocalStack integration and register the S3 client:

// Configure LocalStack and AWS SDK integration
builder.Services.AddLocalStack(builder.Configuration); // Read LocalStack config from Aspire
builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions()); // Configure AWS SDK
builder.Services.AddAwsService<IAmazonS3>(); // Register S3 client with dependency injection

That’s it. The AddLocalStack(...) method reads all the configuration Aspire injected and sets up the AWS SDK to talk to LocalStack. The S3 client now points to LocalStack automatically. In addition, the AWS SDK client registration AddAwsService<IAmazonS3>() uses the configured AWS options, which now include LocalStack endpoints.

Here’s how the simple API service code looks (we have two endpoints: one for uploading files to Amazon S3 and another for downloading files from S3; this is simple test functionality to demonstrate S3 integration):

// SIMPLIFIED TESTING CODE - DO NOT USE IN PRODUCTION
// THIS IS FOR INTEGRATION DEMONSTRATION PURPOSES ONLY

using Amazon.S3;
using Amazon.S3.Model;
using LocalStack.Client.Extensions;
using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();

// Configure LocalStack and AWS SDK
builder.Services.AddLocalStack(builder.Configuration);
builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions());
builder.Services.AddAwsService<IAmazonS3>();

// Register our storage configuration
builder.Services.Configure<StorageOptions>(builder.Configuration.GetSection("Storage"));

var app = builder.Build();

app.MapDefaultEndpoints();

// Health check endpoint
app.MapGet("/health", () => "Healthy");

// Upload endpoint
app.MapPost("/upload", async (
    IFormFile file,
    IAmazonS3 s3Client,
    IOptions<StorageOptions> storageOptions) =>
{
    var bucketName = storageOptions.Value.BucketName;

    // Use original filename as S3 key for simplicity (UNSAFE for production)
    var key = file.FileName;

    // Open the input file stream
    await using var stream = file.OpenReadStream();

    // Upload the file to S3
    await s3Client.PutObjectAsync(new PutObjectRequest
    {
        BucketName = bucketName,
        Key = key,
        InputStream = stream,
        ContentType = file.ContentType
    });
    
    return Results.Ok(new
    {
        Url = new Uri(storageOptions.Value.PublicBaseUrl, key)
    });
})
// Disable antiforgery for simplicity in this example
.DisableAntiforgery();

// Download endpoint
app.MapGet("/download/{key}", async (
    string key,
    IAmazonS3 s3Client,
    IOptions<StorageOptions> storageOptions) =>
{
    var bucketName = storageOptions.Value.BucketName;

    try
    {
        var response = await s3Client.GetObjectAsync(bucketName, key);
        return Results.File(response.ResponseStream, response.Headers["Content-Type"], key);
    }
    catch (AmazonS3Exception ex) when (ex.StatusCode == System.Net.HttpStatusCode.NotFound)
    {
        return Results.NotFound();
    }
});

app.Run();

// Storage configuration class
// Maps to Storage section in configuration:
// Storage:BucketName and Storage:PublicBaseUrl
public sealed class StorageOptions
{
    public string BucketName { get; init; } = null!;
    public Uri PublicBaseUrl { get; init; } = null!;
}

The beauty here is that the LocalStack client automatically falls back to real AWS when LocalStack isn’t enabled. We don’t need conditional registration - just use AddAwsService<...>() everywhere and let the configuration decide where calls go. The LocalStack Client uses these injected settings (LocalStack__ from above, especially LocalStack__UseLocalStack) to route requests to LocalStack when enabled, or to real AWS otherwise.

So now we can run our Aspire application again and test the API service. We can use tools like Postman or curl to upload and download files. Since LocalStack is running, all Amazon S3 operations happen locally without touching real AWS. We can even use the AWS CLI to inspect the LocalStack S3 bucket. In my case it looks like this:

# Upload a file using curl
curl -v "http://localhost:22456/upload" -F "file=@index.html"
  # *   Trying 127.0.0.1:22456...
  # * Connected to localhost (127.0.0.1) port 22456 (#0)
  # > POST /upload HTTP/1.1
  # > Host: localhost:22456
  # > User-Agent: curl/7.87.0
  # > Accept: */*
  # > Content-Length: 326
  # > Content-Type: multipart/form-data; boundary=------------------------90474ff5b4693aae
  # > 
  # * We are completely uploaded and fine
  # * Mark bundle as not supporting multiuse
  # < HTTP/1.1 200 OK
  # < Content-Type: application/json; charset=utf-8
  # < Date: Wed, 02 Nov 2025 16:44:05 GMT
  # < Server: Kestrel
  # < Transfer-Encoding: chunked
  # < 
  # * Connection #0 to host localhost left intact
  # {"url":"http://test-data-bucket.s3-website.localhost:33895/index.html"}%  

# List objects in the S3 bucket using AWS CLI
aws --endpoint-url="http://localhost:33895" s3 ls s3://test-data-bucket
  # 2025-11-02 17:44:05        139 index.html

# Download the file using curl
curl -v "http://localhost:22456/download/index.html" -o downloaded_index.html

Useful links:

• LocalStack
• .NET Aspire Integrations for LocalStack
• LocalStack .NET Client
• Integrating AWS with .NET Aspire
• Working with the AWS CDK in C#
• LocalStack Provisioning Examples

In Agile teams, we’re comfortable with story points for sprint planning. We know the scope, our velocity, our capacity. Everything works more or less smoothly within two-week cycles. But management wants dates and dollars. The situation gets even more challenging when we’re standing there with nothing but a vague idea of what needs to be built, no team yet, no velocity to reference, no historical data from similar projects, just a vision, maybe few documents and wireframes, and an executive who needs an answer.

I’ve been in this situation countless times, especially in my recent presales work where I’m doing these estimations few times per week. Here’s how I handle it without giving estimates that are either wildly inaccurate or so padded they’re useless.

Let me provide a concrete imaginary example. A mid-size manufacturing company needed an inventory management system. They wanted to track raw materials, manage supplier relationships, monitor stock levels, integrate with existing systems, and generate reports for procurement teams. Sounds like a standard inventory system. But “standard” doesn’t mean simple, and it definitely doesn’t mean the scope won’t explode.

Breaking It Down

First thing, you need to break this down into “features” you can actually wrap your head around. But here’s the thing about feature breakdown - there’s a sweet spot: go too big, like “build supplier management” as a single feature, and you’re just guessing. That could be anywhere from a week to three months depending on what “supplier management” means; go too small, breaking everything down into 1-2 man-day features, and you’ve essentially reinvented waterfall - you’ll spend more time planning than building.

What works for me is thinking in terms of something between 3-5 man-days to 15-20 man-days (1-2 sprints) maximum. If I can’t estimate something within 15-20 man-days, it needs to be broken down further. Of course, I might often get features that take only 1-2 man-days, but that’s not a problem as long as I don’t need to estimate hundreds of such features - I don’t want to turn estimations into waterfall, I don’t want to have 500 very small features with estimations taking a week while still having too much uncertainty. Similarly, in opposite direction, sometimes I might estimate feature as 30+ man-days but only if I have historical data from similar activities.

Who does this breakdown? It depends on the company. Bigger ones have business analysts (aka requirement engineers) for this, but in smaller companies, it’s usually engineers doing it themselves. And that’s fine, but here’s a mistake I see constantly, engineers decomposing work into technical tasks. “Design database schema”, “Implement REST API”, “Create domain model”. However, that’s not how modern software gets built. Don’t get me wrong, these are valid tasks for individual feature breakdown during development, but it’s hard to imagine a scenario where you design the complete database for all features upfront. In the real world, you build features iteratively. You deliver business value and the database evolves as you go. So instead, think about what users can actually do: “Users can create an account and log in”, “Staff can receive and process incoming inventory shipments”, “Manager can generate reports for procurement teams”, etc.

Of course, there are exceptions. You do need to set up CI/CD pipelines. You do need to configure your infrastructure. Set up logging, monitoring, all that stuff. These are legitimate technical tasks that happen usually at the project start. Estimate them separately or as a bundle based on experience - most engineers know roughly how long their standard setup takes in their environment.

When I’m doing the breakdown myself (it happens not that often in fact due to BAs who do it in my current company), I like to think in terms of modules or functional areas first. For our inventory system: “User Management”, “Product Catalog”, “Stock Management”, “Purchase Orders”, “Supplier Management”, “Integration with ERP”, “Reporting Dashboard”, “Admin Panel”, etc. And then I break each of these down further. For example, “Stock Management” might include: “Staff can receive and process incoming inventory shipments”, “Users can view current stock levels and locations”, “Warehouse staff can move items between locations”, “Managers can adjust stock quantities for damaged or lost items”, etc. Each of these is something a user does, not something software engineer does.

Beyond Single-Point Estimates

So, you’ve got your tasks broken down. Now comes the part where most estimates go wrong - putting numbers on them. The naive approach is to slap a effort number on each task. “Staff can receive and process incoming inventory shipments? 10 man-days.” But that’s not an estimation, that’s a guess dressed up in false precision.

Here’s where PERT comes in. Instead of one effort number, you give three: optimistic, realistic, and pessimistic. Each number represents a different scenario, and thinking through all three makes your estimations way more accurate.

Back to the feature “Staff can receive and process incoming inventory shipments”:

• Optimistic scenario. Basic shipment receipt with manual entry of quantities, simple item lookup by SKU, update stock levels in database, print basic receipt. This is the “nothing goes wrong, no surprises, no scope creep” version. It almost never happens, but it could. 4 man-days of development (just an example, I don’t know the actual numbers for this feature 😜, it sounds like 1-2 days on backend and 2 days on frontend).

• Realistic scenario. Now we add barcode scanning for items, purchase order validation, discrepancy tracking when received quantities don’t match expected, quality inspection workflow, automatic supplier notifications, and proper audit trails. This is what you’ll probably actually build because these aren’t nice-to-haves, they’re essential for any real warehouse operation. 9 man-days of development (just another example estimate).

• Pessimistic scenario. Everything above plus photo documentation for damaged items and approval workflows for high-value discrepancies. This is the “everything that could reasonably be added to this feature gets added” version. 12 man-days of development (just another example estimate).

In the PERT approach, the expected effort is calculated as:

So for “Staff can receive and process incoming inventory shipments”:

Notice how it’s weighted toward the realistic estimate? That’s intentional. The optimistic and pessimistic scenarios are outliers, the realistic is what usually happens. There are variations of PERT that use different weights, but this is the most common one.

Let’s have another example. Product search.

• Optimistic scenario. Basic keyword search, filter by category, show results in a grid, add pagination. Simple, just make it work. 3 man-days of development.

• Realistic scenario. Full-text search with relevance, multiple filters that actually make sense, sorting options. 5 man-days of development.

• Pessimistic scenario. Filter dependencies, performance optimization for 100,000+ SKUs. 8 man-days of development.