Aspire 托管集成开发指南打造高质量 Dashboard UX图标、URL、命令与日志设计规范【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读本文以 Aspire 仓库中托管集成Hosting Integration开发技能的 Dashboard UX 设计规范为骨架系统讲解如何在为 Aspire 构建自定义资源与集成时设计出清晰、安全、可观测的仪表盘用户体验。你将掌握WithIconName图标与资源命名规范、WithUrlForEndpoint/WithUrls的 URL 展示策略、资源命令Resource Commands的安全设计要点以及通知、日志与管理伴生资源Admin Companion的最佳实践并对照 src/Aspire.Hosting 下的真实源码理解其底层机制。核心原则让资源不言自明托管集成Hosting Integration决定了用户在 Aspire Dashboard 中看到的一切。优秀的 Dashboard UX 应该让资源一目了然、无需暴露实现细节即可被理解。换句话说用户看到的是资源是什么、能做什么、怎么访问而不是它底层由哪些组件拼装而成。这份规范的核心出发点可以概括为两句话面向用户而非面向实现只展示用户需要看到、需要操作的资源与信息可操作、可观测、可取消凡是暴露给用户的操作都必须安全、清晰、可取消、可追踪。图标与资源展示Icons and Display应该做DO当存在与资源匹配的清晰图标时使用WithIconName设置图标。在源码中WithIconName定义于 ResourceBuilderExtensions.cs其实现是向资源追加一个ResourceIconAnnotation注解public static IResourceBuilderT WithIconNameT(this IResourceBuilderT builder, string iconName, IconVariant iconVariant IconVariant.Filled) where T : IResource { ArgumentNullException.ThrowIfNull(builder); ArgumentException.ThrowIfNullOrWhiteSpace(iconName); return builder.WithAnnotation(new ResourceIconAnnotation(iconName, iconVariant), ResourceAnnotationMutationBehavior.Replace); }从 ResourceIconAnnotation.cs 的实现可见iconName必须是有效的 FluentUI 系统图标名称iconVariant支持Regular或Filled两种变体默认使用Filled。ResourceAnnotationMutationBehavior.Replace意味着多次调用时后设置的图标会覆盖前者这为集成作者在默认图标基础上按需覆盖提供了明确语义。使用清晰的名字与关系让父子资源parent-child和伴生资源companion的关系一目了然。命名时应让用户仅凭名称即可判断资源的层级归属而不是靠点击查看详情才能推断。将纯内部设置、仅部署期存在的资源适当地排除在运行模型run model或清单manifest之外。这类资源例如部署脚本、内部初始化容器如果对用户没有操作价值就不应该出现在 Dashboard 的一级资源列表中。不应该做DONT不要把内部设置、仅部署期或实现类资源当作一级 Dashboard 资源展示除非用户确实需要对这些资源执行操作不要使用误导性的图标或过于通用的名称——当存在更清晰的资源身份时泛化命名会降低 Dashboard 的可读性。URL 展示策略应该做DO暴露面向用户的主 URL。每个资源的 URL 是用户与该资源交互的主要入口必须是用户真正会点击使用的地址。使用WithUrlForEndpoint调整某个端点的显示文本或展示位置。该方法在 ResourceBuilderExtensions.cs 中有两个重载第一个重载接收ActionResourceUrlAnnotation回调用于修改已存在端点的 URL 展示属性public static IResourceBuilderT WithUrlForEndpointT(this IResourceBuilderT builder, string endpointName, ActionResourceUrlAnnotation callback) where T : IResource { builder.WithUrls(context { var urlForEndpoint context.Urls.FirstOrDefault(u u.Endpoint?.EndpointName endpointName); if (urlForEndpoint is not null) { callback(urlForEndpoint); } else { context.Logger.LogWarning(Could not execute callback to customize endpoint URL as no endpoint with name {EndpointName} could be found on resource {ResourceName}., endpointName, builder.Resource.Name); } }); return builder; }第二个重载接收FuncEndpointReference, ResourceUrlAnnotation工厂用于新增一个与端点关联的 URL见 ResourceBuilderExtensions.cs。从 ResourceUrlAnnotation.cs 可以看到 URL 注解的完整字段Url链接目标、DisplayText链接文本、Endpoint关联的端点引用可为空、DisplayLocation展示位置默认为SummaryAndDetails以及已标记过时的DisplayOrder排序字段。其中DisplayLocation枚举定义了 URL 的两种展示层级取值含义SummaryAndDetails在资源摘要和资源详情两处都展示默认值DetailsOnly仅在资源详情页展示不进入资源摘要把诊断类、健康检查、指标或次要 URL 放进仅详情details-only展示避免污染资源摘要当用户被预期会打开管理端伴生 URL 时将其暴露出来详见下文管理伴生资源。不应该做DONT不要让内部端点淹没资源摘要。摘要区应保持克制只放用户高频使用的入口不要把健康检查端点当作主应用 URL 暴露。健康检查是运维细节不是业务入口放在详情页即可。资源命令Resource Commands资源命令是用户动作是 Dashboard 中用户能主动触发资源行为的主要途径。因此它们必须满足安全、清晰、可取消、可观测。应该做DO命令名与展示名都要准确描述动作。命令的命名应以动词开头、直白无歧义用户不需要阅读文档就能判断点了会发生什么。校验命令前置条件尽可能返回明确的禁用disabled/不可用unavailable状态。让用户在点击之前就知道当前状态下该命令是否可用而不是点击后才得到失败反馈。尊重取消令牌cancellation tokens。命令执行应响应取消请求避免用户无法中止耗时操作。这是命令可取消要求的直接落地。将有用的执行进度写入资源日志resource logs。用户执行命令后应在对应资源的日志中看到清晰的进度与结果形成闭环可观测。避免依赖隐藏的全局状态的命令。命令的可理解性与可测试性都要求其行为只取决于资源自身的状态与显式参数。对于 controller/reconciler 类集成命令的启用/禁用/隐藏状态应直接由 controller 的活动与排队操作状态推导。这是命令状态单一事实来源的要求——不要让 Dashboard 侧的逻辑猜测 controller 的内部状态。在变更类操作进行期间保持只读诊断类命令可用只要它们有助于恢复与排查。诊断命令不能因为正在变更就被一刀切禁用。为需要被 Agent 或用户检视的操作返回结构化命令结果structured command results便于自动化消费与审计。不应该做DONT不要添加命名含糊、缺少保护措施的破坏性命令。破坏性操作必须通过命名与确认机制双重警示。不要把命令失败伪装成成功形态的结果。失败就是失败命令结果必须如实反映执行状态。不要从命令参数或结果中记录密钥secrets。日志脱敏是硬性要求命令相关的输入输出都必须防范敏感信息泄漏。不要把 Dashboard 的命令禁用机制当作唯一的并发防护。Dashboard 的禁用状态只是 UX 层提示真正的冲突防护必须在 controller 侧同样强制实现double-enforcement。在源码层面命令相关的模型集中在 ApplicationModel 目录ResourceCommandAnnotation命令注解模型、ResourceCommandService命令服务分别承载命令的定义与执行逻辑读者可结合 CommandsConfigurationExtensions.cs 查看命令如何注册到资源上。通知与日志Notifications and Logs应该做DO使用资源通知resource notifications发布用户需要看到的资源状态迁移。例如从启动中到运行中、再到已停止这些关键转变应通过通知通道及时推送给 Dashboard。使用资源日志服务resource logger services输出集成生成的设置日志与命令日志。从源码结构看ResourceNotificationService.cs 与 ResourceLoggerService.cs 分别承载通知与日志的管道它们是集成向 Dashboard 汇报状态的两条标准通道。保持日志可操作actionable并对密钥脱敏。日志的价值在于帮助排障任何一行无助于行动的日志都是噪音任何一行泄漏敏感信息的日志都是事故。对于合成/门面synthetic/facade类资源主动发布清晰的初始initial、启动中starting、运行中running、已停止stopped状态。因为这类资源没有 DCP 进程在背后自动维护状态状态机必须由集成自己驱动。当由人工管理manually managed的宿主资源停止时将其 URL 标记为失效inactive。URL 反映的是资源当前的可用性不能停留在历史状态。不应该做DONT不要对每个回调都输出无用的信息日志。回调频繁触发时噪音日志会淹没真正有价值的信号。不要在设置工作仍在进行时就提前完成资源日志。日志的完成语义必须与真实工作生命周期对齐否则会误导用户判断。不要为已不再转发或不可达的端点保留活跃的 Dashboard URL。URL 必须与端点的真实可达性保持一致。管理伴生资源Admin Companions管理/开发伴生资源例如管理后台 UI、运维控制台应该让用户感到它依附于其宿主服务而不是一个游离的独立容器。应该做DO添加父/自定义关系parent/custom relationships。在源码中关系通过WithRelationship与WithParentRelationship建立其定义位于 ResourceBuilderExtensions.cs 与 ResourceBuilderExtensions.cs。WithParentRelationship的本质是调用WithRelationship(resource, KnownRelationshipTypes.Parent)即追加一个ResourceRelationshipAnnotation并标注关系类型为Parent。Dashboard 据此把伴生资源渲染为父服务的从属节点。使用清晰的伴生命名。名称应直接点明它服务于哪个父资源例如myapp-admin而非让人猜测。除非有意支持否则将伴生资源排除在发布/部署输出之外。管理 UI 通常是开发态能力不应无意识地进入生产发布物。当工具管理多个父实例时优先采用单例式singleton-style伴生行为。即多个父实例共享一个伴生管理入口避免每个实例都拉起一份重复的管理组件。不应该做DONT不要让用户通过在一堆独立容器中逐个翻找来发现管理 UI。管理入口必须通过资源关系、URL 和命名系统性地暴露出来而不是靠运气。落地对照一份 Dashboard UX 检查清单将上述规范整合为集成作者在提交代码前可自检的清单图标核心资源是否设置了语义准确的WithIconNameFluentUI 图标名 Filled/Regular变体可见性内部设置、部署期资源是否已从 run model/manifest 中隐藏URL主 URL 是否展示在摘要健康检查、指标等次要 URL 是否下沉到详情页UrlDisplayLocation.DetailsOnly命令命令名是否以动词清晰描述动作前置条件是否映射为 disabled 状态是否尊重取消令牌破坏性命令是否有防护controller 侧是否独立强制并发约束日志与通知状态迁移是否通过资源通知发布设置/命令日志是否走资源日志服务且已脱敏合成资源的生命周期状态是否由集成主动驱动伴生资源管理 UI 是否通过WithParentRelationship挂在父资源下是否已从发布输出排除小结Dashboard UX 是托管集成质量的门面。这份规范从图标与展示、URL 策略、资源命令、通知日志到管理伴生资源给出了一整套可执行的设计准则其每一项 DO/DONT 都可以在 src/Aspire.Hosting 的ResourceBuilderExtensions、ApplicationModel注解模型ResourceIconAnnotation、ResourceUrlAnnotation、ResourceRelationshipAnnotation、ResourceCommandAnnotation以及ResourceNotificationService/ResourceLoggerService中找到对应的落地载体。遵循这些原则集成作者就能让用户在 Dashboard 中看到即理解、点击即安全、过程可追踪。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Aspire 托管集成开发指南：打造高质量 Dashboard UX（图标、URL、命令与日志设计规范）
Aspire 托管集成开发指南打造高质量 Dashboard UX图标、URL、命令与日志设计规范【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读本文以 Aspire 仓库中托管集成Hosting Integration开发技能的 Dashboard UX 设计规范为骨架系统讲解如何在为 Aspire 构建自定义资源与集成时设计出清晰、安全、可观测的仪表盘用户体验。你将掌握WithIconName图标与资源命名规范、WithUrlForEndpoint/WithUrls的 URL 展示策略、资源命令Resource Commands的安全设计要点以及通知、日志与管理伴生资源Admin Companion的最佳实践并对照 src/Aspire.Hosting 下的真实源码理解其底层机制。核心原则让资源不言自明托管集成Hosting Integration决定了用户在 Aspire Dashboard 中看到的一切。优秀的 Dashboard UX 应该让资源一目了然、无需暴露实现细节即可被理解。换句话说用户看到的是资源是什么、能做什么、怎么访问而不是它底层由哪些组件拼装而成。这份规范的核心出发点可以概括为两句话面向用户而非面向实现只展示用户需要看到、需要操作的资源与信息可操作、可观测、可取消凡是暴露给用户的操作都必须安全、清晰、可取消、可追踪。图标与资源展示Icons and Display应该做DO当存在与资源匹配的清晰图标时使用WithIconName设置图标。在源码中WithIconName定义于 ResourceBuilderExtensions.cs其实现是向资源追加一个ResourceIconAnnotation注解public static IResourceBuilderT WithIconNameT(this IResourceBuilderT builder, string iconName, IconVariant iconVariant IconVariant.Filled) where T : IResource { ArgumentNullException.ThrowIfNull(builder); ArgumentException.ThrowIfNullOrWhiteSpace(iconName); return builder.WithAnnotation(new ResourceIconAnnotation(iconName, iconVariant), ResourceAnnotationMutationBehavior.Replace); }从 ResourceIconAnnotation.cs 的实现可见iconName必须是有效的 FluentUI 系统图标名称iconVariant支持Regular或Filled两种变体默认使用Filled。ResourceAnnotationMutationBehavior.Replace意味着多次调用时后设置的图标会覆盖前者这为集成作者在默认图标基础上按需覆盖提供了明确语义。使用清晰的名字与关系让父子资源parent-child和伴生资源companion的关系一目了然。命名时应让用户仅凭名称即可判断资源的层级归属而不是靠点击查看详情才能推断。将纯内部设置、仅部署期存在的资源适当地排除在运行模型run model或清单manifest之外。这类资源例如部署脚本、内部初始化容器如果对用户没有操作价值就不应该出现在 Dashboard 的一级资源列表中。不应该做DONT不要把内部设置、仅部署期或实现类资源当作一级 Dashboard 资源展示除非用户确实需要对这些资源执行操作不要使用误导性的图标或过于通用的名称——当存在更清晰的资源身份时泛化命名会降低 Dashboard 的可读性。URL 展示策略应该做DO暴露面向用户的主 URL。每个资源的 URL 是用户与该资源交互的主要入口必须是用户真正会点击使用的地址。使用WithUrlForEndpoint调整某个端点的显示文本或展示位置。该方法在 ResourceBuilderExtensions.cs 中有两个重载第一个重载接收ActionResourceUrlAnnotation回调用于修改已存在端点的 URL 展示属性public static IResourceBuilderT WithUrlForEndpointT(this IResourceBuilderT builder, string endpointName, ActionResourceUrlAnnotation callback) where T : IResource { builder.WithUrls(context { var urlForEndpoint context.Urls.FirstOrDefault(u u.Endpoint?.EndpointName endpointName); if (urlForEndpoint is not null) { callback(urlForEndpoint); } else { context.Logger.LogWarning(Could not execute callback to customize endpoint URL as no endpoint with name {EndpointName} could be found on resource {ResourceName}., endpointName, builder.Resource.Name); } }); return builder; }第二个重载接收FuncEndpointReference, ResourceUrlAnnotation工厂用于新增一个与端点关联的 URL见 ResourceBuilderExtensions.cs。从 ResourceUrlAnnotation.cs 可以看到 URL 注解的完整字段Url链接目标、DisplayText链接文本、Endpoint关联的端点引用可为空、DisplayLocation展示位置默认为SummaryAndDetails以及已标记过时的DisplayOrder排序字段。其中DisplayLocation枚举定义了 URL 的两种展示层级取值含义SummaryAndDetails在资源摘要和资源详情两处都展示默认值DetailsOnly仅在资源详情页展示不进入资源摘要把诊断类、健康检查、指标或次要 URL 放进仅详情details-only展示避免污染资源摘要当用户被预期会打开管理端伴生 URL 时将其暴露出来详见下文管理伴生资源。不应该做DONT不要让内部端点淹没资源摘要。摘要区应保持克制只放用户高频使用的入口不要把健康检查端点当作主应用 URL 暴露。健康检查是运维细节不是业务入口放在详情页即可。资源命令Resource Commands资源命令是用户动作是 Dashboard 中用户能主动触发资源行为的主要途径。因此它们必须满足安全、清晰、可取消、可观测。应该做DO命令名与展示名都要准确描述动作。命令的命名应以动词开头、直白无歧义用户不需要阅读文档就能判断点了会发生什么。校验命令前置条件尽可能返回明确的禁用disabled/不可用unavailable状态。让用户在点击之前就知道当前状态下该命令是否可用而不是点击后才得到失败反馈。尊重取消令牌cancellation tokens。命令执行应响应取消请求避免用户无法中止耗时操作。这是命令可取消要求的直接落地。将有用的执行进度写入资源日志resource logs。用户执行命令后应在对应资源的日志中看到清晰的进度与结果形成闭环可观测。避免依赖隐藏的全局状态的命令。命令的可理解性与可测试性都要求其行为只取决于资源自身的状态与显式参数。对于 controller/reconciler 类集成命令的启用/禁用/隐藏状态应直接由 controller 的活动与排队操作状态推导。这是命令状态单一事实来源的要求——不要让 Dashboard 侧的逻辑猜测 controller 的内部状态。在变更类操作进行期间保持只读诊断类命令可用只要它们有助于恢复与排查。诊断命令不能因为正在变更就被一刀切禁用。为需要被 Agent 或用户检视的操作返回结构化命令结果structured command results便于自动化消费与审计。不应该做DONT不要添加命名含糊、缺少保护措施的破坏性命令。破坏性操作必须通过命名与确认机制双重警示。不要把命令失败伪装成成功形态的结果。失败就是失败命令结果必须如实反映执行状态。不要从命令参数或结果中记录密钥secrets。日志脱敏是硬性要求命令相关的输入输出都必须防范敏感信息泄漏。不要把 Dashboard 的命令禁用机制当作唯一的并发防护。Dashboard 的禁用状态只是 UX 层提示真正的冲突防护必须在 controller 侧同样强制实现double-enforcement。在源码层面命令相关的模型集中在 ApplicationModel 目录ResourceCommandAnnotation命令注解模型、ResourceCommandService命令服务分别承载命令的定义与执行逻辑读者可结合 CommandsConfigurationExtensions.cs 查看命令如何注册到资源上。通知与日志Notifications and Logs应该做DO使用资源通知resource notifications发布用户需要看到的资源状态迁移。例如从启动中到运行中、再到已停止这些关键转变应通过通知通道及时推送给 Dashboard。使用资源日志服务resource logger services输出集成生成的设置日志与命令日志。从源码结构看ResourceNotificationService.cs 与 ResourceLoggerService.cs 分别承载通知与日志的管道它们是集成向 Dashboard 汇报状态的两条标准通道。保持日志可操作actionable并对密钥脱敏。日志的价值在于帮助排障任何一行无助于行动的日志都是噪音任何一行泄漏敏感信息的日志都是事故。对于合成/门面synthetic/facade类资源主动发布清晰的初始initial、启动中starting、运行中running、已停止stopped状态。因为这类资源没有 DCP 进程在背后自动维护状态状态机必须由集成自己驱动。当由人工管理manually managed的宿主资源停止时将其 URL 标记为失效inactive。URL 反映的是资源当前的可用性不能停留在历史状态。不应该做DONT不要对每个回调都输出无用的信息日志。回调频繁触发时噪音日志会淹没真正有价值的信号。不要在设置工作仍在进行时就提前完成资源日志。日志的完成语义必须与真实工作生命周期对齐否则会误导用户判断。不要为已不再转发或不可达的端点保留活跃的 Dashboard URL。URL 必须与端点的真实可达性保持一致。管理伴生资源Admin Companions管理/开发伴生资源例如管理后台 UI、运维控制台应该让用户感到它依附于其宿主服务而不是一个游离的独立容器。应该做DO添加父/自定义关系parent/custom relationships。在源码中关系通过WithRelationship与WithParentRelationship建立其定义位于 ResourceBuilderExtensions.cs 与 ResourceBuilderExtensions.cs。WithParentRelationship的本质是调用WithRelationship(resource, KnownRelationshipTypes.Parent)即追加一个ResourceRelationshipAnnotation并标注关系类型为Parent。Dashboard 据此把伴生资源渲染为父服务的从属节点。使用清晰的伴生命名。名称应直接点明它服务于哪个父资源例如myapp-admin而非让人猜测。除非有意支持否则将伴生资源排除在发布/部署输出之外。管理 UI 通常是开发态能力不应无意识地进入生产发布物。当工具管理多个父实例时优先采用单例式singleton-style伴生行为。即多个父实例共享一个伴生管理入口避免每个实例都拉起一份重复的管理组件。不应该做DONT不要让用户通过在一堆独立容器中逐个翻找来发现管理 UI。管理入口必须通过资源关系、URL 和命名系统性地暴露出来而不是靠运气。落地对照一份 Dashboard UX 检查清单将上述规范整合为集成作者在提交代码前可自检的清单图标核心资源是否设置了语义准确的WithIconNameFluentUI 图标名 Filled/Regular变体可见性内部设置、部署期资源是否已从 run model/manifest 中隐藏URL主 URL 是否展示在摘要健康检查、指标等次要 URL 是否下沉到详情页UrlDisplayLocation.DetailsOnly命令命令名是否以动词清晰描述动作前置条件是否映射为 disabled 状态是否尊重取消令牌破坏性命令是否有防护controller 侧是否独立强制并发约束日志与通知状态迁移是否通过资源通知发布设置/命令日志是否走资源日志服务且已脱敏合成资源的生命周期状态是否由集成主动驱动伴生资源管理 UI 是否通过WithParentRelationship挂在父资源下是否已从发布输出排除小结Dashboard UX 是托管集成质量的门面。这份规范从图标与展示、URL 策略、资源命令、通知日志到管理伴生资源给出了一整套可执行的设计准则其每一项 DO/DONT 都可以在 src/Aspire.Hosting 的ResourceBuilderExtensions、ApplicationModel注解模型ResourceIconAnnotation、ResourceUrlAnnotation、ResourceRelationshipAnnotation、ResourceCommandAnnotation以及ResourceNotificationService/ResourceLoggerService中找到对应的落地载体。遵循这些原则集成作者就能让用户在 Dashboard 中看到即理解、点击即安全、过程可追踪。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考