QueueView.Hosting 1.0.0

QueueView

An Aspire hosting extension for viewing Azure ServiceBus queues.

What is QueueView?

QueueView is NOT a standalone application. It's an Aspire plugin that adds a web-based queue viewer to any Azure ServiceBus resource in your Aspire application. Simply call .WithQueueView() on your ServiceBus resource and get instant visibility into your queues!

Features

• 🔌 Plug & Play - Add .WithQueueView() to any ServiceBus resource
• 📊 Queue Overview - See all queues with active and total message counts
• 🔍 Message Inspection - Browse recent messages from the queue
• 💅 Smart Formatting - Auto-detect and pretty-print JSON message bodies
• 📋 Complete Details - View all message properties (MessageId, SequenceNumber, EnqueuedTime, Subject, ContentType, Properties)
• 🎨 Modern UI - Clean interface built with React and Tailwind CSS
• 🔗 Integrated - Appears in Aspire dashboard with automatic connection string handling

Quick Start

1. Install QueueView NuGet Package

dotnet add package QueueView.Hosting

Or add to your AppHost project:

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

2. Use the Extension

In your AppHost's Program.cs:

using Aspire.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("servicebus")
    .WithQueueView();  // Simple! No type parameter needed

builder.Build().Run();

3. Configure Authentication

QueueView supports two authentication methods:

Option A: Connection String (Development)

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

Option B: Managed Identity / RBAC (Production - Recommended)

# Configure namespace instead of connection string
dotnet user-secrets set "servicebus:fullyQualifiedNamespace" "your-namespace.servicebus.windows.net" --project YourApp.AppHost

# Ensure your identity has Azure Service Bus Data Owner role
# For local dev: az login
# For production: Enable Managed Identity and assign RBAC roles

See AUTHENTICATION.md for detailed setup and production deployment.

4. Run and View

dotnet run --project YourApp.AppHost

The QueueView interface will appear in your Aspire dashboard as servicebus-viewer. Click it to open the queue viewer!

Project Structure

QueueView/
├── src/
│   ├── QueueView.Hosting/         # Extension methods library
│   │   └── QueueViewExtensions.cs # .WithQueueView() extension
│   │
│   └── QueueView.Viewer/          # Web viewer application
│       ├── Models/                # DTOs
│       ├── Services/              # ServiceBus integration
│       ├── Program.cs             # API endpoints
│       └── wwwroot/               # React frontend (built)
│
├── frontend/                      # React source code
│   ├── src/
│   │   ├── components/           # React components
│   │   └── services/             # API client (using fetch)
│   └── package.json
│
└── samples/
    └── SampleApp.AppHost/         # Example usage

API Endpoints

The QueueView.Viewer exposes these endpoints:

• GET /api/queues - List all queues with message counts

  [
    {
      "name": "orders",
      "activeMessageCount": 42,
      "totalMessageCount": 150
    }
  ]
  

• GET /api/queues/{queueName}/messages?limit=20 - Get recent messages

  {
    "messages": [...]
  }
  

  Note: Returns the first limit messages (default 20, max 100). Pagination is not supported due to ServiceBus emulator limitations with message counts.

Advanced Usage

Custom Viewer Name

var serviceBus = builder.AddAzureServiceBus("orders-bus")
    .WithQueueView("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("notifications-viewer");

Development

Frontend Development

For active development with hot reload:

cd frontend
npm run dev

The Vite dev server proxies API requests to the running Viewer backend.

Building Locally

See BUILD.md for detailed build instructions.

Publishing

Publishing is automated on push to master. See QUICKSTART.md for maintainers.

How It Works

1. Extension Method: .WithQueueView() is an extension method on IResourceBuilder<AzureServiceBusResource>
2. Container Launch: Pulls and launches the QueueView viewer Docker container
3. Connection Injection: Passes the ServiceBus connection string to the viewer container via .WithReference()
4. Dashboard Integration: Exposes HTTP endpoints so the viewer appears in the Aspire dashboard
5. Zero Configuration: The viewer automatically connects to the ServiceBus and starts serving requests

Technical Details

• Backend: ASP.NET Core 9 minimal API
• Frontend: React 18 with TypeScript
• Styling: Tailwind CSS 3
• Data Fetching: TanStack Query (React Query)
• HTTP Client: Native fetch API (no axios!)
• ServiceBus Client: Azure.Messaging.ServiceBus 7.20+
• Authentication: Azure.Identity with DefaultAzureCredential (supports connection strings, Managed Identity, RBAC, Azure CLI, etc.)
• Aspire: .NET Aspire 13.1+

Architecture Decisions

Why Not a Standalone App?

QueueView is designed as an Aspire extension to:

• ✅ Integrate seamlessly with existing Aspire apps
• ✅ Automatically receive connection strings from ServiceBus resources
• ✅ Appear alongside other services in the Aspire dashboard
• ✅ Leverage Aspire's orchestration and service discovery
• ✅ Require zero manual configuration

Why Peek vs. Receive?

QueueView uses peeking to view messages non-destructively. This means:

• ✅ Messages stay in the queue
• ✅ No impact on message processing
• ✅ Safe for production use
• ⚠️ Limited to viewing message content and properties (no dead-lettering, resubmission, etc.)

Why No Pagination?

QueueView shows a limited number of recent messages without pagination because:

• The Azure ServiceBus emulator doesn't provide accurate ActiveMessageCount values
• Without reliable message counts, calculating total pages is not possible
• Peeking messages is sequential - you must peek through all earlier messages to reach later ones
• This design focuses on quick inspection of recent queue activity rather than exhaustive browsing

Why Docker Container?

QueueView is distributed as a Docker container because:

• ✅ Lightweight NuGet package (just orchestration code, no viewer source)
• ✅ Viewer can be updated independently of the hosting package
• ✅ No project references needed - just install the NuGet package
• ✅ Follows Aspire container patterns
• ✅ Simple distribution and deployment

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 🚀