Skip to content

Commit 2f025d8

Browse files
davidfowlCopilot
davidfowl
and
Copilot
authored
Add hosting integration authoring skill (#1433)
* Add hosting integration authoring skill Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Enrich hosting skill with Toolkit patterns Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Trim hosting integration creator agent Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent d8c5674 commit 2f025d8

33 files changed

Lines changed: 3421 additions & 589 deletions

‎.agents/skills/hosting-integration-authoring/SKILL.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: hosting-integration-authoring
3+
description: Guides authoring and reviewing CommunityToolkit Aspire.Hosting integration APIs. Classifies integration archetypes, then applies self-contained best practices for naming, resource shape, run/publish/deploy behavior, eventing, connection properties, security, endpoint semantics, polyglot exports, READMEs, and tests.
4+
---
5+
6+
# Aspire hosting integration authoring
7+
8+
Use this skill when creating, modifying, or reviewing `CommunityToolkit.Aspire.Hosting.*` hosting integration packages and related `Aspire.Hosting.*` APIs.
9+
10+
This skill is self-contained. The resource files in this skill are the authoritative guidance, and repository paths are examples of existing patterns only.
11+
12+
## First step: classify the integration
13+
14+
Read `resources/selector-matrix.md` first. Then read `resources/app-model-fundamentals.md` for the app model rules that apply to every hosting integration. Classify the work across all four axes:
15+
16+
1. Resource shape.
17+
2. Lifecycle mode.
18+
3. Integration role.
19+
4. Structure.
20+
21+
Do not force the integration into a single bucket. Most integrations compose several patterns. For example, PostgreSQL is a container-backed service, has parent-child database resources, exposes connection properties, creates databases during resource readiness, and has admin UI companion helpers.
22+
23+
## Then read the matching resources
24+
25+
Always read the relevant archetype resource and the cross-cutting resources that apply to the change.
26+
27+
| If the integration involves | Read |
28+
| --- | --- |
29+
| Any resource, annotation, lifecycle event, structured value, endpoint, manifest, or app-model behavior | `resources/app-model-fundamentals.md` |
30+
| Local container service, database, broker, cache, vector DB | `resources/archetype-container-backed-service.md` |
31+
| Admin UI, inspector, dashboard, load/test tool, or standalone utility container | `resources/archetype-admin-and-tool-container.md` |
32+
| Migration, package/tool install, model pull, schema deployment, DACPAC, or one-shot setup helper | `resources/archetype-setup-and-migration-helper.md` |
33+
| Serialized controller, reconciler, command-driven resource operations, drift detection, or state-machine orchestration | `resources/archetype-controller-reconciler.md` |
34+
| Sidecar, component registry, telemetry collector, service mesh, middleware, or app-wide annotation-driven infrastructure | `resources/archetype-sidecar-and-middleware.md` |
35+
| Local tunnel, webhook forwarder, callback bridge, or CLI that exposes/forwards local endpoints | `resources/archetype-tunnel-and-webhook-bridge.md` |
36+
| Secret manager, credential broker, external secret provider, or provider-backed managed secret child resources | `resources/archetype-secret-provider.md` |
37+
| External/SaaS service reference with API key/endpoint, no local container/provisioning | `resources/archetype-external-cloud-reference.md` |
38+
| Azure resource provisioning, Bicep, role assignments, existing Azure resources, emulators, local containers for Azure resources | `resources/archetype-azure-provisioning.md` |
39+
| Docker Compose, Kubernetes, Azure Container Apps, or another deployment target/publisher | `resources/archetype-deployment-target-publisher.md` and `resources/deployment-production-readiness.md` |
40+
| Python, Go, JavaScript, Node, Vite, Next.js, or another language runtime/workload | `resources/archetype-language-executable-app.md` |
41+
| Non-resource model/configuration overlay, e.g. Orleans-style APIs | `resources/archetype-overlay-configuration.md` |
42+
| Public API names, overloads, return types, polyglot AppHost compatibility, annotations, experimental state | `resources/api-naming-and-shape.md` |
43+
| Any run/publish/deploy branching | `resources/run-publish-deploy-modes.md` |
44+
| Event subscriptions, initialization, generated files, health checks, pipeline steps | `resources/eventing-and-initialization.md` |
45+
| Custom resource lifetime, synthetic/facade resources, manually allocated endpoints, or resource notification state machines | `resources/custom-lifecycle-and-facade-resources.md` |
46+
| `IResourceWithConnectionString`, `WithReference`, environment variables, URI/JDBC properties | `resources/connection-properties.md` |
47+
| Parent-child resources, companions, setup siblings, `WithReference`, waits, relationships | `resources/relationships-and-companions.md` |
48+
| `[AspireExport]`, TypeScript/polyglot AppHosts, ATS metadata, analyzer diagnostics, DTOs, union parameters, value catalogs, callback contexts | `resources/polyglot-exports.md` |
49+
| Endpoint names, service discovery, external URLs, reference endpoints, endpoint environment variables | `resources/endpoints-and-service-discovery.md` |
50+
| Secrets, parameters, credentials, managed identity, RBAC, private networking, generated artifacts containing sensitive data | `resources/security-secrets-and-identity.md` |
51+
| Resource names, physical names, annotations, constructors, mutability, model invariants | `resources/resource-model-invariants.md` |
52+
| Package metadata, preview/stable posture, `aspire add` discovery, icons, gallery/README visibility | `resources/package-and-discoverability.md` |
53+
| Dashboard icons, URLs, commands, notifications, resource logs, admin companion UX | `resources/dashboard-ux.md` |
54+
| Generated config files, `WithContainerFiles`, file permissions, temp/store usage, build dependencies | `resources/generated-files-and-container-files.md` |
55+
| Toolchain detection, path handling, Windows/macOS/Linux behavior, shell quoting, executable permissions | `resources/cross-platform-tooling.md` |
56+
| Experimental/obsolete/deprecation lifecycle, compatibility shims, migration guidance | `resources/compatibility-and-deprecation.md` |
57+
| README or tests | `resources/testing-and-readmes.md` |
58+
59+
## Authoring workflow
60+
61+
1. State the classification briefly before changing or reviewing code.
62+
2. Apply the archetype-specific DO/DON'T list.
63+
3. Apply every relevant cross-cutting checklist.
64+
4. Validate both run-mode and publish/deploy behavior when the integration changes those surfaces.
65+
5. Keep generated API baseline files under `*/api/*.cs` untouched unless the task explicitly asks for API baseline regeneration.
66+
67+
## Review workflow
68+
69+
When reviewing an integration PR, look for concrete violations that can cause wrong runtime behavior, wrong generated manifests, broken deployment output, bad public API, missing connection properties, or bad polyglot projection. Do not spend review budget on style-only comments.

‎.agents/skills/hosting-integration-authoring/resources/api-naming-and-shape.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# API naming and shape
2+
3+
Aspire hosting integrations should feel consistent across C# and polyglot AppHosts. Public APIs should be predictable, versionable, and hard to misuse.
4+
5+
## Method naming
6+
7+
| Pattern | Use for | Examples |
8+
| --- | --- | --- |
9+
| `Add{Technology}` | Create a top-level resource or integration object | `AddPostgres`, `AddAzureStorage`, `AddGoApp` |
10+
| `Add{Child}` | Create parent-scoped subresources | `AddDatabase`, `AddQueue`, `AddBlobContainer`, `AddModel` |
11+
| `With{Configuration}` | Configure an existing resource builder | `WithDataVolume`, `WithHostPort`, `WithEnvironment` |
12+
| `RunAs{Mode}` | Change local run behavior only | `RunAsEmulator`, `RunAsContainer`, `RunAsExisting` |
13+
| `PublishAs{Target}` | Change publish/deploy behavior only | `PublishAsDockerComposeService`, `PublishAsAzureContainerApp` |
14+
| `AsExisting` | Apply existing-resource semantics in both run and publish modes | `AsExisting` |
15+
| `Configure{Model}` | Mutate a generated deployment or infrastructure model | `ConfigureInfrastructure`, `ConfigureComposeFile` |
16+
17+
## Polyglot AppHost compatibility
18+
19+
Polyglot compatibility is a cross-cutting API shape constraint, not a separate integration archetype. Treat TypeScript and other generated AppHosts as first-class consumers when naming and shaping public APIs.
20+
21+
DO:
22+
23+
- Sketch the intended generated-SDK call shape before finalizing public C# names.
24+
- Keep one user concept to one generated method name on a given target type. Put variation in an options DTO, enum, union parameter, or internal dispatcher.
25+
- Use names that describe user behavior, not C# implementation mechanics. For example, prefer `PublishAsStaticWebsite` over names that expose callback, generic, or annotation details.
26+
- Mark C# convenience overloads, callback overloads, and generic-metadata overloads with `[AspireExportIgnore(Reason = "...")]` when they are not the generated-SDK contract.
27+
- Add a polyglot-friendly exported adapter when the ergonomic C# API uses callbacks, generics, framework types, or types that do not project cleanly.
28+
- Use language-neutral XML docs and `ats-*` overrides when the C# docs mention types or behaviors generated SDK users cannot see.
29+
- Inspect generated SDK names, signatures, docs, and capability IDs before shipping a new exported API.
30+
31+
DON'T:
32+
33+
- Don't rely on C# overload resolution, extension receiver types, generic constraints, or optional-parameter overloads to make generated APIs understandable.
34+
- Don't expose C# implementation type names such as `Action`, `IServiceProvider`, `IConfiguration`, `IProjectMetadata`, annotations, or builder callbacks as the only way to configure a feature.
35+
- Don't let internal adapter names leak into generated SDKs. Use an explicit export ID or `MethodName` so generated users see the conceptual API name.
36+
- Don't add a C#-only API and defer polyglot shape decisions until after the API has shipped.
37+
38+
## Type naming
39+
40+
Use nouns or noun phrases for public types.
41+
42+
- Primary resources: `{Technology}Resource` or `{Technology}ServerResource`.
43+
- Child resources: `{Technology}{Child}Resource`, for example `PostgresDatabaseResource`.
44+
- Admin/dev companion containers: `{Tool}ContainerResource`, for example `PgAdminContainerResource`.
45+
- Annotations: `{Purpose}Annotation`, not verb-prefixed names.
46+
- Options objects: `{Feature}Options`.
47+
48+
Prefer consistent property names:
49+
50+
- URI-producing values should be named `UriExpression`.
51+
- Connection string expressions should be named `ConnectionStringExpression`.
52+
- Endpoint references should be named after role: `PrimaryEndpoint`, `InternalEndpoint`, `HttpEndpoint`.
53+
- `IServiceProvider` properties should be named `Services`.
54+
- Port customizers should use existing names like `WithHostPort` or role-specific names like `WithGatewayPort`.
55+
56+
## Return types
57+
58+
Resource-producing APIs should return `IResourceBuilder<TResource>`.
59+
60+
Rare overlay/configuration APIs may return a non-resource object only when the integration intentionally does not create a resource. See `archetype-overlay-configuration.md`.
61+
62+
Fluent configuration APIs should return the same builder type they receive, unless they create and return a child resource.
63+
64+
## Parameters
65+
66+
DO:
67+
68+
- Use `[ResourceName] string name` for Aspire resource names.
69+
- Validate `builder` with `ArgumentNullException.ThrowIfNull`.
70+
- Validate required strings with `ArgumentException.ThrowIfNullOrEmpty`.
71+
- Separate Aspire resource names from physical names. Use `databaseName`, `queueName`, or similar optional physical-name parameters that default to `name`.
72+
- Use `IResourceBuilder<ParameterResource>` for secrets and user-supplied credentials.
73+
- Prefer options objects when an API needs many optional parameters.
74+
75+
DON'T:
76+
77+
- Don't make logically required parameters optional just to avoid updating call sites.
78+
- Don't add many optional parameters to public APIs; they are hard to version.
79+
- Don't use `Tuple<>` in public APIs.
80+
- Don't expose implementation-detail annotations, helpers, or generated deployment node types publicly unless users must customize them.
81+
- Don't use boolean parameters when an enum is clearer and likely to grow.
82+
83+
## Annotations
84+
85+
Use `ResourceAnnotationMutationBehavior.Replace` for last-wins configuration, such as build flags, selected package manager, chosen publish mode, or existing-resource settings.
86+
87+
Do not accumulate mutually exclusive annotations unless multiple annotations are intentionally meaningful.
88+
89+
## Experimental APIs
90+
91+
Mark unstable or emerging APIs with `[Experimental("ASPIRE...")]` and use a unique diagnostic ID. Deployment, publishing, compute, language-runtime, and generated-Dockerfile APIs often require experimental treatment.
92+
93+
Do not add obsolete shims for APIs that have not shipped stable unless there is a specific compatibility reason.

0 commit comments

Comments
 (0)