设计与多媒体

winui-app

试用

搭建 WinUI 3 开发环境、用 C# 生成项目骨架,并完成构建、启动与验证。

它能做什么

面向 C# 与 Windows App SDK 的 WinUI 3 开发流程:先判断机器是否具备构建条件,再用技能自带的 WinGet 配置安装前置组件,通过 `dotnet new winui` 生成项目,最后用 `dotnet build` 加实际启动检查确认结果。任务会按类型分发到 13 个参考文件,涵盖外壳与导航、控件与自适应布局、主题与材质、无障碍、性能、CommunityToolkit、生命周期与部署以及评审清单。设计上优先使用 WinUI 原生控件,默认同时支持浅色与深色模式,并要求明确宽屏、中屏、手机宽度下的行为。

什么时候用它

  • 确认一台 Windows 电脑是否具备构建 WinUI 3 应用的工具链
  • 从命令行生成打包或非打包的 WinUI 3 新项目
  • 遇到 MSB3073 这类 XAML 编译器报错时回到模板骨架排查
  • 评审现有 WinUI 应用的结构、资源、绑定与无障碍支持

技能文档

WinUI App

Use this skill for WinUI 3 and Windows App SDK work that needs grounded setup guidance, app bootstrap, modern Windows UX decisions, or concrete implementation patterns.

Required Flow

  1. Classify the task as environment/setup, new-app bootstrap, design, implementation, review, or troubleshooting.
  2. If the task is about preparing a machine for WinUI, auditing readiness, or creating a brand new app, start with the bundled setup-and-scaffold flow in this skill before broader design, implementation, or troubleshooting work:
    • Pick the app name when the request is for a new app.
    • Use the exact name the user gave when it is already a safe folder name.
    • If the user did not give a name, derive a short PascalCase name from the request and state what you chose.
    • Create the project in the user's current workspace unless they asked for another location.
    • Do not use --force unless the user explicitly asked to overwrite existing files.
    • Run the bundled WinGet configuration from the skill directory so the relative path stays exactly config.yaml:
winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity
  • Treat the configuration as intended to enable Developer Mode, install or update Visual Studio Community 2026, and install the Managed Desktop, Universal, and Windows App SDK C# components needed for WinUI development.
  • Assess the configuration result before continuing. Continue on success. If it fails, inspect the output instead of guessing. If the winui template is already available and the toolchain is usable, note the partial failure and continue. If prerequisites are still missing, stop and report the blocker clearly.
  • Verify the template is available before scaffolding:
dotnet new list winui
  • For diagnostics-only environment requests, explain that the bundled bootstrap may change the machine and get confirmation before running it. If the user declines changes, use the manual verification guidance in references/foundation-environment-audit-and-remediation.md and summarize readiness under present, missing, uncertain, and recommended optional tools.
  • For a brand new app, scaffold with dotnet new winui -o . Add template options only when the user asked for them. Supported options: -f|--framework net10.0|net9.0|net8.0, -slnx|--use-slnx, -cpm|--central-pkg-mgmt, -mvvm|--use-mvvm, -imt|--include-mvvm-toolkit, -un|--unpackaged, -nsf|--no-solution-file, --force. Do not invent unsupported flags. If the user asks for packaged behavior, pass --unpackaged false. Otherwise keep the template default.
  • Verify a new scaffold by confirming the expected project file exists and running dotnet build against the generated .csproj.
  • Launch a newly scaffolded app through the correct path for its actual packaging model and confirm there is a real top-level window instead of relying only on the launcher process exit code.
  1. Read references/_sections.md, then load only the reference files that match the task.
  2. Make the packaging model explicit before creating or refactoring the app. Default to packaged for Store-like product workflows and Visual Studio deploy/F5 flows. Default to unpackaged when the user expects repeatable CLI build-and-run loops or direct .exe launches after each change.
  3. When the task is an opaque XAML compiler failure such as MSB3073 or XamlCompiler.exe, read references/foundation-template-first-recovery.md and simplify back toward the current dotnet new winui scaffold for the chosen packaging model before inventing custom recovery structure.
  4. For any work that creates or changes a WinUI app, make a complete but minimal edit set, then build the app and run it before responding to the user. Do this by default even when the user did not explicitly ask for verification. If a running app instance locks the output while more work remains, stop it, rebuild, relaunch, and continue verification. When the work is complete and launch verification succeeds, leave the final verified app instance running for the user unless they explicitly asked you not to.
  5. Treat launch verification as incomplete until the app shows objective success signals such as a responsive top-level window, expected window title, or other clear startup behavior. A spawned process by itself is not enough.
  6. Prefer Microsoft Learn for requirements, API expectations, and platform guidance.
  7. Prefer WinUI Gallery for concrete control usage, shell composition, and design details.
  8. Prefer WindowsAppSDK-Samples for scenario-level APIs such as windowing, lifecycle, notifications, deployment, and custom controls.
  9. Build toward WinUI and Fluent guidance first. Treat native WinUI shells, controls, interactions, and control chrome as the default implementation path.
  10. For grouped command surfaces such as document actions, editor formatting, view toggles, or page-level toolbars, favor a native CommandBar or other stock WinUI command surface before building a custom row with Grid, StackPanel, Border, or ad hoc button groupings.
  11. Do not invent app-specific controls, bespoke component libraries, or custom chrome to replace stock WinUI behavior unless the user explicitly asks for that customization, the existing product design system already requires it, or a verified platform gap leaves no clean native option.
  12. When customization is needed, first compose, template, or restyle built-in WinUI controls and system resources before adding CommunityToolkit dependencies or authoring a new custom control.
  13. Use CommunityToolkit only when built-in WinUI controls or helpers do not cover the need cleanly.
  14. Support both light and dark mode by default. Treat single-theme output as an exception that requires an explicit user request or an existing product constraint.
  15. Use theme-aware resources, system brushes, and WinUI styling hooks instead of hard-coded light-only or dark-only colors when building or revising UI.
  16. Make scroll ownership explicit for collection layouts. When a page already scrolls vertically, do not assume a nested GridView or other scroll-owning collection will still render a horizontal poster rail correctly.
  17. Do not add extra Border wrappers around sections, lists, or cards unless the border is doing distinct work that the contained control or parent surface does not already provide. Avoid "double-card" compositions where a section Border wraps child items that already render as cards.
  18. Treat responsiveness as a shell-plus-page problem, not only a control-resize problem. Plan explicit wide, medium, and phone-width behavior for navigation, padding, content density, and footer/tool regions, and simplify or hide nonessential UI as width shrinks.

Common Routes

RequestRead first
Check whether this PC can build WinUI appsreferences/foundation-environment-audit-and-remediation.md
Install missing WinUI prerequisitesreferences/foundation-environment-audit-and-remediation.md
Start a new packaged or unpackaged appreferences/foundation-setup-and-project-selection.md
Recover from opaque XAML compiler or startup failures while staying anchored to the template scaffoldreferences/foundation-template-first-recovery.md
Build, run, or verify that a WinUI app actually launchedreferences/build-run-and-launch-verification.md
Review app structure, pages, resources, and bindingsreferences/foundation-winui-app-structure.md
Choose shell, navigation, title bar, or multi-window patternsreferences/shell-navigation-and-windowing.md
Choose controls or responsive layout patternsreferences/controls-layout-and-adaptive-ui.md
Apply Mica, theming, typography, icons, or Fluent stylingreferences/styling-theming-materials-and-icons.md
Improve accessibility, keyboarding, or localizationreferences/accessibility-input-and-localization.md
Diagnose responsiveness or UI-thread performancereferences/performance-diagnostics-and-responsiveness.md
Decide whether to use CommunityToolkitreferences/community-toolkit-controls-and-helpers.md
Handle lifecycle, notifications, or deploymentreferences/windows-app-sdk-lifecycle-notifications-and-deployment.md
Run a review checklistreferences/testing-debugging-and-review-checklists.md

Environment Rules

  • Do not guess whether the machine is ready for WinUI development. Verify it.
  • Use the bundled setup-and-scaffold flow in this skill for fresh setup, remediation, and first-project scaffolding instead of delegating to another skill.
  • Treat config.yaml in this skill directory as the bundled bootstrap source of truth.
  • Treat uncertain environment signals as uncertain, not as success.
  • If the task is audit-only and the user declines machine changes, use the manual verification guidance in references/foundation-environment-audit-and-remediation.md and keep uncertain signals explicit instead of implying success.
  • If config.yaml is missing, say so clearly and fall back to the official Microsoft workflow instead of pretending the bundled path exists.
  • Keep environment readiness, packaging choice, and application startup verification as separate checks. Passing one does not prove the others.
  • Fail closed on ambiguous launch results. If the app did not clearly open, keep debugging.
  • After creating or editing a WinUI app, do not stop at a successful build. Launch the app, confirm objective startup behavior, and leave the final verified app instance running before returning control to the user unless they explicitly say not to run it.

Reference Rules

  • Keep C# as the primary path. Mention C++ or C++/WinRT only when the difference is material.
  • Preserve the conventions of an existing codebase instead of forcing a generic sample structure onto it.
  • Treat WinUI design guidance and native controls as the baseline. Do not drift into bespoke component systems or app-specific replacements for standard controls unless the user explicitly requests them or the existing codebase already depends on them.
  • Support light and dark mode by default for app UI work unless the user explicitly asks for a single-theme result or the product already enforces one.
  • Favor built-in WinUI controls and system styling hooks before adding CommunityToolkit dependencies, custom controls, or app-specific surface systems.
  • Put detailed control, theming, shell, scrolling, responsiveness, packaging, and recovery guidance in the matching reference files instead of duplicating those rules here.

常见问题

它会往我的机器上装东西吗?
只有运行自带的安装流程时才会。该流程执行 `winget configure -f config.yaml`,用途是开启开发者模式,并安装或更新带 WinUI C# 组件的 Visual Studio Community 2026。如果只是环境审计,技能会先征求确认;你拒绝改动时改用参考文件里的手动核查指引。
生成项目时支持哪些模板参数?
基础命令是 `dotnet new winui -o `,只在你明确要求时才追加参数:框架(net10.0、net9.0、net8.0)、`--use-slnx`、`--central-pkg-mgmt`、`--use-mvvm`、`--include-mvvm-toolkit`、`--unpackaged`、`--no-solution-file`。不会自行编造不存在的参数。
它会验证应用真的跑起来了吗?
会。创建或修改应用后,它会构建、启动并检查客观的启动信号,例如顶层窗口是否响应、窗口标题是否符合预期,而不是只看启动进程的退出码。启动结果不明确时会继续排查。

相关技能

以 AI 机器人身份加入视频会议,提供语音、虚拟形象与屏幕共享四种模式。

作者 johnpatternai22 次安装8 星标

docx

官方

用脚本和 XML 创建、编辑、读取并校验 Word 的 .docx 与 .dotx 文件。

作者 Anthropic197.6k 星标

pdf

官方

用 Python 库和命令行工具读取、提取、合并、拆分、旋转、加水印、加密和生成 PDF。

作者 Anthropic197.6k 星标

搭建、重构和排查由 MCP 服务器加 widget 界面组成的 ChatGPT Apps SDK 应用。

作者 OpenAI28.8k 星标

用已发布的设计系统组件、变量和样式,把代码或描述转成完整的 Figma 页面并持续更新。

作者 OpenAI28.8k 星标

OpenAI 的更多技能

浏览全部技能

搭建、重构和排查由 MCP 服务器加 widget 界面组成的 ChatGPT Apps SDK 应用。

作者 OpenAI28.8k 星标

用已发布的设计系统组件、变量和样式,把代码或描述转成完整的 Figma 页面并持续更新。

作者 OpenAI28.8k 星标

把代码库里的设计系统按阶段搬进 Figma,每个阶段停下来等你确认。

作者 OpenAI28.8k 星标

figma-use

官方

在 Figma 文件里通过 Plugin API 执行 JavaScript,并避开那些让脚本报错的坑。

作者 OpenAI28.8k 星标

hatch-pet

官方

把概念、品牌线索或参考图做成经过校验的 8x9 动画 Codex 宠物图集。

作者 OpenAI28.8k 星标

imagegen

官方

在编码项目里生成或编辑位图图像,把需求整理成结构化提示词,并把成品保存进工作区。

作者 OpenAI28.8k 星标