Skip to content
Back to search

desktopmanager-local

MarketplaceWorks with Claude CodeGitHub

DesktopManager is a C# library and PowerShell module that allows to get and set wallpapers to given monitor.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/EvotecIT/DesktopManager with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/EvotecIT/DesktopManager'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/evotecit--desktopmanager/badge.svg)](/listings/evotecit--desktopmanager)

HTML

<a href="/listings/evotecit--desktopmanager"><img src="/api/listings/evotecit--desktopmanager/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For using in PowerShell you can install it from PowerShell Gallery

Install-Module DesktopManager -Force -Verbose

For the daily Windows tray app, use the DesktopManager MSI release artifact when available. The installer creates a Start Menu shortcut, and the app's Startup toggle registers the current user for minimized tray startup.

From source, the app and MSI are built through PowerForge:

.\Build\Build-DesktopManagerApp.ps1
.\Build\Build-DesktopManagerApp-MSI.ps1
msiexec.exe /i .\Artefacts\PowerForge\Msi\DesktopManager.App\win-x64\net10.0-windows10.0.19041.0\PortableCompat\output\DesktopManager.msi

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "desktopmanager-local",
  3. "owner": { "name": "EvotecIT" },
  4. "metadata": { "description": "Windows desktop inspection and verification through DesktopManager." },
  5. "plugins": [
  6. {
  7. "name": "desktopmanager-windows-verification",
  8. "source": "./plugins/desktopmanager-windows-verification",
  9. "description": "Inspect Windows apps and verify authorized interactions with screenshots and control evidence."
  10. }
  11. ]
  12. }
README.MD · README · 818 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DesktopManager - C# Library and PowerShell Module
  2. DesktopManager is a Windows desktop automation toolkit available as a .NET library, PowerShell module, CLI, MCP server, and tray app.
  3. The .NET library also exposes `PortableDesktopService` for current-user wallpaper, display discovery,
  4. and session diagnostics on Windows, macOS, GNOME, and KDE Plasma. Each adapter reports its capabilities;
  5. the window automation, tray app, CLI, and existing PowerShell commands retain their Windows scope.
  6. See [Portable desktop integration](Docs/Portable.Desktop.md) for usage and platform limits.
  7. The .NET 8 and .NET 10 library targets support trimming and Native AOT, including Core Audio,
  8. wallpaper and monitor enumeration, Explorer folder capture, virtual desktops and UI Automation.
  9. The .NET Framework and .NET Standard targets retain their legacy interop paths.
  10. See [Native AOT qualification](Sources/DesktopManager.AotSmoke/README.md) for the contributor smoke consumer.
  11. Threaded services use bounded kernel-event waits for startup and synchronous worker calls, including STA callers.
  12. Startup normally has a five-second deadline; wallpaper/audio COM calls have a fifteen-second completion deadline,
  13. and hotkey registration and clipboard writes have five seconds. UI Automation respects its invocation deadline.
  14. A timeout cancels work that has not started. `NativeOperationOutcomeUnknownException` means a native operation
  15. is already running and may still apply its change: inspect the target before retrying a mutation. An in-flight
  16. native call cannot be terminated safely; its thread retains ownership and performs late-result cleanup.
  17. [![nuget downloads](https://img.shields.io/nuget/dt/DesktopManager?label=nuget%20downloads)](https://www.nuget.org/packages/DesktopManager)
  18. [![nuget version](https://img.shields.io/nuget/v/DesktopManager)](https://www.nuget.org/packages/DesktopManager)
  19. You can also download it from PowerShell Gallery
  20. [![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/DesktopManager.svg?style=flat-square)](https://www.powershellgallery.com/packages/DesktopManager)
  21. [![PowerShell Gallery Preview Version](https://img.shields.io/powershellgallery/v/DesktopManager.svg?label=powershell%20gallery%20preview&colorB=yellow&style=flat-square&include_prereleases)](https://www.powershellgallery.com/packages/DesktopManager)
  22. [![PowerShell Gallery Downloads](https://img.shields.io/powershellgallery/dt/DesktopManager.svg?style=flat-square)](https://www.powershellgallery.com/packages/DesktopManager)
  23. [![PowerShell Gallery Platform](https://img.shields.io/powershellgallery/p/DesktopManager.svg?style=flat-square)](https://www.powershellgallery.com/packages/DesktopManager)
  24. [![GitHub top language](https://img.shields.io/github/languages/top/evotecit/DesktopManager.svg?style=flat-square)](https://github.com/EvotecIT/DesktopManager)
  25. [![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/evotecit/DesktopManager.svg?style=flat-square)](https://github.com/EvotecIT/DesktopManager)
  26. [![GitHub license](https://img.shields.io/github/license/EvotecIT/DesktopManager.svg?style=flat-square)](https://github.com/EvotecIT/DesktopManager)
  27. If you would like to contact me you can do so via Twitter or LinkedIn.
  28. [![Twitter Follow](https://img.shields.io/twitter/follow/PrzemyslawKlys.svg?label=Twitter%20%40PrzemyslawKlys&style=social)](https://twitter.com/PrzemyslawKlys)
  29. [![Blog evotec.xyz](https://img.shields.io/badge/Blog-evotec.xyz-2A6496.svg)](https://evotec.xyz/hub)
  30. [![LinkedIn pklys](https://img.shields.io/badge/LinkedIn-pklys-0077B5.svg?logo=LinkedIn)](https://www.linkedin.com/in/pklys)
  31. [![Discord](https://img.shields.io/discord/508328927853281280?style=flat-square&label=discord%20chat)](https://evo.yt/discord)
  32. [![Threads @PrzemyslawKlys](https://img.shields.io/badge/Threads-@PrzemyslawKlys-000000.svg?logo=Threads&logoColor=White)](https://www.threads.net/@przemyslaw.klys)
  33. ## What it's all about
  34. <img height="256" align="right" src="Assets/Images/DesktopManager.jpg">
  35. DesktopManager provides one shared Windows automation core through five surfaces:
  36. - **C# library** for .NET applications and services
  37. - **PowerShell module** for scripts and operator workflows
  38. - **CLI executable** for terminal and JSON automation
  39. - **MCP server** for inspect-first agent automation
  40. - **Windows tray app** for daily hotkeys and monitor actions
  41. It has following features:
  42. - Get information about monitors
  43. - Get information about display devices
  44. - Get information about wallpapers
  45. - Set wallpapers
  46. - Get/Set desktop background color
  47. - Get/Set monitor position
  48. - Get/Set window position
  49. - Get/Set window state (minimize, maximize, restore)
  50. - Capture desktop screenshots from all monitors, a single monitor or a custom region
  51. - Manage monitor brightness
  52. - Start/Stop/Advance wallpaper slideshows
  53. - Track wallpaper history
  54. - Adjust monitor resolution and orientation
  55. - Move monitors around the virtual desktop
  56. - Save and restore window layouts
  57. - Snap or move windows between monitors
  58. - Subscribe to resolution, orientation or display changes
  59. - Keep inactive windows awake using periodic input
  60. - Manage keep-alive sessions for windows
  61. - Save and restore cohesive workstation profiles across displays, audio, personalization, and taskbars
  62. - Enumerate Core Audio render/capture endpoints, change volume and mute, set default roles, and observe endpoint changes
  63. - Inspect power and interactive-session state; lock, sign out, sleep, hibernate, or hold a bounded keep-awake lease
  64. - Capture and restore personalization snapshots and configure taskbar visibility, position, and auto-hide
  65. - Enumerate, observe, and explicitly enable or disable Wi-Fi, Bluetooth, mobile broadband, and FM radios through the supported Windows radio API
  66. - List saved Windows Wi-Fi profiles and connect an exact saved profile without scanning nearby networks or exposing credentials
  67. - Inspect a window's virtual desktop and move it to a known desktop through the public Windows virtual-desktop API
  68. - Inspect and manage Plug and Play devices and Driver Store packages through documented native Windows APIs
  69. ### Wallpaper consumers
  70. Applications such as [PowerBGInfo](https://github.com/EvotecIT/PowerBGInfo) can read monitor geometry,
  71. display scale and the signed-in session user directly from the library:
  72. ```csharp
  73. using DesktopManager;
  74. var monitors = new Monitors();
  75. foreach (var display in monitors.GetMonitorSnapshots()) {
  76. Console.WriteLine($"{display.Index}: {display.DeviceName}, " +
  77. $"{display.Width} x {display.Height}, scale {display.Scale}");
  78. }
  79. var user = new DesktopSessionService().GetSessionUser();
  80. Console.WriteLine(user?.AccountName ?? "Unknown");
  81. ```
  82. Snapshots contain physical pixel bounds and per-monitor DPI even when the caller is not DPI aware.
  83. The calling thread's DPI context is restored. Indexes describe the current display topology; read
  84. them again after docking or reconnecting. Missing wallpaper device paths on session hosts are retained.
  85. `Monitors.SetLogonWallpaperWithResult(imagePath)` sets the current account's lock screen through
  86. Windows Runtime on .NET Framework, modern .NET and netstandard consumers. The result reports success,
  87. the mechanism used and any failure. Machine policy fallback requires an explicit
  88. `allowPolicyFallback: true` and elevation. The existing `SetLogonWallpaper` method keeps its automatic
  89. policy fallback. See [Wallpaper consumer APIs](Docs/Wallpaper.Consumers.md) for examples, OS requirements,
  90. policy limits and session deployment behavior.
  91. ### Desktop state and controls
  92. The workstation profile is the high-level entrypoint when you want to move between repeatable setups. It captures connected monitor modes and placement, monitor wallpaper and supported brightness/HDR state, active audio endpoint state and default roles, personalization, and taskbars. Applying a profile matches monitors by stable identity, stages display changes together, and rolls back the selected sections when a required step fails. Machine-wide personalization policies are captured but only restored when explicitly requested.
  93. ```powershell
  94. Save-DesktopWorkstationProfile -Name 'office'
  95. Get-DesktopAudioEndpoint -DataFlow Render -ActiveOnly
  96. Get-DesktopPowerStatus
  97. Get-DesktopSession
  98. Get-DesktopRadio
  99. Get-DesktopWifiProfile
  100. Connect-DesktopWifiProfile -Name 'Corporate WiFi'
  101. Get-DesktopDevice -Present -Problem
  102. Get-DesktopDriverPackage
  103. Restore-DesktopWorkstationProfile -Name 'office' -Confirm
  104. ```
  105. The same capabilities are available from the CLI:
  106. ```text
  107. desktopmanager workstation save --name office
  108. desktopmanager audio list --flow render --active
  109. desktopmanager system power
  110. desktopmanager system session
  111. desktopmanager radio list
  112. desktopmanager wifi profiles
  113. desktopmanager wifi connect --profile "Corporate WiFi"
  114. desktopmanager device list --present --problem
  115. desktopmanager driver list
  116. desktopmanager workstation apply --name office
  117. ```
  118. Radio control has two deliberately separate APIs. `RadioService` and the normal `radio list` / `radio set` commands use the supported `Windows.Devices.Radios` contract for individual radios. Global airplane mode uses an undocumented Windows shell COM contract, so it lives under `ExperimentalAirplaneModeService` and requires `--experimental` in the CLI, `-Experimental` in PowerShell, or `--allow-experimental` in MCP.
  119. Wi-Fi profile connection is separate from radio control. `WifiProfileService`, `Get-DesktopWifiProfile`, and `desktopmanager wifi profiles` enumerate only profiles already stored by Windows. Connecting an exact profile uses the Native Wi-Fi profile API and ACM completion notifications; it does not scan nearby networks, return BSSIDs, expose profile XML or credentials, or query location-sensitive current-connection details. Windows still requires location consent for nearby-network scanning and related Wi-Fi information APIs. See [Changes to API behavior for Wi-Fi access and location](https://learn.microsoft.com/windows/win32/nativewifi/wi-fi-access-location-changes).
  120. `VirtualDesktopService` exposes only the public Windows operations: check whether a top-level window is on the current desktop, get its desktop ID, and move it to a known desktop ID. Desktop enumeration, creation, renaming, switching, and removal are intentionally not presented as supported APIs.
  121. Additional operator-focused docs for the newer CLI and MCP surfaces:
  122. - [Docs/DesktopManager.Cli.md](Docs/DesktopManager.Cli.md)
  123. - [Docs/DesktopManager.Mcp.md](Docs/DesktopManager.Mcp.md)
  124. - [Docs/DesktopManager.Architecture.md](Docs/DesktopManager.Architecture.md)
  125. - [Docs/DesktopManager.DesktopState.md](Docs/DesktopManager.DesktopState.md)
  126. - [Docs/DesktopManager.DeviceManagement.md](Docs/DesktopManager.DeviceManagement.md)
  127. - [Docs/DesktopManager.AutomationBasics.md](Docs/DesktopManager.AutomationBasics.md)
  128. - [Docs/DesktopManager.Plugin.md](Docs/DesktopManager.Plugin.md)
  129. - [.agents/skills/desktopmanager-operator/SKILL.md](.agents/skills/desktopmanager-operator/SKILL.md)
  130. - [.agents/skills/desktopmanager-build/SKILL.md](.agents/skills/desktopmanager-build/SKILL.md)
  131. ## Which Surface Should You Use?
  132. | Surface | Best for | Typical entrypoint |
  133. | ------- | -------- | ------------------ |
  134. | C# library | Embedding DesktopManager into your own .NET app or service | `DesktopManager.dll` |
  135. | PowerShell module | Scripts, operators, admin workflows, repeatable task automation | `Install-Module DesktopManager` |
  136. | CLI executable | Manual use, shell automation, JSON output, and MCP hosting | `desktopmanager.exe` |
  137. | MCP server | Agent-driven automation over stdio with an inspect-first safety model | `desktopmanager mcp serve` |
  138. | Windows tray app | Daily hotkeys, monitor bindings, HDR controls, tray runtime, and per-user startup | `DesktopManager.App.exe` |
  139. ## How It Fits Together
  140. DesktopManager now has one shared core and several operator-facing surfaces on top of it.
  141. ```mermaid
  142. flowchart LR
  143. A["Your .NET app"] --> B["DesktopManager library"]
  144. C["PowerShell module"] --> B
  145. D["desktopmanager.exe CLI"] --> B
  146. E["MCP server"] --> D
  147. J["DesktopManager.App tray app"] --> B
  148. B --> F["Windows desktop APIs"]
  149. F --> G["Monitors / wallpapers / brightness"]
  150. F --> H["Windows / controls / input"]
  151. F --> I["Layouts / snapshots / targets"]
  152. ```
  153. If you want the fuller component and request-flow diagrams, see [Docs/DesktopManager.Architecture.md](Docs/DesktopManager.Architecture.md).
  154. The practical way to think about this:
  155. - use the library when DesktopManager is part of your own application
  156. - use PowerShell when you want scriptable admin/operator automation
  157. - use the CLI when you want a human-friendly or JSON-friendly command surface
  158. - use MCP when an agent should inspect first and mutate only through an explicit server session
  159. ## Common Entry Points
  160. | Goal | Recommended entrypoint |
  161. | ---- | ---------------------- |
  162. | Add DesktopManager features to your own code | Reference the `DesktopManager` NuGet package |
  163. | Run manual desktop operations from a terminal | `desktopmanager.exe` |
  164. | Run DesktopManager every day from the tray | `DesktopManager.App.exe` or the DesktopManager MSI |
  165. | Use it from PowerShell scripts | `DesktopManager` PowerShell module |
  166. | Connect an agent/tooling layer | `desktopmanager mcp serve` |
  167. | Understand the overall wiring | [Docs/DesktopManager.Architecture.md](Docs/DesktopManager.Architecture.md) |
  168. ## Request Flow at a Glance
  169. ```mermaid
  170. flowchart LR
  171. A["User, script, or agent"] --> B{"Surface"}
  172. B -->|".NET"| C["DesktopManager library"]
  173. B -->|"PowerShell"| D["Cmdlets"]
  174. B -->|"CLI"| E["desktopmanager.exe"]
  175. B -->|"MCP"| F["desktopmanager mcp serve"]
  176. B -->|"Tray app"| J["DesktopManager.App.exe"]
  177. D --> C
  178. E --> G["DesktopOperations"]
  179. F --> G
  180. J --> C
  181. G --> C
  182. C --> H["Win32, UI Automation, monitor, screenshot, and input services"]
  183. ```
  184. The important part is that CLI, MCP, and PowerShell are meant to stay aligned by reusing the same shared C# behavior rather than inventing separate desktop logic in each surface.
  185. ### Available PowerShell Cmdlets
  186. | Cmdlet | Description |
  187. | ------ | ----------- |
  188. | Get-DesktopMonitor | Retrieve monitor information with filtering options |
  189. | Get-DesktopWallpaper | Get current wallpaper path for monitors |
  190. | Set-DesktopWallpaper | Apply wallpaper from path, URL or stream |
  191. | Get-DesktopWallpaperHistory | List stored wallpaper history entries |
  192. | Set-DesktopWallpaperHistory | Update or clear wallpaper history file |
  193. | Get-DesktopSlideshow | Inspect slideshow images, state, options and tick interval |
  194. | Set-DesktopSlideshowOptions | Update slideshow shuffle behavior and tick interval |
  195. | Start-DesktopSlideshow | Begin wallpaper slideshow across monitors |
  196. | Stop-DesktopSlideshow | Stop currently running slideshow |
  197. | Step-DesktopSlideshow | Move slideshow forward or backward |
  198. | Get-DesktopBackgroundColor | Read current desktop background color |
  199. | Set-DesktopBackgroundColor | Change desktop background color |
  200. | Get-DesktopBrightness | Read monitor brightness level |
  201. | Set-DesktopBrightness | Set monitor brightness level |
  202. | Set-DesktopPosition | Move a monitor by its top-left coordinates without changing resolution |
  203. | Set-DesktopResolution | Change monitor resolution or orientation |
  204. | Set-DefaultAudioDevice | Set the default audio playback device |
  205. | Get-DesktopAudioEndpoint | List Core Audio render and capture endpoints with volume, mute, and default roles |
  206. | Set-DesktopAudioEndpoint | Set endpoint volume, mute, or selected default roles |
  207. | Register-DesktopAudioEvent | Subscribe to endpoint, state, property, and default-role changes |
  208. | Save-DesktopWorkstationProfile | Capture displays, audio, personalization, and taskbars as one named profile |
  209. | Get-DesktopWorkstationProfile | List or load named workstation profiles |
  210. | Restore-DesktopWorkstationProfile | Apply a named workstation profile with matching and rollback options |
  211. | Remove-DesktopWorkstationProfile | Delete a named workstation profile |
  212. | Get-DesktopPowerStatus | Read AC and battery state |
  213. | Get-DesktopSession | Read current interactive-session identity, connection, lock, and idle state |
  214. | Register-DesktopSessionEvent | Subscribe to meaningful session changes |
  215. | Lock-DesktopSession | Lock the current Windows session |
  216. | Exit-DesktopSession | Sign out the current Windows session with confirmation support |
  217. | Start-DesktopKeepAwake | Hold a bounded system/display keep-awake lease |
  218. | Suspend-DesktopSystem | Request sleep or hibernation with confirmation support |
  219. | Get-DesktopPersonalization | Capture current state or list/load saved personalization snapshots |
  220. | Save-DesktopPersonalization | Save a named personalization snapshot |
  221. | Set-DesktopPersonalization | Apply explicit personalization settings |
  222. | Restore-DesktopPersonalization | Restore a named personalization snapshot |
  223. | Remove-DesktopPersonalization | Delete a named personalization snapshot |
  224. | Get-DesktopTaskbar | List taskbars with monitor mapping, visibility, edge, and bounds |
  225. | Set-DesktopTaskbarAutoHide | Set the explicit taskbar auto-hide state |
  226. | Get-DesktopRadio | List radios through the supported Windows radio API |
  227. | Set-DesktopRadio | Explicitly enable or disable matching supported radios |
  228. | Register-DesktopRadioEvent | Subscribe to supported radio state changes |
  229. | Get-DesktopWifiProfile | List saved Windows Wi-Fi profiles without scanning nearby networks |
  230. | Connect-DesktopWifiProfile | Connect an exact saved Windows Wi-Fi profile |
  231. | Get-DesktopAirplaneMode | Read the experimental global airplane-mode state after explicit acknowledgement |
  232. | Set-DesktopAirplaneMode | Apply and verify experimental global airplane mode after explicit acknowledgement |
  233. | Get-DesktopVirtualDesktop | Inspect the supported virtual-desktop state for a top-level window |
  234. | Move-DesktopWindowToVirtualDesktop | Move a top-level window to a known virtual-desktop ID |
  235. | Get-LogonWallpaper | Get the lock screen wallpaper path |
  236. | Set-LogonWallpaper | Set the lock screen wallpaper |
  237. | Set-TaskbarPosition | Move or hide the taskbar |
  238. | Invoke-DesktopMouseMove | Move the mouse cursor |
  239. | Invoke-DesktopMouseClick | Simulate a mouse click |
  240. | Invoke-DesktopMouseScroll | Scroll the mouse wheel |
  241. | Invoke-DesktopScreenshot | Capture monitor or region screenshots |
  242. | Get-DesktopWindow | Enumerate visible windows |
  243. | Get-DesktopWindowGeometry | Return outer-window and client-area geometry for matched windows |
  244. | Get-DesktopWindowControl | Enumerate Win32 or UIA window controls |
  245. | Get-DesktopWindowControlDiagnostic | Explain Win32 vs UIA control discovery and actionability |
  246. | Get-DesktopWindowProcessInfo | Return process details for matched windows |
  247. | Get-DesktopWindowTarget | List saved window-relative targets or resolve one against live windows |
  248. | Get-DesktopControlTarget | List saved control targets or resolve one against live windows |
  249. | Get-DesktopHostedSessionDiagnostic | Read the latest hosted-session typing diagnostic artifact or a specific one |
  250. | Invoke-DesktopControlClick | Click a matched control using shared control action routing |
  251. | Invoke-DesktopWindowClick | Click a window-relative point or saved window target |
  252. | Invoke-DesktopWindowDrag | Drag between window-relative points or saved targets |
  253. | Invoke-DesktopWindowScroll | Scroll at a window-relative point or saved target |
  254. | Send-DesktopControlKey | Send keys to a matched control without reimplementing key routing |
  255. | Set-DesktopControlTarget | Save a reusable control selector profile |
  256. | Set-DesktopControlText | Write text directly to a specific control |
  257. | Set-DesktopWindow | Move, resize or control windows |
  258. | Set-DesktopWindowSnap | Snap window to common positions |
  259. | Set-DesktopWindowTarget | Save a reusable window-relative point target |
  260. | Set-DesktopWindowText | Paste or type text into a window |
  261. | Wait-DesktopWindow | Wait for a window to appear |
  262. | Wait-DesktopWindowControl | Wait for a control to appear |
  263. | Test-DesktopWindow | Verify that a window exists or matches the active window |
  264. | Test-DesktopWindowControl | Verify that a control exists |
  265. | Start-DesktopWindowKeepAlive | Send periodic input to keep a window awake |
  266. | Stop-DesktopWindowKeepAlive | Stop sending keep-alive input |
  267. | Get-DesktopWindowKeepAlive | List windows with active keep-alive |
  268. | Save-DesktopWindowLayout | Save current window layout to file |
  269. | Restore-DesktopWindowLayout | Restore saved window layout |
  270. | Register-DesktopMonitorEvent | Subscribe to display configuration changes |
  271. | Register-DesktopOrientationEvent | Subscribe to orientation changes |
  272. | Register-DesktopResolutionEvent | Subscribe to resolution changes |
  273. ### Cmdlet to C# method map
  274. The table below shows the most relevant API methods behind each PowerShell cmdlet.
  275. | Cmdlet | Main C# methods |
  276. | ------ | --------------- |
  277. | Get-DesktopMonitor | `Monitors.GetMonitors` |
  278. | Get-DesktopWallpaper | `Monitors.GetWallpaper` or `Monitor.GetWallpaper` |
  279. | Set-DesktopWallpaper | `Monitors.SetWallpaper`, `Monitors.SetWallpaperFromUrl` |
  280. | Get-DesktopWallpaperHistory | `WallpaperHistory.GetHistory` |
  281. | Set-DesktopWallpaperHistory | `WallpaperHistory.SetHistory` |
  282. | Get-DesktopSlideshow | `Monitors.GetWallpaperSlideshow` |
  283. | Set-DesktopSlideshowOptions | `Monitors.SetWallpaperSlideshowOptions` |
  284. | Start-DesktopSlideshow | `Monitors.StartWallpaperSlideshow` |
  285. | Stop-DesktopSlideshow | `Monitors.StopWallpaperSlideshow` |
  286. | Step-DesktopSlideshow | `Monitors.AdvanceWallpaperSlide` |
  287. | Get-DesktopBackgroundColor | `Monitors.GetBackgroundColor` |
  288. | Set-DesktopBackgroundColor | `Monitors.SetBackgroundColor` |
  289. | Get-DesktopBrightness | `Monitors.GetMonitorBrightness` |
  290. | Set-DesktopBrightness | `Monitors.SetMonitorBrightness` |
  291. | Set-DesktopPosition | `Monitor.SetMonitorPosition` or `Monitors.SetMonitorPosition` |
  292. | Set-DesktopResolution | `Monitors.SetMonitorResolution`, `Monitors.SetMonitorOrientation` |
  293. | Set-DefaultAudioDevice | `AudioService.SetDefaultAudioDevice` |
  294. | Get-LogonWallpaper | `Monitors.GetLogonWallpaper` |
  295. | Set-LogonWallpaper | `Monitors.SetLogonWallpaper` |
  296. | Set-TaskbarPosition | `TaskbarService.SetTaskbarPosition` / `SetTaskbarVisibility` |
  297. | Invoke-DesktopMouseMove | `WindowManager.MoveMouse` |
  298. | Invoke-DesktopMouseClick | `WindowManager.ClickMouse` |
  299. | Invoke-DesktopMouseScroll | `WindowManager.ScrollMouse` |
  300. | Invoke-DesktopScreenshot | `ScreenshotService.CaptureScreen`, `ScreenshotService.CaptureRegion` |
  301. | Get-DesktopWindow | `WindowManager.GetWindows` / `GetWindowsForProcess` |
  302. | Get-DesktopWindowGeometry | `DesktopAutomationService.GetWindowGeometry` |
  303. | Get-DesktopWindowControl | `DesktopAutomationService.GetControls` |
  304. | Get-DesktopWindowControlDiagnostic | `DesktopAutomationService.GetControlDiagnostics` / `GetControlTargetDiagnostics` |
  305. | Get-DesktopWindowProcessInfo | `WindowManager.GetWindowProcessInfo` |
  306. | Get-DesktopWindowTarget | `DesktopAutomationService.ListWindowTargets`, `GetWindowTarget`, `ResolveWindowTargets` |
  307. | Get-DesktopControlTarget | `DesktopAutomationService.ListControlTargets`, `GetControlTarget`, `ResolveControlTargets` |
  308. | Invoke-DesktopControlClick | `DesktopAutomationService.ClickControls` / `ClickControlTarget` |
  309. | Invoke-DesktopWindowClick | `DesktopAutomationService.ClickWindowPoint` / `ClickWindowTarget` |
  310. | Invoke-DesktopWindowDrag | `DesktopAutomationService.DragWindowPoints` / `DragWindowTargets` |
  311. | Invoke-DesktopWindowScroll | `DesktopAutomationService.ScrollWindowPoint` / `ScrollWindowTarget` |
  312. | Send-DesktopControlKey | `DesktopAutomationService.SendControlKeys` / `SendControlTargetKeys` |
  313. | Set-DesktopControlTarget | `DesktopAutomationService.SaveControlTarget` |
  314. | Set-DesktopControlText | `DesktopAutomationService.SetControlText` |
  315. | Set-DesktopWindow | `WindowManager.SetWindowPosition`, `MoveWindowToMonitor`, etc. |
  316. | Set-DesktopWindowSnap | `WindowManager.SnapWindow` |
  317. | Set-DesktopWindowTarget | `DesktopAutomationService.SaveWindowTarget` |
  318. | Set-DesktopWindowText | `WindowManager.TypeText`, `WindowManager.PasteText`, `WindowInputService` |
  319. | Wait-DesktopWindow | `DesktopAutomationService.WaitForWindows` |
  320. | Wait-DesktopWindowControl | `DesktopAutomationService.WaitForControls` |
  321. | Test-DesktopWindow | `DesktopAutomationService.WindowExists` / `ActiveWindowMatches` |
  322. | Test-DesktopWindowControl | `DesktopAutomationService.ControlExists` |
  323. | Start-DesktopWindowKeepAlive | `WindowKeepAlive.Start` |
  324. | Stop-DesktopWindowKeepAlive | `WindowKeepAlive.Stop` or `StopAll` |
  325. | Get-DesktopWindowKeepAlive | `WindowKeepAlive.ActiveHandles` |
  326. | Save-DesktopWindowLayout | `WindowManager.SaveLayout` |
  327. | Restore-DesktopWindowLayout | `WindowManager.LoadLayout` |
  328. | Register-DesktopMonitorEvent | `MonitorWatcher.DisplaySettingsChanged` |
  329. | Register-DesktopOrientationEvent | `MonitorWatcher.OrientationChanged` |
  330. | Register-DesktopResolutionEvent | `MonitorWatcher.ResolutionChanged` |
  331. ### Installation
  332. For using in PowerShell you can install it from PowerShell Gallery
  333. ```powershell
  334. Install-Module DesktopManager -Force -Verbose
  335. ```
  336. For the daily Windows tray app, use the DesktopManager MSI release artifact when available. The installer creates a Start Menu shortcut, and the app's Startup toggle registers the current user for minimized tray startup.
  337. From source, the app and MSI are built through PowerForge:
  338. ```powershell
  339. .\Build\Build-DesktopManagerApp.ps1
  340. .\Build\Build-DesktopManagerApp-MSI.ps1
  341. msiexec.exe /i .\Artefacts\PowerForge\Msi\DesktopManager.App\win-x64\net10.0-windows10.0.19041.0\PortableCompat\output\DesktopManager.msi
  342. ```
  343. ### Verified mutation examples
  344. When you want more than "the call did not throw", prefer `-Verify` together with `-PassThru` so the cmdlet returns the observed postcondition.
  345. ```powershell
  346. # Verify a window move against the observed geometry
  347. Set-DesktopWindow -Name "*Visual Studio Code*" -Left 0 -Top 0 -Width 1600 -Height 1200 -Verify -PassThru
  348. # Verify exact text after a control text update
  349. Set-DesktopControlText -Control $ctrl -Text "Hello world" -Verify -PassThru
  350. # Verify the observed check state
  351. Set-DesktopControlCheck -Control $checkbox -Check $true -Verify -PassThru
  352. # Return a structured record after a control click
  353. Invoke-DesktopControlClick -Control $button -PassThru
  354. # Return a structured record after sending keys
  355. Send-DesktopControlKey -Control $editor -Keys @([DesktopManager.VirtualKey]::VK_RETURN) -PassThru
  356. ```
  357. Verification behavior is action-aware:
  358. - window mutations verify geometry, state, topmost, close, or foreground conditions when those postconditions are meaningful
  359. - `Set-DesktopControlText -Verify` verifies the observed text/value when the control can be re-queried
  360. - `Set-DesktopControlCheck -Verify` verifies the observed check state
  361. - control click/key actions return honest presence and foreground evidence when exact semantic verification would be misleading
  362. ### Testing notes
  363. UI-impacting tests are opt-in to avoid opening windows or changing the desktop during local development. Use the environment variables below to control behavior:
  364. - `RUN_UI_TESTS=true` (or `DESKTOPMANAGER_RUN_UI_TESTS=true`) enables the top-level UI test pack.
  365. - `RUN_OWNED_WINDOW_UI_TESTS=true` (or `DESKTOPMANAGER_RUN_OWNED_WINDOW_UI_TESTS=true`) enables owned-window UI tests that use repo-created harness windows.
  366. - `RUN_DESTRUCTIVE_UI_TESTS=true` (or `DESKTOPMANAGER_RUN_DESTRUCTIVE_UI_TESTS=true`) enables owned-window mutation tests such as move, resize, hide, snap, and transparency changes against repo-created harness windows.
  367. - `RUN_FOREGROUND_UI_TESTS=true` (or `DESKTOPMANAGER_RUN_FOREGROUND_UI_TESTS=true`) enables tests that intentionally steal foreground focus, even when they only target repo-created harness windows.
  368. - `RUN_SYSTEM_UI_TESTS=true` (or `DESKTOPMANAGER_RUN_SYSTEM_UI_TESTS=true`) enables system-wide desktop changes such as wallpapers, brightness, resolution, and other monitor-level mutations that can affect your current session.
  369. - `RUN_EXTERNAL_UI_TESTS=true` (or `DESKTOPMANAGER_RUN_EXTERNAL_UI_TESTS=true`) enables live external-application UI tests and MCP end-to-end harnesses that launch real desktop apps.
  370. - `RUN_EXPERIMENTAL_UI_TESTS=true` (or `DESKTOPMANAGER_RUN_EXPERIMENTAL_UI_TESTS=true`) enables experimental live UI harnesses that are useful for manual validation but are not part of the stable regression pack.
  371. - `SKIP_UI_TESTS=true` (or `DESKTOPMANAGER_SKIP_UI_TESTS=true`) forces UI tests to skip, even if enabled elsewhere.
  372. Owned WinForms fixtures show without activation. Tests that explicitly activate a window or depend on foreground focus also require the foreground gate. Keep `RUN_FOREGROUND_UI_TESTS` and `DESKTOPMANAGER_RUN_FOREGROUND_UI_TESTS` disabled while using the desktop; enable that slice only during a dedicated interactive run.
  373. The gates compose intentionally:
  374. | Gate | What it permits | Typical impact |
  375. | ---- | --------------- | -------------- |
  376. | `RUN_UI_TESTS` | Top-level UI pack enablement only | Low |
  377. | `RUN_OWNED_WINDOW_UI_TESTS` | Repo-owned WinForms/WPF harness windows | Low to medium |
  378. | `RUN_DESTRUCTIVE_UI_TESTS` | Mutations against owned harness windows | Medium to high |
  379. | `RUN_FOREGROUND_UI_TESTS` | Tests that intentionally take foreground focus | Medium to high |
  380. | `RUN_SYSTEM_UI_TESTS` | System-wide desktop changes | High |
  381. | `RUN_EXTERNAL_UI_TESTS` | Launching real desktop apps | Medium to high |
  382. | `RUN_EXPERIMENTAL_UI_TESTS` | Experimental live harnesses | Varies |
  383. ```powershell
  384. # Run owned-window UI tests
  385. $env:RUN_UI_TESTS = "true"
  386. $env:RUN_OWNED_WINDOW_UI_TESTS = "true"
  387. # Run repo-owned window mutation tests
  388. $env:RUN_DESTRUCTIVE_UI_TESTS = "true"
  389. # Run tests that intentionally steal foreground focus
  390. $env:RUN_FOREGROUND_UI_TESTS = "true"
  391. # Run system-wide desktop mutations
  392. $env:RUN_SYSTEM_UI_TESTS = "true"
  393. # Run live external-application harnesses
  394. $env:RUN_EXTERNAL_UI_TESTS = "true"
  395. # Run experimental live UI harnesses
  396. $env:RUN_EXPERIMENTAL_UI_TESTS = "true"
  397. # Force skip
  398. $env:SKIP_UI_TESTS = "true"
  399. # Run the repo-owned window mutation slice
  400. dotnet test Sources/DesktopManager.Tests/DesktopManager.Tests.csproj -f net8.0-windows10.0.19041.0 --no-build --filter "WindowPositionTests|WindowStateHelpersTests|WindowVisibilityTests|WindowTransparencyTests|WindowStyleModificationTests|WindowLayoutTests"
  401. # Run the foreground-window slice
  402. dotnet test Sources/DesktopManager.Tests/DesktopManager.Tests.csproj -f net8.0-windows10.0.19041.0 --no-build --filter "DesktopAutomationAssertionTests|WindowManagerFilterTests|WindowTopMostActivationTests"
  403. # Run the live MCP desktop pack backed by the repo-owned DesktopManager.TestApp harness
  404. dotnet test Sources/DesktopManager.Tests/DesktopManager.Tests.csproj -f net8.0-windows10.0.19041.0 --no-build --filter "McpServer_TestApp"
  405. ```
  406. When the hosted-session or experimental live harnesses skip because focus or discoverability never stabilize, they now leave structured diagnostics and artifacts rather than failing silently. See [Docs/Build.Runbook.md](Docs/Build.Runbook.md) for the hosted-session artifact flow and gate guidance.
  407. ### Usage
  408. #### Example in C#
  409. The `DesktopManager.Example` project contains additional examples. Its default mode is read-only; mutation demos require the explicit `--run-mutations` option.
  410. ```csharp
  411. var monitors = new Monitors();
  412. foreach (var monitor in monitors.GetMonitors(connectedOnly: true)) {
  413. MonitorPosition bounds = monitor.GetMonitorPosition();
  414. Console.WriteLine($"{monitor.Index}: {monitor.DeviceName} at {bounds.Left},{bounds.Top} " +
  415. $"({bounds.Right - bounds.Left}x{bounds.Bottom - bounds.Top})");
  416. }
  417. // Moving a monitor changes only its top-left coordinate. Change resolution separately.
  418. // monitors.SetMonitorPosition(selected.DeviceId, left: -1920, top: 0);
  419. ```
  420. #### Example in C# - Getting/Setting Window Position
  421. ```csharp
  422. var manager = new WindowManager();
  423. WindowInfo? window = manager.GetWindows(processName: "notepad").FirstOrDefault();
  424. if (window != null) {
  425. manager.SetWindowPosition(window, left: 100, top: 100, width: 1000, height: 700);
  426. manager.ActivateWindow(window);
  427. }
  428. ```
  429. ### Platform notes
  430. When retrieving a window's style the library uses a helper method that calls
  431. `GetWindowLong` on 32-bit processes and `GetWindowLongPtr` on 64-bit ones. The
  432. method returns an `IntPtr`, so callers should convert the value to the
  433. appropriate numeric type.
  434. #### Example in PowerShell - Getting Monitor Information
  435. ```powershell
  436. Get-DesktopMonitor | Format-Table
  437. Get-DesktopWallpaper -Index 0
  438. Set-DesktopWallpaper -Index 1 -WallpaperPath "C:\Wallpapers\Landscape.jpg" -Position Fit
  439. Set-DesktopWallpaper -Index 0 -WallpaperPath "C:\Wallpapers\Portrait.jpg"
  440. Set-DesktopBackgroundColor -Color 0x0000FF
  441. Get-DesktopBackgroundColor
  442. ```
  443. #### Example in PowerShell - Wallpaper Slideshow
  444. ```powershell
  445. Start-DesktopSlideshow -ImagePath 'C:\Wallpapers\img1.jpg','C:\Wallpapers\img2.jpg' -Shuffle -SlideshowTick 300000
  446. Get-DesktopSlideshow
  447. Set-DesktopSlideshowOptions -NoShuffle -SlideshowTick 600000
  448. Step-DesktopSlideshow -Direction Forward
  449. Stop-DesktopSlideshow
  450. ```
  451. ```powershell
  452. $Desktop1 = Get-DesktopMonitor
  453. $Desktop1 | Format-Table
  454. $Desktop2 = Get-DesktopMonitor -ConnectedOnly
  455. $Desktop2 | Format-Table
  456. $Desktop3 = Get-DesktopMonitor -PrimaryOnly
  457. $Desktop3 | Format-Table
  458. $Desktop4 = Get-DesktopMonitor -Index 1
  459. $Desktop4 | Format-Table
  460. $Desktop5 = Get-DesktopMonitor -DeviceName "\\.\DISPLAY2"
  461. $Desktop5 | Format-Table
  462. ```
  463. #### Example in PowerShell - Setting Monitor Position
  464. ```powershell
  465. $Desktop2 = Get-DesktopMonitor -ConnectedOnly
  466. $Desktop2 | Format-Table
  467. Set-DesktopPosition -Index 0 -Left -3840 -Top 0 -WhatIf
  468. Set-DesktopPosition -Index 1 -Left 0 -Top 0 -WhatIf
  469. ```
  470. ### Example in PowerShell - Getting/Setting Window Position
  471. ```powershell
  472. Get-DesktopWindow | Format-Table *
  473. ```
  474. ```powershell
  475. $np = Start-Process notepad -PassThru
  476. Get-DesktopWindow -ProcessId $np.Id
  477. $np | Stop-Process
  478. ```
  479. ![image](https://github.com/user-attachments/assets/e4d026f7-2035-4a45-9779-a85423acdb21)
  480. ```powershell
  481. Set-DesktopWindow -Name '*Zadanie - Notepad' -Height 800 -Width 1200 -Left 100
  482. Set-DesktopWindow -Name '*Zadanie - Notepad' -State Maximize
  483. ```
  484. ```powershell
  485. Set-DesktopWindowText -Name '*Notepad*' -Text 'Hello world'
  486. ```
  487. ```powershell
  488. # Send Ctrl+S to Notepad
  489. $notepad = Get-DesktopWindow -Name '*Notepad*'
  490. Invoke-DesktopKeyPress -Window $notepad -Keys @(
  491. [DesktopManager.VirtualKey]::VK_CONTROL,
  492. [DesktopManager.VirtualKey]::VK_S
  493. )
  494. # See Examples/KeyboardActions.ps1
  495. ```
  496. ### Example in PowerShell - Activating and Setting Window Top-Most
  497. ```powershell
  498. Set-DesktopWindow -Name '*Notepad*' -TopMost -Activate
  499. ```
  500. #### Example in C# - Activating and Setting Window Top-Most
  501. ```csharp
  502. var manager = new WindowManager();
  503. var window = manager.GetWindows().First();
  504. manager.SetWindowTopMost(window, true);
  505. manager.ActivateWindow(window);
  506. #### Example in PowerShell - Monitoring Display Changes
  507. Use `Register-DesktopMonitorEvent` to react when monitors are plugged in or the display configuration changes.
  508. ```powershell
  509. Register-DesktopMonitorEvent -Duration (New-TimeSpan -Seconds 30) -Action { Write-Host 'Display settings changed' }
  510. ```
  511. Use `Register-DesktopOrientationEvent` or `Register-DesktopResolutionEvent` to handle orientation or resolution changes individually.
  512. ```powershell
  513. Register-DesktopResolutionEvent -Duration (New-TimeSpan -Seconds 30) -Action { Write-Host 'Resolution changed' }
  514. Register-DesktopOrientationEvent -Duration (New-TimeSpan -Seconds 30) -Action { Write-Host 'Orientation changed' }
  515. ```
  516. #### Example in C# - Monitoring Display Changes
  517. Applications can subscribe to the `MonitorWatcher.DisplaySettingsChanged` event.
  518. ```csharp
  519. MonitorWatcherExample.Run(TimeSpan.FromSeconds(30));
  520. ```
  521. #### Example in PowerShell - Saving and Restoring Window Layout
  522. Window geometry uses physical desktop pixels for enumeration, movement, client coordinates and pointer targeting. A width of 900 on a 150% display means 900 physical pixels; DPI-unaware hosts previously could observe 600 logical pixels for that window. Values read by `Get-DesktopWindow` now use the same units as `Set-DesktopWindow`.
  523. Layout files saved by older versions in a DPI-unaware host can contain logical coordinates without identifying their DPI context. Those files retain their numeric values when restored; no reliable automatic conversion is possible. Re-save layouts on scaled displays after checking their placement with the new version. Existing layouts saved in physical pixels retain their coordinates.
  524. For optional virtual desktop assignments, pins, Explorer folders and explicit
  525. per-desktop wallpaper restoration, see [Workspace recovery](Docs/Workspace.Recovery.md).
  526. ```powershell
  527. Save-DesktopWindowLayout -Path './layout.json'
  528. # ... move windows around ...
  529. Restore-DesktopWindowLayout -Path './layout.json' -Validate
  530. ```
  531. #### Example in C# - Saving and Restoring Window Layout
  532. ```csharp
  533. var manager = new WindowManager();
  534. manager.SaveLayout("layout.json");
  535. // ... move windows around ...
  536. manager.LoadLayout("layout.json", validate: true);
  537. ```
  538. Layout restoration uses each live window at most once and skips ambiguous or missing targets. Saved layouts include process and native class names so a restarted application can be matched without relying only on its title. Legacy files retain exact process-ID/title matching; title-only and process-only fallback are disabled. Use `PlanLayout` to inspect matches and `ApplyLayout` to obtain per-window outcomes:
  539. ```csharp
  540. var layout = JsonSerializer.Deserialize<WindowLayout>(File.ReadAllText("layout.json"))!;
  541. WindowLayoutPlan plan = manager.PlanLayout(layout);
  542. foreach (WindowLayoutMatch match in plan.Windows) {
  543. Console.WriteLine($"{match.SavedWindow.Title}: {match.Status} ({match.CandidateCount} candidates)");
  544. }
  545. IReadOnlyList<WindowLayoutApplyResult> results = manager.ApplyLayout(layout);
  546. ```
  547. #### Examples in PowerShell - Window Keep-Alive Cmdlets
  548. ```powershell
  549. # Keep Notepad alive for one minute
  550. Start-DesktopWindowKeepAlive -Name '*Notepad*' -Interval 00:01:00
  551. # List active sessions
  552. Get-DesktopWindowKeepAlive
  553. # Stop the session
  554. Stop-DesktopWindowKeepAlive -Name '*Notepad*'
  555. ```
  556. ```powershell
  557. # Keep Notepad and Calculator alive
  558. Start-DesktopWindowKeepAlive -Name '*Notepad*'
  559. Start-DesktopWindowKeepAlive -Name '*Calculator*' -Interval 00:00:30
  560. Start-Sleep -Seconds 5
  561. Get-DesktopWindowKeepAlive | Format-Table Title, Handle
  562. Stop-DesktopWindowKeepAlive -All
  563. ```
  564. ```powershell
  565. # Monitor RDP windows
  566. Start-DesktopWindowKeepAlive -Name '*RDP*' -Interval 00:00:30
  567. 1..3 | ForEach-Object {
  568. Start-Sleep -Seconds 10
  569. Get-DesktopWindowKeepAlive | ForEach-Object { "Active: $($_.Title)" }
  570. }
  571. Stop-DesktopWindowKeepAlive -Name '*RDP*'
  572. ```
  573. #### Examples in C# - Window Keep-Alive
  574. ```csharp
  575. var manager = new WindowManager();
  576. var notepad = manager.GetWindows("*Notepad*").FirstOrDefault();
  577. if (notepad != null) {
  578. WindowKeepAlive.Instance.Start(notepad, TimeSpan.FromMinutes(1));
  579. }
  580. ```
  581. ```csharp
  582. foreach (var window in new WindowManager().GetWindows("*Chrome*")) {
  583. WindowKeepAlive.Instance.Start(window, TimeSpan.FromSeconds(30));
  584. }
  585. ```
  586. ```csharp
  587. foreach (var handle in WindowKeepAlive.Instance.ActiveHandles) {
  588. Console.WriteLine($"Keeping {handle} alive");
  589. }
  590. WindowKeepAlive.Instance.StopAll();
  591. ```
  592. ### C# API Highlights
  593. DesktopManager ships as a .NET library targeting `net472`, `netstandard2.0`, `net8.0-windows10.0.19041.0`, and `net10.0-windows10.0.19041.0`. The main entry points are:
  594. - `Monitors` for monitor enumeration, wallpaper management, brightness, resolution, orientation and slideshow control.
  595. - `WindowManager` for window enumeration, positioning, resizing and layout persistence.
  596. - `MonitorWatcher` to receive events when display settings change.
  597. - `ScreenshotService` to capture the desktop or custom regions.
  598. - `WorkstationProfileService` and `WorkstationProfileStore` for cohesive named workstation state.
  599. - `AudioService` and `AudioEndpointWatcher` for Core Audio endpoints, default roles, volume, mute, and changes.
  600. - `AudioSessionService` for per-application volume, mute and peak levels, and `AudioService.OpenDefaultEndpoint` for a disposable endpoint level session.
  601. - `MediaSessionService` for the current Windows media session, encoded artwork and transport controls; .NET 8 and .NET 10 Windows targets support this capability.
  602. - `DeviceUsageService` for the microphone and camera applications recorded by the Windows privacy indicator.
  603. - `SystemPowerService`, `DesktopSessionService`, and `DesktopSessionWatcher` for power and session state/actions.
  604. - `PersonalizationService`, `PersonalizationStateStore`, and `TaskbarService` for reversible user settings and taskbars.
  605. - `RadioService` for supported per-radio operations and `ExperimentalAirplaneModeService` for the separately acknowledged undocumented global switch.
  606. - `WifiProfileService` for saved-profile inventory and exact profile connection without nearby-network scanning.
  607. - `VirtualDesktopService` for the supported window-to-desktop operations.
  608. ### Audio and current media
  609. Audio volumes use percentages from 0 through 100; signal peaks use 0 through 1.
  610. Application readings group sessions by process name, retaining a representative
  611. process ID and a key for subsequent volume or mute changes. Dispose the service
  612. to release its cached session references.
  613. ```csharp
  614. using var mixer = new AudioSessionService();
  615. foreach (AudioApplicationInfo app in mixer.GetApplications()) {
  616. Console.WriteLine($"{app.Name}: {app.VolumePercent:0}% (peak {app.PeakValue:0.00})");
  617. }
  618. using var media = new MediaSessionService();
  619. MediaSessionResult current = await media.GetCurrentAsync();
  620. if (current.Succeeded && current.Session is { } track) {
  621. Console.WriteLine($"{track.Artist} — {track.Title}");
  622. }
  623. ```
  624. `MediaSessionService.Changed` signals that the current metadata should be read
  625. again. Artwork is encoded image data, independent of any UI framework. Media
  626. session operations report `Unsupported` on the older library targets and report
  627. success with no session when Windows has no current source. Transport methods
  628. request play/pause, next or previous only when called explicitly.
  629. `AudioService.OpenDefaultEndpoint` retains the endpoint selected for a flow and
  630. role when opened; reopen it after a default-device change. `GetState()` reads
  631. volume, mute and the optional meter. `DeviceUsageService` reads Windows' current
  632. privacy-indicator records without changing permissions; these records can lag
  633. actual microphone or camera activity.
  634. ### Input, waits, and provider health
  635. `TypeText` and `PasteText` insert at an editable control's current selection. They do not replace its whole value to repair an unexpected result. Background text delivery prefers the target's focused editor and rejects multiple eligible editors when none is focused. Use `WindowControlService.SetText` when replacement is intended. Paste, native clicks, and character messages are delivered once. `InputRetryCount` applies only when `SendInput` confirms zero input was delivered. A `NativeOperationOutcomeUnknownException` means the target may already have changed; observe its state before deciding whether to retry. Requested focus and clipboard-text restoration also runs when delivery fails.
  636. Asynchronous waits support cancellation on every library target. A zero timeout waits indefinitely until a match appears or cancellation is requested:
  637. ```csharp
  638. using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(10));
  639. WindowInfo window = await manager.WaitWindowAsync("*Notepad*", cancellationToken: cancellation.Token);
  640. ```
  641. UI Automation uses a separate STA worker per target process, with at most 16 workers and 64 queued operations per worker. Each worker permits up to 64 active event subscriptions with reserved cleanup capacity, so a full operation queue cannot lose cleanup. One blocked provider therefore leaves other processes available while capacity remains. In-flight native calls cannot be safely canceled or replayed and retain their worker until they return. `DesktopAutomationDiagnostics.GetUiAutomationHealth()` reports pending work and blocked calls without contacting the providers. Worker shutdown is bounded, and new work fails when the worker or queue limit is reached.
  642. ### Window capture provenance
  643. `CaptureWindow` retains its desktop fallback behavior. `CaptureWindowDetailed` defaults to strict window capture and records the backend, actual screen bounds, dark-pixel observation, and fallback reason. A dark image can be legitimate; strict mode retains those pixels. Desktop fallback may contain a covering application's pixels.
  644. ```csharp
  645. using WindowCaptureResult capture = ScreenshotService.CaptureWindowDetailed(window.Handle);
  646. Console.WriteLine($"{capture.Backend}: {capture.ScreenBounds}");
  647. capture.Bitmap.Save("window.png");
  648. ```
  649. Pass `new WindowCaptureOptions { AllowDesktopFallback = true }` to opt into visible-desktop fallback. `DesktopAutomationService` capture objects and CLI/MCP screenshot results also expose the capture backend and fallback reason. Sparse dark-image and visual-difference sampling reads locked pixels directly, avoiding full-image managed copies; template matching retains its dense pixel buffer.
  650. ### Display requests requiring a restart
  651. `SetMonitorDisplayModeDetailed` returns `RestartRequired` when Windows accepts a display request that needs a system restart. The existing void `SetMonitorDisplayMode` method throws `DisplayRestartRequiredException` for that outcome. Workstation profile results report `Succeeded = false` and `RestartRequired = true` for this request. PowerShell and the tray app display a warning; CLI JSON and MCP results preserve the restart requirement. No API restarts Windows automatically.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.