mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-24 04:15:14 +00:00
refactor(aspire): flatten skill to references/, version-gate MCP tools, simplify integrations catalog
- Move all reference docs from cli/, mcp/, framework/ subfolders into references/ per agentskills.io spec - Update all cross-references in SKILL.md and reference files - Version-gate MCP tools: 9 tools in 13.1+, docs tools (list_docs/search_docs/get_doc) in 13.2+ - Simplify integrations-catalog.md to lead with MCP tool discovery (list_integrations/get_integration_docs) - Remove .vscode/mcp.json (test artifact from aspire mcp init)
This commit is contained in:
Chris McKee
@@ -8,26 +8,26 @@ Aspire emits diagnostic codes for common issues. These appear in build warnings/
|
||||
|
||||
### Standard diagnostics
|
||||
|
||||
| Code | Severity | Description |
|
||||
|---|---|---|
|
||||
| **ASPIRE001** | Warning | Resource name contains invalid characters |
|
||||
| **ASPIRE002** | Warning | Duplicate resource name detected |
|
||||
| **ASPIRE003** | Error | Missing required package reference |
|
||||
| **ASPIRE004** | Warning | Deprecated API usage |
|
||||
| **ASPIRE005** | Error | Invalid endpoint configuration |
|
||||
| **ASPIRE006** | Warning | Health check not configured for resource with `.WaitFor()` |
|
||||
| **ASPIRE007** | Warning | Container image tag not specified (using `latest`) |
|
||||
| **ASPIRE008** | Error | Circular dependency detected in resource graph |
|
||||
| Code | Severity | Description |
|
||||
| ------------- | -------- | ---------------------------------------------------------- |
|
||||
| **ASPIRE001** | Warning | Resource name contains invalid characters |
|
||||
| **ASPIRE002** | Warning | Duplicate resource name detected |
|
||||
| **ASPIRE003** | Error | Missing required package reference |
|
||||
| **ASPIRE004** | Warning | Deprecated API usage |
|
||||
| **ASPIRE005** | Error | Invalid endpoint configuration |
|
||||
| **ASPIRE006** | Warning | Health check not configured for resource with `.WaitFor()` |
|
||||
| **ASPIRE007** | Warning | Container image tag not specified (using `latest`) |
|
||||
| **ASPIRE008** | Error | Circular dependency detected in resource graph |
|
||||
|
||||
### Experimental diagnostics (ASPIREHOSTINGX*)
|
||||
### Experimental diagnostics (ASPIREHOSTINGX\*)
|
||||
|
||||
These codes indicate usage of experimental/preview APIs. They may require `#pragma warning disable` or `<NoWarn>` if you intentionally use experimental features:
|
||||
|
||||
| Code | Area |
|
||||
|---|---|
|
||||
| ASPIRE_HOSTINGX_0001–0005 | Experimental hosting APIs |
|
||||
| ASPIRE_HOSTINGX_0006–0010 | Experimental integration APIs |
|
||||
| ASPIRE_HOSTINGX_0011–0015 | Experimental deployment APIs |
|
||||
| Code | Area |
|
||||
| ------------------------- | -------------------------------- |
|
||||
| ASPIRE_HOSTINGX_0001–0005 | Experimental hosting APIs |
|
||||
| ASPIRE_HOSTINGX_0006–0010 | Experimental integration APIs |
|
||||
| ASPIRE_HOSTINGX_0011–0015 | Experimental deployment APIs |
|
||||
| ASPIRE_HOSTINGX_0016–0022 | Experimental resource model APIs |
|
||||
|
||||
To suppress experimental warnings:
|
||||
@@ -53,101 +53,101 @@ var resource = builder.AddExperimentalResource("test");
|
||||
|
||||
### Container runtime
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| "Cannot connect to Docker daemon" | Start Docker Desktop / Podman / Rancher Desktop |
|
||||
| Container fails to start | Check `docker ps -a` for exit codes; check dashboard console logs |
|
||||
| Port already in use | Another process is using the port; Aspire auto-assigns, but `targetPort` must be free on the container |
|
||||
| Container image pull fails | Check network connectivity; verify image name and tag |
|
||||
| "Permission denied" on Linux | Add user to `docker` group: `sudo usermod -aG docker $USER` |
|
||||
| Problem | Solution |
|
||||
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| "Cannot connect to Docker daemon" | Start Docker Desktop / Podman / Rancher Desktop |
|
||||
| Container fails to start | Check `docker ps -a` for exit codes; check dashboard console logs |
|
||||
| Port already in use | Another process is using the port; Aspire auto-assigns, but `targetPort` must be free on the container |
|
||||
| Container image pull fails | Check network connectivity; verify image name and tag |
|
||||
| "Permission denied" on Linux | Add user to `docker` group: `sudo usermod -aG docker $USER` |
|
||||
|
||||
### Service discovery
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| Service can't find dependency | Verify `.WithReference()` in AppHost; check env vars in dashboard |
|
||||
| Connection string is null | The reference resource name doesn't match; check `ConnectionStrings__<name>` |
|
||||
| Wrong port in service URL | Check `targetPort` vs actual service listen port |
|
||||
| Env var not set | Rebuild AppHost; verify resource name matches exactly |
|
||||
| Problem | Solution |
|
||||
| ----------------------------- | ---------------------------------------------------------------------------- |
|
||||
| Service can't find dependency | Verify `.WithReference()` in AppHost; check env vars in dashboard |
|
||||
| Connection string is null | The reference resource name doesn't match; check `ConnectionStrings__<name>` |
|
||||
| Wrong port in service URL | Check `targetPort` vs actual service listen port |
|
||||
| Env var not set | Rebuild AppHost; verify resource name matches exactly |
|
||||
|
||||
### Python workloads
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| "Python not found" | Ensure Python is on PATH; specify full path in `AddPythonApp()` |
|
||||
| venv not found | Use `.WithVirtualEnvironment()` or create venv manually |
|
||||
| pip packages fail to install | Use `.WithPipPackages()` or install in venv before `aspire run` |
|
||||
| ModuleNotFoundError | venv isn't activated; `.WithVirtualEnvironment()` handles this |
|
||||
| "Port already in use" for Uvicorn | Check `targetPort` — another instance may be running |
|
||||
| Problem | Solution |
|
||||
| --------------------------------- | --------------------------------------------------------------- |
|
||||
| "Python not found" | Ensure Python is on PATH; specify full path in `AddPythonApp()` |
|
||||
| venv not found | Use `.WithVirtualEnvironment()` or create venv manually |
|
||||
| pip packages fail to install | Use `.WithPipPackages()` or install in venv before `aspire run` |
|
||||
| ModuleNotFoundError | venv isn't activated; `.WithVirtualEnvironment()` handles this |
|
||||
| "Port already in use" for Uvicorn | Check `targetPort` — another instance may be running |
|
||||
|
||||
### JavaScript / TypeScript workloads
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| "node_modules not found" | Use `.WithNpmPackageInstallation()` to auto-install |
|
||||
| npm install fails | Check `package.json` is valid; check npm registry connectivity |
|
||||
| Vite dev server won't start | Verify `vite` is in devDependencies; check Vite config |
|
||||
| Port mismatch | Ensure `targetPort` matches the port in your JS framework config |
|
||||
| TypeScript compilation errors | These happen in the service, not Aspire — check service logs |
|
||||
| Problem | Solution |
|
||||
| ----------------------------- | ---------------------------------------------------------------- |
|
||||
| "node_modules not found" | Use `.WithNpmPackageInstallation()` to auto-install |
|
||||
| npm install fails | Check `package.json` is valid; check npm registry connectivity |
|
||||
| Vite dev server won't start | Verify `vite` is in devDependencies; check Vite config |
|
||||
| Port mismatch | Ensure `targetPort` matches the port in your JS framework config |
|
||||
| TypeScript compilation errors | These happen in the service, not Aspire — check service logs |
|
||||
|
||||
### Go workloads
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| "go not found" | Ensure Go is installed and on PATH |
|
||||
| Build fails | Check `go.mod` exists in working directory |
|
||||
| Problem | Solution |
|
||||
| -------------------------- | ---------------------------------------------------------- |
|
||||
| "go not found" | Ensure Go is installed and on PATH |
|
||||
| Build fails | Check `go.mod` exists in working directory |
|
||||
| "no Go files in directory" | Verify `workingDir` points to the directory with `main.go` |
|
||||
|
||||
### Java workloads
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| "java not found" | Ensure JDK is installed and `JAVA_HOME` is set |
|
||||
| Problem | Solution |
|
||||
| ------------------------ | ------------------------------------------------------- |
|
||||
| "java not found" | Ensure JDK is installed and `JAVA_HOME` is set |
|
||||
| Maven/Gradle build fails | Verify build files exist; check build tool installation |
|
||||
| Spring Boot won't start | Check `application.properties`; verify main class |
|
||||
| Spring Boot won't start | Check `application.properties`; verify main class |
|
||||
|
||||
### Rust workloads
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| "cargo not found" | Install Rust via rustup |
|
||||
| Problem | Solution |
|
||||
| -------------------- | -------------------------------------------------------------------- |
|
||||
| "cargo not found" | Install Rust via rustup |
|
||||
| Build takes too long | Rust compile times are normal; use `.WithCargoBuild()` for pre-build |
|
||||
|
||||
### Health checks & startup
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| Resource stuck in "Starting" | Health check endpoint not responding; check service logs |
|
||||
| `.WaitFor()` timeout | Increase timeout or fix health endpoint; default is 30 seconds |
|
||||
| Health check always fails | Verify endpoint path (default: `/health`); check service binds to correct port |
|
||||
| Cascading startup failures | A dependency failed; check the root resource first |
|
||||
| Problem | Solution |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------ |
|
||||
| Resource stuck in "Starting" | Health check endpoint not responding; check service logs |
|
||||
| `.WaitFor()` timeout | Increase timeout or fix health endpoint; default is 30 seconds |
|
||||
| Health check always fails | Verify endpoint path (default: `/health`); check service binds to correct port |
|
||||
| Cascading startup failures | A dependency failed; check the root resource first |
|
||||
|
||||
### Dashboard
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| Dashboard doesn't open | Check terminal for URL; use `--dashboard-port` for fixed port |
|
||||
| No logs appearing | Service may not be writing to stdout/stderr; check console output |
|
||||
| No traces for non-.NET services | Configure OpenTelemetry SDK in the service; see [Dashboard](dashboard.md) |
|
||||
| Traces don't show cross-service calls | Propagate trace context headers (`traceparent`, `tracestate`) |
|
||||
| Problem | Solution |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Dashboard doesn't open | Check terminal for URL; use `--dashboard-port` for fixed port |
|
||||
| No logs appearing | Service may not be writing to stdout/stderr; check console output |
|
||||
| No traces for non-.NET services | Configure OpenTelemetry SDK in the service; see [Dashboard](dashboard.md) |
|
||||
| Traces don't show cross-service calls | Propagate trace context headers (`traceparent`, `tracestate`) |
|
||||
|
||||
### Build & configuration
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| "Project not found" for `AddProject<T>()` | Ensure `.csproj` is in the solution and referenced by AppHost |
|
||||
| Package version conflicts | Pin all Aspire packages to the same version |
|
||||
| AppHost won't build | Check `Aspire.AppHost.Sdk` is in the project; run `dotnet restore` |
|
||||
| `aspire run` build error | Fix the build error first; `aspire run` requires a successful build |
|
||||
| Problem | Solution |
|
||||
| ----------------------------------------- | ------------------------------------------------------------------- |
|
||||
| "Project not found" for `AddProject<T>()` | Ensure `.csproj` is in the solution and referenced by AppHost |
|
||||
| Package version conflicts | Pin all Aspire packages to the same version |
|
||||
| AppHost won't build | Check `Aspire.AppHost.Sdk` is in the project; run `dotnet restore` |
|
||||
| `aspire run` build error | Fix the build error first; `aspire run` requires a successful build |
|
||||
|
||||
### Deployment
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| `aspire publish` fails | Check publisher package is installed (e.g., `Aspire.Hosting.Docker`) |
|
||||
| Generated Bicep has errors | Check for unsupported resource configurations |
|
||||
| Container image push fails | Verify registry credentials and permissions |
|
||||
| Missing connection strings in deployment | Check generated ConfigMaps/Secrets match resource names |
|
||||
| Problem | Solution |
|
||||
| ---------------------------------------- | -------------------------------------------------------------------- |
|
||||
| `aspire publish` fails | Check publisher package is installed (e.g., `Aspire.Hosting.Docker`) |
|
||||
| Generated Bicep has errors | Check for unsupported resource configurations |
|
||||
| Container image push fails | Verify registry credentials and permissions |
|
||||
| Missing connection strings in deployment | Check generated ConfigMaps/Secrets match resource names |
|
||||
|
||||
---
|
||||
|
||||
@@ -172,6 +172,7 @@ If services fail to start, check the dependency order. A failed dependency block
|
||||
### 5. Use MCP for AI-assisted debugging
|
||||
|
||||
If MCP is configured (see [MCP Server](mcp-server.md)), ask your AI assistant:
|
||||
|
||||
- "What resources are failing?"
|
||||
- "Show me the logs for [service]"
|
||||
- "What traces show errors?"
|
||||
@@ -184,10 +185,10 @@ Run just the failing resource by commenting out others in the AppHost. This narr
|
||||
|
||||
## Getting help
|
||||
|
||||
| Channel | URL |
|
||||
|---|---|
|
||||
| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues |
|
||||
| GitHub Issues (docs) | https://github.com/microsoft/aspire.dev/issues |
|
||||
| Discord | https://aka.ms/aspire/discord |
|
||||
| Stack Overflow | Tag: `dotnet-aspire` |
|
||||
| Reddit | r/dotnet |
|
||||
| Channel | URL |
|
||||
| ----------------------- | ---------------------------------------------- |
|
||||
| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues |
|
||||
| GitHub Issues (docs) | https://github.com/microsoft/aspire.dev/issues |
|
||||
| Discord | https://aka.ms/aspire/discord |
|
||||
| Stack Overflow | Tag: `dotnet-aspire` |
|
||||
| Reddit | https://www.reddit.com/r/aspiredotdev/ |
|
||||
|
||||
Reference in New Issue
Block a user