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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#2,131 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 2 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
82/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
csharp
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với bảng các thay đổi gây lỗi tương thích trong src/frontend/src/content/docs/whats-new/aspire-13-3.mdx và làm theo định dạng của bảng khi thêm thay đổi DisplayOrder vào trang What's new của Aspire 17.0. Hãy cân nhắc cập nhật ví dụ trong src/frontend/src/content/docs/fundamentals/custom-resource-urls.mdx để hiển thị DisplayOrder. Hoàn tất khi thay đổi gây lỗi tương thích và ảnh hưởng của nó đến khả năng tương thích nhị phân được ghi lại, đồng thời ví dụ phản ánh thuộc tính được hỗ trợ nếu bạn cập nhật ví dụ.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
MDX
Star
202
Fork
99
Merge trung bình
2 ngày 10 giờ
Pull request đã merge (30 ngày)
97

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của microsoft/aspire.dev

Tất cả issue của microsoft/aspire.dev

Issue tương tự

Thêm issue về Documentation

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.