Deprecate Integration

You are a specialized integration-deprecation agent for the microsoft/aspire repository. Your job is to perform a complete, consistent soft sunset of a shipped hosting integration (for example Aspire.Hosting.GitHub.Models) so that:

• every public and exported API surfaces a clear [Obsolete] warning that points at a tracking issue,
• the package stops showing up in aspire add,
• integration-specific automation that only exists to maintain it is removed,
• the solution still builds clean and the package still publishes one final obsolete version,
• and a later release can delete the integration entirely with minimal extra work.

Do not delete the project, its tests, its playground, or its polyglot fixtures during a soft sunset. Deletion is a separate, later phase (see "Phase 2: full removal" at the end).

Background: the two-phase lifecycle

Aspire retires an integration in two releases:

1. Phase 1 — soft sunset (this skill). Mark the API [Obsolete], warn in the README, hide it from aspire add, drop its bespoke tooling/workflows, and keep it packable so the next release ships a final, clearly-deprecated version. Existing apps keep working.
2. Phase 2 — full removal (a later release). Delete the project, tests, playground, polyglot fixtures, and solution entry. Keep the package id in the CLI DeprecatedPackages list so previously-published versions stay hidden from aspire add.

Precedent in the repo:

• Aspire.Hosting.Dapr and Aspire.Hosting.NodeJs are already in Phase 2 — their src/ projects are gone, but their ids remain in DeprecatedPackages.s_all.

Inputs to collect

Before starting, determine:

1. Integration project — e.g. src/Aspire.Hosting.<Name>/ and its package id Aspire.Hosting.<Name>.
2. Tracking issue URL — the GitHub issue explaining why the integration is being sunset. Every obsolete message, README banner, and explanatory comment links to it.
3. A short reason — one sentence a user will read (e.g. "GitHub Models is no longer available to new customers").

If the tracking issue is unknown, ask for it before editing — the message text and comments depend on it.

Step 1 — Add a shared deprecation message constant

Create src/Aspire.Hosting.<Name>/<Name>Deprecation.cs with a single internal constant reused by every [Obsolete] attribute. Centralizing the text keeps all the warnings identical and makes the follow-up edit trivial.

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace Aspire.Hosting.<Name>;

internal static class <Name>Deprecation
{
    // <Reason>, so the integration is being sunset.
    // See <tracking-issue-url> for details.
    public const string Message = "<Reason>, so the Aspire <Name> integration is deprecated and will be removed in a future release. See <tracking-issue-url> for details.";
}

Match the integration's existing root namespace. If a type lives in a different namespace than the constant, add a using for the deprecation namespace to that file.

Step 2 — Mark the entire public + exported API [Obsolete]

Add [Obsolete(<Name>Deprecation.Message)] to each public type and each extension method the integration exposes:

• the resource class(es) (public class <Name>Resource : Resource, ...),
• any public descriptor/option/enum-wrapper types the integration exposes (the type, not each of its entries — see scoping below),
• all extension methods in *Extensions.cs, including public and internal ones.

Scope it correctly — mark each public type and extension method once, and do not over-apply:

• Marking a type [Obsolete] already covers all of its members. Any access through an obsolete type (including its nested types, fields, constants, and static readonly descriptor instances) raises CS0618 for consumers. So when you mark the enclosing type, do not also decorate its nested types, members, or per-item constants — that is redundant and produces a large, noisy diff for no behavioral gain.
• Do not edit generated files (*.Generated.cs, or any file produced by tooling) to add [Obsolete]. Mark the hand-authored partial that declares the public type instead; the obsolete attribute on the enclosing type carries over to the generated partial's members automatically.
• Never overwrite a pre-existing [Obsolete(...)] attribute that carries a more specific message. Some members may already be obsolete for a different, narrower reason (for example, individual catalog entries marked [Obsolete("This item has been removed from the service.")]). Leave those messages intact — only add [Obsolete(<Name>Deprecation.Message)] to members that are not already obsolete.

Other important details:

• Keep [AspireExport] / [AspireExportIgnore] attributes in place. [Obsolete] does not remove a member from polyglot code generation. The ATS scanner reads [Obsolete] (AtsCapabilityScanner sets IsObsolete) and the generators still emit the member, just annotated @deprecated (e.g. AtsTypeScriptCodeGenerator emits a @deprecated JSDoc tag). Removing the export attributes would change the generated SDK surface and break polyglot apphosts — do not do it.
• Place [Obsolete(...)] above the existing attributes on each member, then the other attributes, then the signature.
• Do not add error: true to [Obsolete]. It must stay a warning so the final release still compiles for consumers and so the package builds.

Example:

[Obsolete(<Name>Deprecation.Message)]
[AspireExport]
public static IResourceBuilder<<Name>Resource> WithApiKey(this IResourceBuilder<<Name>Resource> builder, ...)

You do not normally need <NoWarn>CS0618</NoWarn> in the integration's own product .csproj: Roslyn does not raise CS0618 when an obsolete member references another obsolete member within the same obsolete context. Rely on the build (Step 6) to confirm rather than pre-emptively suppressing.

Step 3 — Add a README warning banner

At the very top of src/Aspire.Hosting.<Name>/README.md (right under the # <Title> heading), add a GitHub alert banner so the deprecation is unmissable on NuGet and GitHub:

> [!WARNING]
> **This integration is deprecated and no longer supported.**
> <Reason>, so the
> `Aspire.Hosting.<Name>` integration has been sunset. It will not receive
> further updates and will be removed in a future release. Existing applications
> continue to function, but new use is discouraged.
> See [microsoft/aspire#<issue-number>](<tracking-issue-url>)
> for details.

Leave the rest of the README intact so existing users can still read the usage docs.

Step 4 — Remove integration-specific automation and tooling

Delete anything that exists only to maintain this integration, because it should stop running once the integration is frozen:

• Scheduled GitHub Actions workflows that refresh data for it (e.g. .github/workflows/update-<name>.yml).
• Bespoke code generators / data-refresh tools under src/Aspire.Hosting.<Name>/tools/ (e.g. GenModel.cs, tools/Directory.Build.props, tools/Directory.Build.targets).
• Any <Compile Remove="tools\**\*.cs" /> (or similar) lines in the integration .csproj that only existed to exclude that tooling — remove them when you delete the tooling so the project file stays clean.

Search for other references to the removed workflow/tooling (CI trigger maps, docs) and clean up dangling mentions. Do not remove shared infrastructure used by other integrations.

Step 5 — Hide the package from aspire add

Add the package id to the CLI deny-list in src/Aspire.Cli/NuGet/NuGetPackageCache.cs:

internal static class DeprecatedPackages
{
    private static readonly FrozenSet<string> s_all = new[]
    {
        "Aspire.Hosting.Dapr",
        "Aspire.Hosting.<Name>",   // keep the list alphabetically sorted
        "Aspire.Hosting.NodeJs"
    }.ToFrozenSet(StringComparer.OrdinalIgnoreCase);
    ...
}

This filters the package out of aspire add search/listing and aspire update suggestions by default. It does not affect aspire restore, which resolves already-declared packages by exact id directly through the bundled NuGet service — that is why existing apps and polyglot fixtures keep restoring fine.

Users who still need it can opt back in with the feature flag (aspire config set features.showDeprecatedPackages true), so this is a soft hide, not a hard block.