| name | aspire-development |
| description | Expert guidance for .NET Aspire distributed application development. Use when adding integrations (databases, messaging, AI services), configuring AppHost orchestration, implementing service discovery, or troubleshooting Aspire applications. Emphasizes MCP tools for discovering up-to-date package information before implementation. |
| compatibility | Requires .NET Aspire workload, Aspire CLI, and network access for NuGet packages |
| metadata | {"author":"unified-ai-tracker","version":"1.0","aspire-version":"13.1.x"} |
.NET Aspire Development
This skill provides comprehensive guidance for working with .NET Aspire distributed applications, including integration discovery, implementation patterns, and troubleshooting.
When to Use This Skill
- Adding integrations: Databases, messaging systems, AI services, Azure resources
- Orchestrating services: Configuring AppHost, managing service references
- Service discovery: Implementing inter-service communication
- Container management: Working with Docker containers in Aspire
- Troubleshooting: Diagnosing Aspire application issues
Critical Principle: Fresh Information First
⚠️ LLM training data for Aspire is outdated. The framework evolves rapidly with new integrations, breaking changes, and updated patterns.
Mandatory Pre-Implementation Checklist
Before implementing ANY Aspire integration:
- ✅ Query
mcp_aspire_list_integrations to discover available integrations
- ✅ Call
mcp_aspire_get_integration_docs(packageId, version) for specific package documentation
- ✅ Verify exact package IDs and versions from MCP responses
- ✅ Review NuGet documentation URLs provided in MCP responses
- ❌ NEVER rely on cached LLM knowledge for package names, versions, or patterns
- ❌ NEVER guess or assume integration details
Tool Selection Rules
For Aspire-Specific Queries (integrations, packages, AppHost patterns):
mcp_aspire_list_integrations - List all available Aspire hosting integrationsmcp_aspire_get_integration_docs(packageId, version) - Get specific integration documentation
For General .NET Topics (C#, EF Core, ASP.NET Core, etc.):
mcp_microsoft_doc_microsoft_docs_search - Search Microsoft Learnmcp_microsoft_doc_microsoft_code_sample_search - Find code samplesmcp_microsoft_doc_microsoft_docs_fetch - Fetch complete documentation
DO NOT use Microsoft documentation tools for Aspire integration discovery.
Standard Workflow
Phase 1: Discovery & Planning
-
Identify Requirements
- Understand what integration or service is needed
- Clarify configuration requirements
-
Query Available Integrations
mcp_aspire_list_integrations
→ Review results, note package IDs
→ Filter by category (Database, Messaging, AI, etc.)
-
Fetch Integration Documentation
mcp_aspire_get_integration_docs(packageId, version)
→ Review NuGet documentation URL
→ Verify usage patterns
→ Check prerequisites and dependencies
-
Validate Compatibility
- Check version compatibility with existing packages
- Review configuration requirements
- Identify client packages needed
Phase 2: Implementation
-
Add Package to AppHost
cd unifiedaitracker.AppHost
dotnet add package <PackageId> --version <Version>
-
Configure in AppHost.cs
var resource = builder.Add<Integration>("resource-name")
.WithConfiguration()
.WithHealthCheck();
-
Add Service References
builder.AddProject<Projects.ApiService>("api")
.WithReference(resource);
-
Configure Client Services
- Add client NuGet packages to consuming projects
- Configure dependency injection
- Set up connection handling
Phase 3: Execution & Validation
-
Build Solution
dotnet build unifiedaitracker.slnx
-
Run with Aspire
aspire run --project unifiedaitracker.AppHost
-
Verify in Aspire Dashboard
- Check all services start successfully
- Verify container health
- Review connection status
- Check logs for errors
-
Test Integration
- Verify service discovery works
- Test data operations
- Validate telemetry and logs
Quick Reference: Common Operations
Running Aspire Applications
# Preferred method (from solution root)
aspire run --project unifiedaitracker.AppHost
# With specific configuration
aspire run --project unifiedaitracker.AppHost --configuration Release
# Alternative (from AppHost directory)
cd unifiedaitracker.AppHost
dotnet run
The Aspire Dashboard automatically opens (typically http://localhost:15xxx) providing:
- Real-time service status
- Container health and logs
- Distributed traces
- Metrics and telemetry
- Service dependency graph
Service Discovery Pattern
var api = builder.AddProject<Projects.ApiService>("api");
var service = builder.AddProject<Projects.Worker>("worker")
.WithReference(api);
builder.Services.AddHttpClient<IMyService, MyService>(client =>
{
client.BaseAddress = new Uri("http://api");
});
Integration Categories (Overview)
See references/INTEGRATIONS.md for the complete catalog (100+ integrations).
Major Categories:
- Databases: PostgreSQL, MySQL, MongoDB, SQL Server, Redis, Elasticsearch, etc.
- Messaging: Kafka, RabbitMQ, Azure Service Bus, NATS, etc.
- AI Services: Azure OpenAI, GitHub Models, Ollama, Cognitive Services
- Vector Databases: Milvus, Qdrant, Meilisearch
- Azure Services: Storage, Key Vault, Cosmos DB, Functions, etc.
- Language Runtimes: JavaScript/Node.js, Python, Java, Golang, Rust
- Infrastructure: Dapr, Orleans, Kubernetes, Docker
- Observability: Seq, Application Insights, OpenTelemetry
- Development Tools: Keycloak, Adminer, MailPit, etc.
Common Implementation Patterns
See references/PATTERNS.md for detailed patterns with code examples:
- Adding database integrations (with persistence and admin UI)
- Configuring Azure OpenAI
- Adding Node.js/JavaScript services
- Implementing service discovery
- Container health checks
- Environment variable configuration
Troubleshooting
See references/TROUBLESHOOTING.md for detailed solutions.
Quick Checks:
- Package not found: Verify exact package ID with
mcp_aspire_list_integrations
- Service discovery fails: Check service names match AppHost configuration
- Container won't start: Review logs in Aspire Dashboard
- Connection string issues: Verify
WithReference() calls and appsettings.json
Integration Verification Checklist
Before considering an integration complete:
Essential Commands
# Discover integrations (use MCP tool)
mcp_aspire_list_integrations
# Get integration docs (use MCP tool)
mcp_aspire_get_integration_docs(packageId, version)
# Add package
dotnet add package <PackageId> --version <Version>
# Build solution
dotnet build unifiedaitracker.slnx
# Run Aspire application
aspire run --project unifiedaitracker.AppHost
# Create new Aspire project
dotnet new aspire-apphost -n MyApp.AppHost
# Update Aspire workload
dotnet workload update
Best Practices
- Always use MCP tools for integration discovery - never rely on cached knowledge
- Use exact versions from MCP responses when adding packages
- Configure health checks for all container-based integrations
- Name resources consistently between AppHost and consuming services
- Use service discovery instead of hardcoded endpoints
- Monitor Aspire Dashboard during development for immediate feedback
- Enable telemetry to debug distributed application issues
- Persist data volumes for databases to avoid data loss during restarts
Additional Resources
- Integration Catalog: Complete list of 100+ available integrations
- Implementation Patterns: Code examples for common scenarios
- Troubleshooting Guide: Solutions for common issues
- Aspire Dashboard: Primary tool for monitoring and debugging (auto-opens on run)
- NuGet Package Pages: Official documentation URLs provided by MCP tools
Remember: The cornerstone of successful Aspire development is using MCP tools (mcp_aspire_list_integrations, mcp_aspire_get_integration_docs) to get current, accurate information before every implementation.
