QueueView.Hosting 1.0.1

QueueView

An Aspire hosting extension for viewing Azure ServiceBus queues.

What is QueueView?

QueueView is an Aspire plugin that adds a web-based queue viewer to Azure ServiceBus resources. Call .WithQueueView() on any ServiceBus resource to add queue inspection capabilities to your Aspire dashboard.

Usage

Install the NuGet Package

dotnet add package QueueView.Hosting

Or add to your AppHost project:

<ItemGroup>
  <PackageReference Include="QueueView.Hosting" Version="1.0.0" />
</ItemGroup>

Add to Your ServiceBus Resource

In your AppHost's Program.cs:

using Aspire.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("servicebus")
    .WithQueueView();

builder.Build().Run();

Configure ServiceBus Connection

QueueView supports connection strings and managed identity:

Connection String (Development)

dotnet user-secrets set "ConnectionStrings:servicebus" "YOUR_CONNECTION_STRING" --project YourApp.AppHost

Managed Identity / RBAC (Production)

dotnet user-secrets set "servicebus:fullyQualifiedNamespace" "your-namespace.servicebus.windows.net" --project YourApp.AppHost

For production, ensure your identity has the Azure Service Bus Data Owner role assigned.

Run Your Application

dotnet run --project YourApp.AppHost

The viewer appears in your Aspire dashboard as {serviceBusName}-viewer. Click it to browse queues and messages.

Project Structure

QueueView/
├── src/
│   ├── QueueView.Hosting/         # Extension methods library
│   │   └── QueueViewExtensions.cs
│   │
│   └── QueueView.Viewer/          # Containerized viewer
│       ├── Endpoints/             # FastEndpoints API
│       ├── Models/                # DTOs
│       ├── Services/              # ServiceBus client
│       ├── Program.cs
│       ├── Dockerfile
│       └── wwwroot/               # Built React frontend
│
├── frontend/                      # React source
│   ├── src/
│   │   ├── components/
│   │   └── services/
│   └── package.json
│
├── samples/
│   └── SampleApp.AppHost/
│
└── tests/
    └── QueueView.Tests/

API Endpoints

The viewer exposes two FastEndpoints:

GET /api/queues

Lists all queues in the ServiceBus namespace:

[
  { "name": "orders" },
  { "name": "notifications" }
]

GET /api/queues/{queueName}/messages?limit=20

Peeks messages from a queue (non-destructive):

{
  "messages": [
    {
      "messageId": "abc123",
      "sequenceNumber": 1234567,
      "enqueuedTime": "2024-01-23T12:00:00Z",
      "subject": "Order.Created",
      "contentType": "application/json",
      "body": "{\"orderId\":\"12345\"}",
      "properties": {}
    }
  ]
}

The limit parameter defaults to 20, maximum 100. Pagination is not supported.

Advanced Usage

Custom Viewer Name

var serviceBus = builder.AddAzureServiceBus("orders-bus")
    .WithQueueView(viewerName: "orders-viewer");

Custom Image Tag

var serviceBus = builder.AddAzureServiceBus("servicebus")
    .WithQueueView(imageTag: "1.0.0");

Multiple ServiceBus Instances

var ordersBus = builder.AddAzureServiceBus("orders")
    .WithQueueView();

var notificationsBus = builder.AddAzureServiceBus("notifications")
    .WithQueueView(viewerName: "notifications-viewer");

Development

Frontend Development

Run the frontend dev server with hot reload:

cd frontend
npm install
npm run dev

The Vite dev server will proxy API requests to http://localhost:5000 (the viewer backend).

Building the Docker Image

Use the provided build script:

./build-docker.sh dev

This script:

1. Builds the React frontend
2. Copies built files to src/QueueView.Viewer/wwwroot
3. Builds the Docker image
4. Tags it as queueview-viewer:dev and queueview-viewer:latest

Publishing

Docker images are automatically published to GitHub Container Registry on push to master.

How It Works

1. .WithQueueView() is an extension method on IResourceBuilder<AzureServiceBusResource>
2. Launches a containerized viewer using .AddContainer()
3. Passes the ServiceBus connection to the container via .WithReference()
4. Viewer appears in the Aspire dashboard with HTTP endpoints exposed
5. Viewer auto-detects the connection configuration and connects to ServiceBus

Technical Stack

• Backend: ASP.NET Core 10, FastEndpoints
• Frontend: React 19 with TypeScript, Vite
• Styling: Tailwind CSS 3
• Data Fetching: TanStack Query v5
• HTTP Client: Native fetch API
• ServiceBus Client: Azure.Messaging.ServiceBus 7.20
• Authentication: Azure.Identity with DefaultAzureCredential
• Aspire: .NET Aspire 13.1

Architecture Notes

Aspire Extension Pattern

QueueView is an Aspire hosting extension, not a standalone application. This allows it to integrate with Aspire's orchestration, automatically receive connection configurations via .WithReference(), and appear in the Aspire dashboard alongside other resources.

Non-Destructive Message Viewing

QueueView uses ServiceBus peek operations to view messages without removing them from queues. Messages remain available for normal processing. This limits functionality to read-only inspection - no dead-lettering or resubmission operations.

No Pagination

The viewer displays a limited set of recent messages (configurable, default 20, max 100) without pagination. ServiceBus peek operations are sequential, and the emulator doesn't provide reliable message counts for calculating pages. This design focuses on quick inspection rather than exhaustive browsing.

Container Distribution

The viewer is distributed as a Docker container. The NuGet package (QueueView.Hosting) contains only the extension method and container orchestration code. This keeps the package lightweight and allows the viewer to be updated independently.

Roadmap

Future enhancements:

• Message resubmit / dead-letter operations
• Support for Topics and Subscriptions
• Message search and filtering
• Export messages to JSON/CSV
• Real-time updates with SignalR
• Package as NuGet with container image
• Support for other message brokers (RabbitMQ, Kafka)

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure tests pass and build succeeds
5. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

Built with:

• .NET Aspire
• Azure ServiceBus
• React
• Tailwind CSS
• TanStack Query

fetch is all you need 🚀