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

未关闭 适合新手
  • 哪里不对？
#2,131 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 2 天内回复

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
82/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
csharp
领域
documentation

调研方向

从 src/frontend/src/content/docs/whats-new/aspire-13-3.mdx 中的破坏性变更表开始，添加 DisplayOrder 变更到 Aspire 17.0 的 What's new 页面时遵循该表的格式。考虑更新 src/frontend/src/content/docs/fundamentals/custom-resource-urls.mdx 中的示例，以展示 DisplayOrder。完成条件是记录该破坏性变更及其对二进制兼容性的影响；如果更新示例，则示例应体现受支持的属性。

由索引模型根据 Issue 内容生成。

描述

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.
主要语言
MDX
星标
202
派生
99
平均合并
2 天 10 小时
30 天内合并 PR
97

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

microsoft/aspire.dev 的其他 Issue

查看 microsoft/aspire.dev 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。