Skip to content

[17.0] Document breaking change: ResourceUrlAnnotation.DisplayOrder changed from a field to a property #2131

Closed

Description

In Aspire 17.0, Aspire.Hosting.ApplicationModel.ResourceUrlAnnotation.DisplayOrder in the stable Aspire.Hosting package changed from an [Obsolete] public field to a read/write property. Typical C# code still compiles, but assemblies compiled against the field fail at run time until they're rebuilt, so this should be listed in the 17.0 breaking changes.

- [Obsolete("DisplayOrder was incorrectly created as a field. It will be re-added as a property in a future Aspire version.")]
- public int? DisplayOrder;
+ public int? DisplayOrder { get; set; }

Why it changed

DisplayOrder was exposed as a public field by mistake. Aspire 13.6 marked the field obsolete and said a property would replace it in a future version. Aspire 17.0 makes that change and removes the obsolete warning. What the value means hasn't changed: higher values sort the URL higher on the dashboard.

Impact

  • Binary: assemblies compiled against an earlier Aspire version that read or write DisplayOrder throw MissingFieldException at run time with Aspire 17.0 until they're rebuilt. Hosting integrations that set it in a WithUrlForEndpoint or WithUrls callback are an example.
  • Source: reads, assignments, and object initializers compile unchanged, and the CS0618 obsolete warning no longer appears. Passing DisplayOrder by ref or out no longer compiles.
  • Reflection: code that looks up DisplayOrder with Type.GetField must use Type.GetProperty.

Migration

Rebuild against Aspire 17.0. Typical usage needs no code changes:

builder.AddProject<Projects.AspireApp_Api>("api")
    .WithUrlForEndpoint("https", url =>
    {
        url.DisplayText = "Scalar (HTTPS)";
        url.Url = "/scalar";
        url.DisplayOrder = 1000;
    });

After rebuilding:

  • Remove any #pragma warning disable CS0618 directives or NoWarn entries that were only there for DisplayOrder.
  • Replace ref or out usage with a local variable, then assign it to the property.
  • Hosting integration authors who set DisplayOrder need to ship a version built against Aspire 17.0.

Where to document

  • Add a row to the ⚠️ Breaking changes table on the 17.0 What's new page. There's no whats-new/aspire-17*.mdx on main yet; follow the table in aspire-13-3.mdx.
  • Consider showing DisplayOrder in the Customize endpoint URL example now that it can be set without a warning. No aspire.dev page mentions it today.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions