Skip to content

AGENTS.md

Latest commit

 

History

History
127 lines (91 loc) · 5.29 KB

AGENTS.md

File metadata and controls

127 lines (91 loc) · 5.29 KB
Raw

AGENTS.md

DesktopFlyouts is a WinUI library for showing lightweight desktop flyouts, menu flyouts, and tray-icon driven UI from desktop apps. It ships three public library flavors:

Code Structure

.
├───DesktopFlyouts.slnx
├───src
│   ├───DesktopFlyouts.Shared
│   │   └───DesktopFlyouts.Shared.shproj
│   ├───DesktopFlyouts.WinUI
│   │   └───DesktopFlyouts.WinUI.csproj
│   ├───DesktopFlyouts.Uwp
│   │   └───DesktopFlyouts.Uwp.csproj
│   └───DesktopFlyouts.Uno
│       └───DesktopFlyouts.Uno.csproj
└───samples
    ├───DesktopFlyouts.WinUI.SampleApp
    │   └───DesktopFlyouts.WinUI.SampleApp.csproj
    ├───DesktopFlyouts.Uwp.SampleApp
    │   └───DesktopFlyouts.Uwp.SampleApp.csproj
    ├───DesktopFlyouts.Uwp.Sample.Packaging
    │   └───DesktopFlyouts.Uwp.Sample.Packaging.wapproj
    └───DesktopFlyouts.Uwp.Sample.TrayHost
        └───DesktopFlyouts.Uwp.Sample.TrayHost.csproj

Most runtime behavior lives in src/DesktopFlyouts.Shared behind #if WASDK, #if UWP, and #if HAS_UNO. Keep all branches building when changing shared files.

Keep in mind that for Uno Platform, WASDK and HAS_UNO will both be true.

Formatting And Editing Rules

  • This repo uses CRLF. Preserve CRLF for every changed text file.
  • .editorconfig sets UTF-8, CRLF, final newline, spaces, and 4-space indentation.
  • .gitattributes enforces text=auto eol=crlf.
  • Use existing patterns and dependency property generation style. Avoid broad refactors while fixing focused behavior.
  • Do not edit generated bin, obj, or Generated Files output.

Build Commands

Run validation one command at a time and inspect each result before moving on. WinUI and UWP builds require Windows; skip them on other platforms.

  1. Build the Uno library (cross-platform):
dotnet msbuild /restore:false src/DesktopFlyouts.Uno/DesktopFlyouts.Uno.csproj /p:Configuration=Debug /p:Platform=x64 /p:AppxBundle=Never
  1. Build the WinUI 3 sample and library (Windows only):
dotnet msbuild /restore:false samples\DesktopFlyouts.WinUI.SampleApp\DesktopFlyouts.WinUI.SampleApp.csproj /p:Configuration=Debug /p:Platform=x64 /p:AppxBundle=Never
  1. Build the UWP library (Windows only):
dotnet msbuild /restore:false src\DesktopFlyouts.Uwp\DesktopFlyouts.Uwp.csproj /p:Configuration=Debug /p:Platform=x64 /p:AppxBundle=Never
  1. Check whitespace and line endings:
git diff --check
git ls-files --eol

NETSDK1057 preview SDK messages can appear on this machine. Treat them as environment notices unless accompanied by a build failure.

Packaged App Debugging And Launch

The WinUI sample is a packaged app. Do not validate launch by running the built .exe directly with Start-Process or dotnet run. That path can fail with REGDB_E_CLASSNOTREG. Use a package-aware launch path.

After building the WinUI sample, register the generated package manifest and launch through shell:AppsFolder.

$manifest = Join-Path (Get-Location) 'samples\DesktopFlyouts.WinUI.SampleApp\bin\x64\Debug\net10.0-windows10.0.26100.0\AppxManifest.xml'
Add-AppxPackage -Register $manifest -DisableDevelopmentMode

$package = Get-AppxPackage -Name 'd6120692-1c26-4251-b686-e2321694e3b0'
Start-Process "shell:AppsFolder\$($package.PackageFamilyName)!App"

Start-Sleep -Seconds 5
Get-Process -Name DesktopFlyouts.WinUI.SampleApp -ErrorAction SilentlyContinue |
    Select-Object Id, ProcessName, MainWindowHandle, Responding, HasExited

A successful launch should show a live DesktopFlyouts.WinUI.SampleApp process with Responding = True and a non-zero MainWindowHandle.

Debugging

Use Event Viewer for startup and packaged-launch failures. Check Windows Logs > Application first, especially .NET Runtime event 1026, Application Error event 1000, and Windows Error Reporting event 1001.

From PowerShell, read the same Application log with:

Get-WinEvent -FilterHashtable @{LogName='Application'; StartTime=(Get-Date).AddMinutes(-10)} |
    Where-Object { $_.Message -match 'DesktopFlyouts.WinUI.SampleApp|DesktopFlyouts' } |
    Select-Object -First 10 TimeCreated, ProviderName, Id, LevelDisplayName, Message |
    Format-List

If the log shows 0x80040154 REGDB_E_CLASSNOTREG from WindowsAppRuntime.DeploymentInitializeOptions, treat it as an invalid unpackaged/direct .exe launch path before blaming app code. Re-run the packaged launch steps above.

Stop running samples before rebuilding if output files are locked:

Get-Process -Name DesktopFlyouts.WinUI.SampleApp -ErrorAction SilentlyContinue | Stop-Process -Force

Validation Checklist

Validate one item at a time:

  1. git status --short --branch to understand the current branch and dirty files.
  2. Build the Uno library.
  3. Build the WinUI sample (Windows only).
  4. Build the UWP library when shared code changed (Windows only).
  5. Launch the WinUI sample as packaged, never by direct .exe (Windows only).
  6. Confirm the app has a responsive process and real window handle (Windows only).
  7. Run git diff --check.
  8. Confirm changed text files remain CRLF.
  9. Summarize what was changed, what was validated, and any remaining risk.