Annotation-Based Open Discriminated Union for Aspire Resources

[davidfowl]

Today every concrete resource class—ProjectResource, ContainerResource, AzureServiceBusResource, etc.—owns state in its own fields.
When real workflows demand the same logical resource appear differently in run-mode and publish-mode, our model currently must

1. remove the original resource instance
2. create another concrete type
3. copy annotations by hand

That breaks identity (two resource IDs), scatters logs, confuses diff tooling, and forces hacks inside helpers such as RunAsContainer(), RunAsEmulator(), and PublishAsDockerFile().

We already tie container identity to the annotation-collection reference; this proposal finishes that idea for all resources:

• All observable state lives in the annotation collection.
• A discriminator annotation — ResourceTypeAnnotation.ResourceKind : Type — declares the current shape.
• Wrapper classes (views) expose ergonomic APIs but share the same annotation spine.

Dev inner-loop	Publish output
.NET Project	OCI container
Emulator container	Azure PaaS service
Local Redis container	Connection-string parameter pointing at a shared cache

Identity never changes; we simply switch the tag.

graph TD
    subgraph "Annotations (identity)"
        A["{ annotations … ; tag = ResourceKind }"]
    end
    A -- viewed-as --> B[ProjectResource]
    A -- viewed-as --> C[ContainerResource]
    A -- viewed-as --> D[AzureBicepResource]
    A -- viewed-as --> E[ConnectionStringParam]

Loading

Code sketches (same helpers, new engine)

// Project ⇒ container on publish
builder.AddProject("web")
       .PublishAsDockerFile(); // internally retags to ContainerResource

// Azure PaaS ⇒ emulator container on local run
builder.AddAzureServiceBus("events")
       .RunAsEmulator();      // retags to ContainerResource

// Container ⇒ external hosted cache for prod
builder.AddRedis("cache")
       .PublishAsConnectionString(); // retags to ConnectionStringParameter

---

Execution plan (high-level)

Phase A — helper façade

• Add IsKind<T>(), TryGet<T>() (initial impl = is/as).
• Replace direct is, as, OfType<T>() in the codebase.
• Roslyn analyzer forbids new violations.
• Behaviour identical to today.

Phase B — tag & identity

• Introduce ResourceTypeAnnotation and Resource.ResourceKind.
• Equals/GetHashCode now rely on the annotation-collection reference.
• Helpers switch to the tag internally.
• Identity stable across view switches.

Phase C — move data to annotations

• Create *Annotation classes (e.g. ContainerEntryPointAnnotation).
• Properties wrap annotations; helpers retag instead of delete + clone.

Annotation collections become read-only after model-build; cloning must be explicit.

---

Helper API details

public static bool IsKind<T>(this IResource r)
    => r.ResourceKind == typeof(T);

public static bool TryGet<T>(this IResource r,
                             [NotNullWhen(true)] out T? view)
    where T : class, IResource
{
    if (r.ResourceKind == typeof(T))
    {
        view = r as T ??
               (T)Activator.CreateInstance(typeof(T), r.Name, r.Annotations)!;
        return true;
    }
    view = null;
    return false;
}

Every resource kind must expose a (string name, ResourceAnnotationCollection ann) constructor; an analyzer will enforce this.

---

Trade-offs & potential issues

• Exhaustiveness – compiler no longer warns if a new kind is unhandled.
  Mitigation: default branches plus analyzer checks.
• Performance – reflection in the helpers.
  Mitigation: cache typeof(T) comparisons and profile.
• External extensions using is/as – will break when the tag diverges from CLR type.
  Mitigation: analyzer package + migration docs; optional runtime guard.
• Annotation mutability – copy-on-write or concurrent edits could corrupt identity.
  Mitigation: freeze collection reference after build; mutations through WithAnnotation.
• Constructor convention – new kinds must add the two-arg ctor.
  Mitigation: analyzer + project template.
• Versioning – equality semantics change.
  Mitigation: land in next major release; debug shim to detect old behaviour.

---

Unsolved / open design gaps

View-specific members remain callable after a view switch.

Example: you create an AzureBicepResource, call RunAsEmulator(), so it is now viewed as a container, yet bicepResource.Outputs["primaryKey"] is still accessible—even though those outputs are meaningless in run-mode.

Unanswered questions:

• Do we introduce publish-only / run-only capabilities so annotations can self-describe validity?
• Should runtime guards throw (or assert) when a publish-only member is accessed under a run-mode tag?
• Can a Roslyn analyzer warn when publish-only members are used in run-time code paths?
• At minimum we need docs that state: after a view switch certain members are undefined and accessing them is user error.

These remain open and must be tracked as follow-up work once the union mechanics are in place.

See #7251 for an initial prototype

[afscrome]

I've been playing around with this concept a bit - specifically around converting Containers to Projects. It works at a high level, but I've hit a few oddities.

Oddities if leaving if a resource is treated as both container and executable

In my first iteration of AsProject, I copied all annotations over to the new project resource (including the ContainerImageAnnotation). This led to a number of weird situations:

• It seems like aspire starts both the exe and the container, but it only shows logs for the container.
• If the exe exits after the container starts up, the resource state transitions to Exited but the container is still running / putting out logs. (It is very confusing when you're seeing logs continuing to show up in an Exited resource.
• You end up with two stop / restart buttons

I think Phase A as suggested above should sort this problem out.

Endpoint Target Port

With containers, you must specify a target port. But for executables you almost never want to specify the target port. This means there's no good way to configure your endpoints to work as both a project and a container without needing to do targeted modifications when converting the resource.

Contextual endpoint resolution

I think this will also make #7153 even more important - right now you can work around the lack of that by knowing the exact context your resource is going o be run in. But if that context can be changed by further callers, those assumptions will no longer work out. I've already encountered one situation where I have to add a WithEnvironment callback and conditionally specify the server address / port differently depending on whether the resource resolves as a container or a project.

              .WithEnvironment(x =>
              {
                  if (x.Resource is ContainerResource)
                  {
                      x.EnvironmentVariables["LocalRabbitMqServerAddress"] = rabbitMq.Resource.Name;
                      x.EnvironmentVariables["LocalRabbitMqServerPort"] = rabbitMq.Resource.PrimaryEndpoint.TargetPort;
                  }
                  else
                  {
                      x.EnvironmentVariables["LocalRabbitMqServerAddress"] = rabbitMq.Resource.PrimaryEndpoint.Host;
                      x.EnvironmentVariables["LocalRabbitMqServerPort"] = rabbitMq.Resource.PrimaryEndpoint.Port;
                  }
              })

For reference, what I've been playing around with:

internal static class ProjectSubstitution
{
    // Multiple generic params on an extension method is a bit nasty - whilst a single generic parm
    // is often resolved implicitly, that isn't true with multiple args
    // But it does mean the converted resource has an explicit conversion to the old resource type
    // Alowing you to continue using it with methods taking the container based type
    public static IResourceBuilder<ProjectResource<T>> AsProject<T, V>(this IResourceBuilder<T> builder)
        where T : ContainerResource
        where V : IProjectMetadata, new()
    {
        // Remove the original resoruce
        var originalResource = builder.Resource;
        builder.ApplicationBuilder.Resources.Remove(originalResource);

        // WithProjectDefaults is internal, so create a temporary project resource
        // and steal the resulting annotations.
        var tempProject = builder.ApplicationBuilder.AddProject<V>(builder.Resource.Name, options => options.ExcludeKestrelEndpoints = true);
        builder.ApplicationBuilder.Resources.Remove(tempProject.Resource);
        builder.ApplicationBuilder.Resources.Remove(originalResource);


        // Now create the substitue resource, using the original resoruce's annotations
        // As well as the extra project annotations
        var resource = new ProjectResource<T>(originalResource);
        foreach (var annotation in tempProject.Resource.Annotations)
        {
            resource.Annotations.Add(annotation);
        }

        // Strip out container related annotations
        // Otherwise weird things happenw ith aspire tyring to run both the container and the executable
        var containerAnnotations = originalResource.Annotations.OfType<ContainerImageAnnotation>().ToArray();
        foreach (var annotation in containerAnnotations)
        {
            resource.Annotations.Remove(annotation);
        }

        // For containers, you have to specify a target port, but for executable resources you
        // may want to rely on DCP to allocate a dynamic port for you
        foreach (var endpoint in originalResource.Annotations.OfType<EndpointAnnotation>())
        {
            if (endpoint.Port == null &&  endpoint.IsProxied)
            {
                endpoint.TargetPort = null;
            }
        }

        return builder.ApplicationBuilder.AddResource(resource);
    }
}


public class ProjectResource<T> : ProjectResource
   where T : ContainerResource
{
    private readonly T _inner;

    public ProjectResource(T inner) : base(inner.Name)
    {
        _inner = inner;
        // Remove all container annotations to ensure aspire doens't try to start the resource as both a project and a container
        var containerAnnotations = inner.Annotations.OfType<ContainerImageAnnotation>().ToArray();
        foreach (var annotation in inner.Annotations)
        {
            inner.Annotations.Remove(annotation);
        }
    }

    public override ResourceAnnotationCollection Annotations => _inner.Annotations;

    public static explicit operator T(ProjectResource<T> resource) => resource._inner;
}

[afscrome]

Another awkwardness I encountered converting ContainerResource to ProjectResource - Bind Mounts / Container Files / Volumes need to be adapted. (And then so to do any EnvironmentVariables / ReferenceExpressions referencing those paths.

For this specific case, perhaps there is a more general file system API (.WithFile(), .WithDirectory()) that can be used.

But more generally, I also wonder if we'll need some way to only add annotations when the resource is viewed as a specific type e.g.

builder.WhenViewedAs<ContainerResource>(innerBuilder =>
{
   // these methods will only apply their annotations to the `ContainerResource` view, not other views.
   builder.WithEnvironment("RunningAsContainer", true);
}
builder.WhenViewedAs<ProjectResource>(innerBuilder =>
{
   builder.WithEnvironment("RunningAsContainer", false);
}

Somewhat similar to MapWhen int he ASP.Net core middleware pipeline.

[maddymontaquila]

This has been addressed/resolved in #11135. Closing as done. Thank you for filing! If you're still experiencing issues with the latest version, please open a new issue.

[karolz-ms]

Suggestions for what characteristics the solution for this issue should have:

• I can put as many "RunAs"/"PublishAs" annotations on a resource as I want to. They can be configured independently.
• I can put multiple annotations of the same type on a resource. E.g. I can configure that a resource should be run as a container during local run and as different container when deployed to Kubernetes.
• The programmatic type that I am getting as a result/callback to RunAs/PublishAs should reflect both the base resource characteristics as well as the run modality characteristics. E.g. if I RunAsContainer() a Node app, I should get a proxy for the resource that has Node app properties/methods and container properties/methods.
• The logic to decide which run modality is used for local run/deployment is a setting (or policy) of the target environment. E.g. with a single line of code I can change the local run configuration to run a particular Node app to run as a container instead as a process.

[afscrome]

Another complication I hit with #18052 was handling of helper resources - e.g. when replacing the project resource with a container, I wanted the built in rebuilder child resource gone.

Might be solvable by the same WhenViewedAs suggestion above, but equally could need a different approach.