Inngest.NET 1.4.5

Inngest.NET

A .NET SDK for Inngest, a platform for building reliable, scalable event-driven workflows.

Features

• Attribute-based functions: Define functions using familiar .NET patterns with attributes
• Full dependency injection: Constructor injection with scoped services per function invocation
• Durable execution: Steps automatically retry and resume from failures
• Step primitives: Run, Sleep, SleepUntil, WaitForEvent, Invoke, SendEvent
• Flow control: Concurrency, rate limiting, throttling, debounce, batching
• Full observability: Built-in logging with ILogger support

Installation

dotnet add package Inngest.NET

Quick Start

1. Configure Inngest in Program.cs

using Inngest;

var builder = WebApplication.CreateBuilder(args);

// Add Inngest with configuration and auto-discover functions
builder.Services
    .AddInngest(options =>
    {
        options.AppId = "my-app";
        options.IsDev = true; // Use Inngest Dev Server
    })
    .AddFunctionsFromAssembly(typeof(Program).Assembly);

var app = builder.Build();

// Mount the Inngest endpoint
app.UseInngest("/api/inngest");

app.Run();

2. Create a Function

using Inngest;
using Inngest.Attributes;

[InngestFunction("process-order", Name = "Process Order")]
[EventTrigger("shop/order.created")]
[Retry(Attempts = 5)]
public class OrderProcessor : IInngestFunction
{
    private readonly IOrderService _orderService;
    private readonly ILogger<OrderProcessor> _logger;

    // Constructor injection - services are scoped per function invocation
    public OrderProcessor(IOrderService orderService, ILogger<OrderProcessor> logger)
    {
        _orderService = orderService;
        _logger = logger;
    }

    public async Task<object?> ExecuteAsync(InngestContext context, CancellationToken cancellationToken)
    {
        // Step 1: Validate order (memoized - runs once, replays on retries)
        var order = await context.Step.Run("validate-order", async () =>
        {
            _logger.LogInformation("Validating order");
            return await _orderService.ValidateAsync(context.Event.Data);
        });

        // Step 2: Sleep for 5 minutes (durable - survives restarts)
        await context.Step.Sleep("wait-for-processing", TimeSpan.FromMinutes(5));

        // Step 3: Process payment
        var payment = await context.Step.Run("process-payment", async () =>
        {
            return await _orderService.ProcessPaymentAsync(order.Id);
        });

        return new { status = "completed", orderId = order.Id };
    }
}

3. Strongly-Typed Events (No Magic Strings!)

Define events that know their own name using IInngestEventData:

// Event definition - the event name lives with the event type
public record OrderCreatedEvent : IInngestEventData
{
    public static string EventName => "shop/order.created";

    public required string OrderId { get; init; }
    public required decimal Amount { get; init; }
    public required string CustomerId { get; init; }
}

// Function - NO [EventTrigger] needed! Trigger auto-derived from OrderCreatedEvent.EventName
[InngestFunction("order-handler", Name = "Order Handler")]
public class OrderHandler : IInngestFunction<OrderCreatedEvent>
{
    public async Task<object?> ExecuteAsync(
        InngestContext<OrderCreatedEvent> context,
        CancellationToken cancellationToken)
    {
        // Fully typed event data - no nulls, no magic strings
        var eventData = context.Event.Data!;

        await context.Step.Run("process", () =>
        {
            Console.WriteLine($"Order {eventData.OrderId} for ${eventData.Amount}");
            return true;
        });

        return new { processed = true };
    }
}

// Sending events - type-safe, event name derived automatically
await inngestClient.SendAsync(new OrderCreatedEvent
{
    OrderId = "123",
    Amount = 99.99m,
    CustomerId = "cust-456"
});

Function Attributes

InngestFunction

Marks a class as an Inngest function:

[InngestFunction("my-function-id", Name = "Human Readable Name")]

EventTrigger

Triggers the function when a specific event is received:

[EventTrigger("user/signed.up")]
[EventTrigger("user/invited", Expression = "event.data.role == 'admin'")] // With filter

CronTrigger

Triggers the function on a schedule:

[CronTrigger("0 0 * * *")]  // Every day at midnight
[CronTrigger("*/30 * * * *")]  // Every 30 minutes

Retry

Configures retry behavior:

[Retry(Attempts = 5)]

Concurrency

Limits concurrent executions:

[Concurrency(5)]  // Max 5 concurrent executions
[Concurrency(1, Key = "event.data.userId")]  // Per-user concurrency

RateLimit

Limits execution rate:

[RateLimit(100, Period = "1h")]  // 100 per hour
[RateLimit(10, Period = "1m", Key = "event.data.customerId")]  // Per-customer

Configuration

Using Options Pattern

// appsettings.json
{
  "Inngest": {
    "AppId": "my-app",
    "EventKey": "your-event-key",
    "SigningKey": "your-signing-key",
    "DisableCronTriggersInDev": true  // Optional: prevent cron jobs locally
  }
}

// Program.cs
builder.Services
    .AddInngest(builder.Configuration.GetSection("Inngest"))
    .AddFunctionsFromAssembly(typeof(Program).Assembly);

Using Action Configuration

builder.Services
    .AddInngest(options =>
    {
        options.AppId = "my-app";
        options.EventKey = "your-event-key";
        options.SigningKey = "your-signing-key";
        options.IsDev = builder.Environment.IsDevelopment();
        options.DisableCronTriggersInDev = true; // Prevent cron jobs from running locally
    })
    .AddFunction<OrderProcessor>()
    .AddFunction<EmailSender>();

Environment Variables

Sending Events

Strongly-Typed Events (Recommended)

// Define your event with IInngestEventData
public record OrderCreatedEvent : IInngestEventData
{
    public static string EventName => "shop/order.created";
    public required string OrderId { get; init; }
    public required decimal Amount { get; init; }
}

// Send with full type safety - no magic strings!
public class OrderController : ControllerBase
{
    private readonly IInngestClient _inngest;

    public OrderController(IInngestClient inngest) => _inngest = inngest;

    [HttpPost]
    public async Task<IActionResult> CreateOrder(Order order)
    {
        // Strongly-typed - event name derived from OrderCreatedEvent.EventName
        await _inngest.SendAsync(new OrderCreatedEvent
        {
            OrderId = order.Id,
            Amount = order.Total
        });

        // With additional configuration
        await _inngest.SendAsync(new OrderCreatedEvent
        {
            OrderId = order.Id,
            Amount = order.Total
        }, evt => evt.WithIdempotencyKey($"order-{order.Id}"));

        return Ok();
    }
}

Untyped Events (Legacy)

// Simple event with magic string
await _inngest.SendEventAsync("shop/order.created", new {
    orderId = order.Id,
    amount = order.Total
});

// Event with metadata
var evt = new InngestEvent("shop/order.created", new { orderId = order.Id })
    .WithUser(new { id = order.CustomerId })
    .WithIdempotencyKey($"order-{order.Id}");

await _inngest.SendEventAsync(evt);

Step Primitives

step.Run - Execute code with automatic retry

var result = await context.Step.Run("fetch-user", async () =>
{
    var user = await userService.GetUserAsync(userId);
    return user;
});

// Synchronous version
var value = await context.Step.Run("compute", () => ComputeValue());

step.Sleep - Pause execution

// Sleep for a duration
await context.Step.Sleep("wait", TimeSpan.FromHours(1));

// Sleep using Inngest time string format
await context.Step.Sleep("wait", "30m");  // 30 minutes
await context.Step.Sleep("wait", "2h30m"); // 2.5 hours

step.SleepUntil - Sleep until a specific time

var targetTime = DateTimeOffset.UtcNow.AddDays(1);
await context.Step.SleepUntil("wait-until-tomorrow", targetTime);

step.WaitForEvent - Wait for another event

var payment = await context.Step.WaitForEvent<PaymentData>(
    "wait-payment",
    new WaitForEventOptions
    {
        Event = "payment/completed",
        Timeout = "24h",
        Match = "async.data.orderId == event.data.orderId"
    });

if (payment == null)
{
    // Timeout occurred
    await context.Step.Run("handle-timeout", () => CancelOrder());
}

step.Invoke - Call another Inngest function

var result = await context.Step.Invoke<ProcessResult>(
    "process-payment",
    new InvokeOptions
    {
        FunctionId = "my-app-payment-processor",
        Data = new { amount = 100, currency = "USD" },
        Timeout = "5m"
    });

step.SendEvent - Emit events from within a function

await context.Step.SendEvent("notify-team", new InngestEvent(
    "notification/send",
    new { message = "Order completed!", channel = "slack" }
));

Error Handling

Non-Retriable Errors

await context.Step.Run("validate", () =>
{
    if (!IsValid(data))
    {
        // This error won't be retried
        throw new NonRetriableException("Invalid data format");
    }
    return data;
});

Retry-After Errors

await context.Step.Run("call-api", async () =>
{
    var response = await client.GetAsync(url);
    if (response.StatusCode == HttpStatusCode.TooManyRequests)
    {
        // Retry after the specified time
        throw new RetryAfterException(TimeSpan.FromMinutes(5));
    }
    return await response.Content.ReadAsStringAsync();
});

Running Locally

Prerequisites

• .NET 8.0 SDK or later
• Node.js (for running the Inngest Dev Server via npx)

Option A: Auto-Discovery with -u Flag (Recommended)

This approach tells the Dev Server where to find your app, enabling automatic function discovery.

Terminal 1 - Start your .NET app first:

dotnet run --project YourProject

Terminal 2 - Start the Dev Server pointing to your app:

npx inngest-cli@latest dev -u http://localhost:5000/api/inngest

The Dev Server will automatically discover and sync your functions.

Option B: Manual Registration

If you prefer to start the Dev Server first:

Terminal 1 - Start the Dev Server:

npx inngest-cli@latest dev --no-discovery

Terminal 2 - Start your .NET app:

dotnet run --project YourProject

The --no-discovery flag prevents auto-discovery. Your app will register its functions when it starts.

Note: Leave both terminals running during development.

Access the Dev Server UI

Open your browser to http://localhost:8288 to:

• View all registered functions
• Send test events to trigger functions
• Monitor function executions in real-time
• Inspect step-by-step execution and retries
• Debug failures and view logs

Environment Variables for Local Development

For local development, you typically don't need to set any environment variables. The SDK auto-detects the Dev Server.

To explicitly configure the Dev Server URL:

export INNGEST_DEV=http://localhost:8288

Troubleshooting

License

MIT