DashboardConfiguration

Use AddConnection<TTransportInit>() to register a transport connection. Each connection requires a connection string and can contain multiple queues.

builder.Services.AddDotNetWorkQueueDashboard(options =>
{
    options.AddConnection<SqlServerMessageQueueInit>(
        "Server=myserver;Database=mydb;Trusted_Connection=true;",
        conn =>
        {
            conn.DisplayName = "Production SQL Server";
            conn.AddQueue("OrderQueue");
            conn.AddQueue("NotificationQueue");
        });
});

The transport init types are:

If your queues use message interceptors (compression or encryption), you must register the same interceptors on the dashboard queue so that it can decode message bodies.

conn.AddQueue("EncryptedQueue", container =>
{
    container.Register(() => new AesMessageInterceptorConfiguration(key), LifeStyles.Singleton);
    container.RegisterCollection<IMessageInterceptor>(new[]
    {
        typeof(GZipMessageInterceptor),
        typeof(AesMessageInterceptor)
    });
});

key is the same 32-byte AES key that the producers and consumers use.

Without matching interceptors, message body inspection returns encoded/encrypted data.

You can register reusable interceptor configurations by name and reference them per-queue:

builder.Services.AddDotNetWorkQueueDashboard(options =>
{
    options.AddInterceptorProfile("compressed", container =>
    {
        container.RegisterCollection<IMessageInterceptor>(new[] { typeof(GZipMessageInterceptor) });
    });

    options.AddConnection<SqlServerMessageQueueInit>(connectionString, conn =>
    {
        conn.DisplayName = "Production";
        conn.AddQueueWithProfile("CompressedQueue", "compressed");
    });
});

You can configure the built-in GZip and AES interceptors entirely from appsettings.json, without code. The Interceptors section applies to every queue in every connection:

{
  "Dashboard": {
    "Interceptors": {
      "GZip": {
        "Enabled": true,
        "MinimumSize": 150
      },
      "Aes": {
        "Enabled": true,
        "Key": "BASE64_ENCODED_32_BYTE_KEY"
      }
    },
    "Connections": [
      {
        "Transport": "SqlServer",
        "ConnectionString": "Server=myserver;Database=mydb;Trusted_Connection=true;",
        "DisplayName": "Production",
        "Queues": [ "EncryptedQueue" ]
      }
    ]
  }
}

The Interceptors:TripleDes section was removed in 0.16.0. If it is still present, the dashboard throws an InvalidOperationException at startup. See the Migration Guide.

Security warning: Do not store Key values in appsettings.json files committed to source control. Use .NET User Secrets for development and a secrets manager for production.

The priority order for interceptor configuration is: inline delegate > named profile > JSON options.

To restrict access to dashboard endpoints, set AuthorizationPolicy to the name of a registered ASP.NET Core authorization policy:

builder.Services.AddAuthorization(auth =>
{
    auth.AddPolicy("DashboardPolicy", policy =>
        policy.RequireRole("Admin"));
});

builder.Services.AddDotNetWorkQueueDashboard(options =>
{
    options.AuthorizationPolicy = "DashboardPolicy";
});

When AuthorizationPolicy is set, all dashboard controllers require the specified policy. When it is null (the default), the endpoints are open with no authorization.

To secure endpoints with an API key, set the ApiKey option:

builder.Services.AddDotNetWorkQueueDashboard(options =>
{
    options.ApiKey = "my-secret-key";
});

Security note: Never hardcode the API key in source code. Read it from an environment variable, .NET User Secrets, or a vault. Rotate the key periodically.

All requests must then include the X-Api-Key header with the matching value. When Swagger is enabled and an API key is configured, the Swagger UI includes an API key input field.

When EnableConsumerTracking is true (the default), consumers can register with the dashboard and send periodic heartbeats. The dashboard tracks active consumers per queue and prunes any that miss heartbeats.

Use the Dashboard Client package (DashboardConsumerClient) for automatic registration and heartbeat management.

The dashboard can run queue maintenance monitors (heartbeat reset, expiration cleanup, error cleanup) instead of your consumers. Enable it per queue:

conn.AddQueue("OrderQueue", hostMaintenance: true);

See Maintenance Mode for details on configuring consumers to use external maintenance.

The dashboard includes a global exception filter that maps exceptions to HTTP status codes: