DesktopManager - C# Library and PowerShell Module

DesktopManager is a Windows desktop automation toolkit available as a .NET library, PowerShell module, CLI, MCP server, and tray app.

You can also download it from PowerShell Gallery

If you would like to contact me you can do so via Twitter or LinkedIn.

What it's all about

DesktopManager provides one shared Windows automation core through five surfaces:

• C# library for .NET applications and services
• PowerShell module for scripts and operator workflows
• CLI executable for terminal and JSON automation
• MCP server for inspect-first agent automation
• Windows tray app for daily hotkeys and monitor actions

It has following features:

• Get information about monitors
• Get information about display devices
• Get information about wallpapers
• Set wallpapers
• Get/Set desktop background color
• Get/Set monitor position
• Get/Set window position
• Get/Set window state (minimize, maximize, restore)
• Capture desktop screenshots from all monitors, a single monitor or a custom region
• Manage monitor brightness
• Start/Stop/Advance wallpaper slideshows
• Track wallpaper history
• Adjust monitor resolution and orientation
• Move monitors around the virtual desktop
• Save and restore window layouts
• Snap or move windows between monitors
• Subscribe to resolution, orientation or display changes
• Keep inactive windows awake using periodic input
• Manage keep-alive sessions for windows
• Save and restore cohesive workstation profiles across displays, audio, personalization, and taskbars
• Enumerate Core Audio render/capture endpoints, change volume and mute, set default roles, and observe endpoint changes
• Inspect power and interactive-session state; lock, sign out, sleep, hibernate, or hold a bounded keep-awake lease
• Capture and restore personalization snapshots and configure taskbar visibility, position, and auto-hide
• Enumerate, observe, and explicitly enable or disable Wi-Fi, Bluetooth, mobile broadband, and FM radios through the supported Windows radio API
• List saved Windows Wi-Fi profiles and connect an exact saved profile without scanning nearby networks or exposing credentials
• Inspect a window's virtual desktop and move it to a known desktop through the public Windows virtual-desktop API
• Inspect and manage Plug and Play devices and Driver Store packages through documented native Windows APIs

Desktop state and controls

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.

Save-DesktopWorkstationProfile -Name 'office'
Get-DesktopAudioEndpoint -DataFlow Render -State Active
Get-DesktopPowerStatus
Get-DesktopSession
Get-DesktopRadio
Get-DesktopWifiProfile
Connect-DesktopWifiProfile -Name 'Corporate WiFi'
Get-DesktopDevice -Present -Problem
Get-DesktopDriverPackage
Restore-DesktopWorkstationProfile -Name 'office' -Confirm

The same capabilities are available from the CLI:

desktopmanager workstation save --name office
desktopmanager audio list --flow render --active
desktopmanager system power
desktopmanager system session
desktopmanager radio list
desktopmanager wifi profiles
desktopmanager wifi connect --profile "Corporate WiFi"
desktopmanager device list --present --problem
desktopmanager driver list
desktopmanager workstation apply --name office

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.

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.

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.

Additional operator-focused docs for the newer CLI and MCP surfaces:

• Docs/DesktopManager.Cli.md
• Docs/DesktopManager.Mcp.md
• Docs/DesktopManager.Architecture.md
• Docs/DesktopManager.DesktopState.md
• Docs/DesktopManager.DeviceManagement.md
• Docs/DesktopManager.AutomationBasics.md
• Docs/DesktopManager.Plugin.md
• .agents/skills/desktopmanager-operator/SKILL.md
• .agents/skills/desktopmanager-build/SKILL.md

Which Surface Should You Use?

Surface	Best for	Typical entrypoint
C# library	Embedding DesktopManager into your own .NET app or service	DesktopManager.dll
PowerShell module	Scripts, operators, admin workflows, repeatable task automation	Install-Module DesktopManager
CLI executable	Manual use, shell automation, JSON output, and MCP hosting	desktopmanager.exe
MCP server	Agent-driven automation over stdio with an inspect-first safety model	desktopmanager mcp serve
Windows tray app	Daily hotkeys, monitor bindings, HDR controls, tray runtime, and per-user startup	DesktopManager.App.exe

How It Fits Together

DesktopManager now has one shared core and several operator-facing surfaces on top of it.

flowchart LR
    A["Your .NET app"] --> B["DesktopManager library"]
    C["PowerShell module"] --> B
    D["desktopmanager.exe CLI"] --> B
    E["MCP server"] --> D
    J["DesktopManager.App tray app"] --> B
    B --> F["Windows desktop APIs"]
    F --> G["Monitors / wallpapers / brightness"]
    F --> H["Windows / controls / input"]
    F --> I["Layouts / snapshots / targets"]

Loading

If you want the fuller component and request-flow diagrams, see Docs/DesktopManager.Architecture.md.

The practical way to think about this:

• use the library when DesktopManager is part of your own application
• use PowerShell when you want scriptable admin/operator automation
• use the CLI when you want a human-friendly or JSON-friendly command surface
• use MCP when an agent should inspect first and mutate only through an explicit server session

Common Entry Points

Goal	Recommended entrypoint
Add DesktopManager features to your own code	Reference the DesktopManager NuGet package
Run manual desktop operations from a terminal	desktopmanager.exe
Run DesktopManager every day from the tray	DesktopManager.App.exe or the DesktopManager MSI
Use it from PowerShell scripts	DesktopManager PowerShell module
Connect an agent/tooling layer	desktopmanager mcp serve
Understand the overall wiring	Docs/DesktopManager.Architecture.md

Request Flow at a Glance

flowchart LR
    A["User, script, or agent"] --> B{"Surface"}
    B -->|".NET"| C["DesktopManager library"]
    B -->|"PowerShell"| D["Cmdlets"]
    B -->|"CLI"| E["desktopmanager.exe"]
    B -->|"MCP"| F["desktopmanager mcp serve"]
    B -->|"Tray app"| J["DesktopManager.App.exe"]

    D --> C
    E --> G["DesktopOperations"]
    F --> G
    J --> C
    G --> C
    C --> H["Win32, UI Automation, monitor, screenshot, and input services"]

Loading

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.

Available PowerShell Cmdlets

Cmdlet	Description
Get-DesktopMonitor	Retrieve monitor information with filtering options
Get-DesktopWallpaper	Get current wallpaper path for monitors
Set-DesktopWallpaper	Apply wallpaper from path, URL or stream
Get-DesktopWallpaperHistory	List stored wallpaper history entries
Set-DesktopWallpaperHistory	Update or clear wallpaper history file
Get-DesktopSlideshow	Inspect slideshow images, state, options and tick interval
Set-DesktopSlideshowOptions	Update slideshow shuffle behavior and tick interval
Start-DesktopSlideshow	Begin wallpaper slideshow across monitors
Stop-DesktopSlideshow	Stop currently running slideshow
Step-DesktopSlideshow	Move slideshow forward or backward
Get-DesktopBackgroundColor	Read current desktop background color
Set-DesktopBackgroundColor	Change desktop background color
Get-DesktopBrightness	Read monitor brightness level
Set-DesktopBrightness	Set monitor brightness level
Set-DesktopPosition	Move a monitor by its top-left coordinates without changing resolution
Set-DesktopResolution	Change monitor resolution or orientation
Set-DefaultAudioDevice	Set the default audio playback device
Get-DesktopAudioEndpoint	List Core Audio render and capture endpoints with volume, mute, and default roles
Set-DesktopAudioEndpoint	Set endpoint volume, mute, or selected default roles
Register-DesktopAudioEvent	Subscribe to endpoint, state, property, and default-role changes
Save-DesktopWorkstationProfile	Capture displays, audio, personalization, and taskbars as one named profile
Get-DesktopWorkstationProfile	List or load named workstation profiles
Restore-DesktopWorkstationProfile	Apply a named workstation profile with matching and rollback options
Remove-DesktopWorkstationProfile	Delete a named workstation profile
Get-DesktopPowerStatus	Read AC and battery state
Get-DesktopSession	Read current interactive-session identity, connection, lock, and idle state
Register-DesktopSessionEvent	Subscribe to meaningful session changes
Lock-DesktopSession	Lock the current Windows session
Exit-DesktopSession	Sign out the current Windows session with confirmation support
Start-DesktopKeepAwake	Hold a bounded system/display keep-awake lease
Suspend-DesktopSystem	Request sleep or hibernation with confirmation support
Get-DesktopPersonalization	Capture current state or list/load saved personalization snapshots
Save-DesktopPersonalization	Save a named personalization snapshot
Set-DesktopPersonalization	Apply explicit personalization settings
Restore-DesktopPersonalization	Restore a named personalization snapshot
Remove-DesktopPersonalization	Delete a named personalization snapshot
Get-DesktopTaskbar	List taskbars with monitor mapping, visibility, edge, and bounds
Set-DesktopTaskbarAutoHide	Set the explicit taskbar auto-hide state
Get-DesktopRadio	List radios through the supported Windows radio API
Set-DesktopRadio	Explicitly enable or disable matching supported radios
Register-DesktopRadioEvent	Subscribe to supported radio state changes
Get-DesktopWifiProfile	List saved Windows Wi-Fi profiles without scanning nearby networks
Connect-DesktopWifiProfile	Connect an exact saved Windows Wi-Fi profile
Get-DesktopAirplaneMode	Read the experimental global airplane-mode state after explicit acknowledgement
Set-DesktopAirplaneMode	Apply and verify experimental global airplane mode after explicit acknowledgement
Get-DesktopVirtualDesktop	Inspect the supported virtual-desktop state for a top-level window
Move-DesktopWindowToVirtualDesktop	Move a top-level window to a known virtual-desktop ID
Get-LogonWallpaper	Get the lock screen wallpaper path
Set-LogonWallpaper	Set the lock screen wallpaper
Set-TaskbarPosition	Move or hide the taskbar
Invoke-DesktopMouseMove	Move the mouse cursor
Invoke-DesktopMouseClick	Simulate a mouse click
Invoke-DesktopMouseScroll	Scroll the mouse wheel
Invoke-DesktopScreenshot	Capture monitor or region screenshots
Get-DesktopWindow	Enumerate visible windows
Get-DesktopWindowGeometry	Return outer-window and client-area geometry for matched windows
Get-DesktopWindowControl	Enumerate Win32 or UIA window controls
Get-DesktopWindowControlDiagnostic	Explain Win32 vs UIA control discovery and actionability
Get-DesktopWindowProcessInfo	Return process details for matched windows
Get-DesktopWindowTarget	List saved window-relative targets or resolve one against live windows
Get-DesktopControlTarget	List saved control targets or resolve one against live windows
Get-DesktopHostedSessionDiagnostic	Read the latest hosted-session typing diagnostic artifact or a specific one
Invoke-DesktopControlClick	Click a matched control using shared control action routing
Invoke-DesktopWindowClick	Click a window-relative point or saved window target
Invoke-DesktopWindowDrag	Drag between window-relative points or saved targets
Invoke-DesktopWindowScroll	Scroll at a window-relative point or saved target
Send-DesktopControlKey	Send keys to a matched control without reimplementing key routing
Set-DesktopControlTarget	Save a reusable control selector profile
Set-DesktopControlText	Write text directly to a specific control
Set-DesktopWindow	Move, resize or control windows
Set-DesktopWindowSnap	Snap window to common positions
Set-DesktopWindowTarget	Save a reusable window-relative point target
Set-DesktopWindowText	Paste or type text into a window
Wait-DesktopWindow	Wait for a window to appear
Wait-DesktopWindowControl	Wait for a control to appear
Test-DesktopWindow	Verify that a window exists or matches the active window
Test-DesktopWindowControl	Verify that a control exists
Start-DesktopWindowKeepAlive	Send periodic input to keep a window awake
Stop-DesktopWindowKeepAlive	Stop sending keep-alive input
Get-DesktopWindowKeepAlive	List windows with active keep-alive
Save-DesktopWindowLayout	Save current window layout to file
Restore-DesktopWindowLayout	Restore saved window layout
Register-DesktopMonitorEvent	Subscribe to display configuration changes
Register-DesktopOrientationEvent	Subscribe to orientation changes
Register-DesktopResolutionEvent	Subscribe to resolution changes

Cmdlet to C# method map

The table below shows the most relevant API methods behind each PowerShell cmdlet.

Cmdlet	Main C# methods
Get-DesktopMonitor	Monitors.GetMonitors
Get-DesktopWallpaper	Monitors.GetWallpaper or Monitor.GetWallpaper
Set-DesktopWallpaper	Monitors.SetWallpaper, Monitors.SetWallpaperFromUrl
Get-DesktopWallpaperHistory	WallpaperHistory.GetHistory
Set-DesktopWallpaperHistory	WallpaperHistory.SetHistory
Get-DesktopSlideshow	Monitors.GetWallpaperSlideshow
Set-DesktopSlideshowOptions	Monitors.SetWallpaperSlideshowOptions
Start-DesktopSlideshow	Monitors.StartWallpaperSlideshow
Stop-DesktopSlideshow	Monitors.StopWallpaperSlideshow
Step-DesktopSlideshow	Monitors.AdvanceWallpaperSlide
Get-DesktopBackgroundColor	Monitors.GetBackgroundColor
Set-DesktopBackgroundColor	Monitors.SetBackgroundColor
Get-DesktopBrightness	Monitors.GetMonitorBrightness
Set-DesktopBrightness	Monitors.SetMonitorBrightness
Set-DesktopPosition	Monitor.SetMonitorPosition or Monitors.SetMonitorPosition
Set-DesktopResolution	Monitors.SetMonitorResolution, Monitors.SetMonitorOrientation
Set-DefaultAudioDevice	AudioService.SetDefaultAudioDevice
Get-LogonWallpaper	Monitors.GetLogonWallpaper
Set-LogonWallpaper	Monitors.SetLogonWallpaper
Set-TaskbarPosition	TaskbarService.SetTaskbarPosition / SetTaskbarVisibility
Invoke-DesktopMouseMove	WindowManager.MoveMouse
Invoke-DesktopMouseClick	WindowManager.ClickMouse
Invoke-DesktopMouseScroll	WindowManager.ScrollMouse
Invoke-DesktopScreenshot	ScreenshotService.CaptureScreen, ScreenshotService.CaptureRegion
Get-DesktopWindow	WindowManager.GetWindows / GetWindowsForProcess
Get-DesktopWindowGeometry	DesktopAutomationService.GetWindowGeometry
Get-DesktopWindowControl	DesktopAutomationService.GetControls
Get-DesktopWindowControlDiagnostic	DesktopAutomationService.GetControlDiagnostics / GetControlTargetDiagnostics
Get-DesktopWindowProcessInfo	WindowManager.GetWindowProcessInfo
Get-DesktopWindowTarget	DesktopAutomationService.ListWindowTargets, GetWindowTarget, ResolveWindowTargets
Get-DesktopControlTarget	DesktopAutomationService.ListControlTargets, GetControlTarget, ResolveControlTargets
Invoke-DesktopControlClick	DesktopAutomationService.ClickControls / ClickControlTarget
Invoke-DesktopWindowClick	DesktopAutomationService.ClickWindowPoint / ClickWindowTarget
Invoke-DesktopWindowDrag	DesktopAutomationService.DragWindowPoints / DragWindowTargets
Invoke-DesktopWindowScroll	DesktopAutomationService.ScrollWindowPoint / ScrollWindowTarget
Send-DesktopControlKey	DesktopAutomationService.SendControlKeys / SendControlTargetKeys
Set-DesktopControlTarget	DesktopAutomationService.SaveControlTarget
Set-DesktopControlText	DesktopAutomationService.SetControlText
Set-DesktopWindow	WindowManager.SetWindowPosition, MoveWindowToMonitor, etc.
Set-DesktopWindowSnap	WindowManager.SnapWindow
Set-DesktopWindowTarget	DesktopAutomationService.SaveWindowTarget
Set-DesktopWindowText	WindowManager.TypeText, WindowManager.PasteText, WindowInputService
Wait-DesktopWindow	DesktopAutomationService.WaitForWindows
Wait-DesktopWindowControl	DesktopAutomationService.WaitForControls
Test-DesktopWindow	DesktopAutomationService.WindowExists / ActiveWindowMatches
Test-DesktopWindowControl	DesktopAutomationService.ControlExists
Start-DesktopWindowKeepAlive	WindowKeepAlive.Start
Stop-DesktopWindowKeepAlive	WindowKeepAlive.Stop or StopAll
Get-DesktopWindowKeepAlive	WindowKeepAlive.ActiveHandles
Save-DesktopWindowLayout	WindowManager.SaveLayout
Restore-DesktopWindowLayout	WindowManager.LoadLayout
Register-DesktopMonitorEvent	MonitorWatcher.DisplaySettingsChanged
Register-DesktopOrientationEvent	MonitorWatcher.OrientationChanged
Register-DesktopResolutionEvent	MonitorWatcher.ResolutionChanged

Installation

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

Verified mutation examples

When you want more than "the call did not throw", prefer -Verify together with -PassThru so the cmdlet returns the observed postcondition.

# Verify a window move against the observed geometry
Set-DesktopWindow -Name "*Visual Studio Code*" -Left 0 -Top 0 -Width 1600 -Height 1200 -Verify -PassThru

# Verify exact text after a control text update
Set-DesktopControlText -Control $ctrl -Text "Hello world" -Verify -PassThru

# Verify the observed check state
Set-DesktopControlCheck -Control $checkbox -Check $true -Verify -PassThru

# Return a structured record after a control click
Invoke-DesktopControlClick -Control $button -PassThru

# Return a structured record after sending keys
Send-DesktopControlKey -Control $editor -Keys @([DesktopManager.VirtualKey]::VK_RETURN) -PassThru

Verification behavior is action-aware:

• window mutations verify geometry, state, topmost, close, or foreground conditions when those postconditions are meaningful
• Set-DesktopControlText -Verify verifies the observed text/value when the control can be re-queried
• Set-DesktopControlCheck -Verify verifies the observed check state
• control click/key actions return honest presence and foreground evidence when exact semantic verification would be misleading

Testing notes

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:

• RUN_UI_TESTS=true (or DESKTOPMANAGER_RUN_UI_TESTS=true) enables the top-level UI test pack.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• SKIP_UI_TESTS=true (or DESKTOPMANAGER_SKIP_UI_TESTS=true) forces UI tests to skip, even if enabled elsewhere.

The gates compose intentionally:

Gate	What it permits	Typical impact
RUN_UI_TESTS	Top-level UI pack enablement only	Low
RUN_OWNED_WINDOW_UI_TESTS	Repo-owned WinForms/WPF harness windows	Low to medium
RUN_DESTRUCTIVE_UI_TESTS	Mutations against owned harness windows	Medium to high
RUN_FOREGROUND_UI_TESTS	Tests that intentionally take foreground focus	Medium to high
RUN_SYSTEM_UI_TESTS	System-wide desktop changes	High
RUN_EXTERNAL_UI_TESTS	Launching real desktop apps	Medium to high
RUN_EXPERIMENTAL_UI_TESTS	Experimental live harnesses	Varies

# Run owned-window UI tests
$env:RUN_UI_TESTS = "true"
$env:RUN_OWNED_WINDOW_UI_TESTS = "true"

# Run repo-owned window mutation tests
$env:RUN_DESTRUCTIVE_UI_TESTS = "true"

# Run tests that intentionally steal foreground focus
$env:RUN_FOREGROUND_UI_TESTS = "true"

# Run system-wide desktop mutations
$env:RUN_SYSTEM_UI_TESTS = "true"

# Run live external-application harnesses
$env:RUN_EXTERNAL_UI_TESTS = "true"

# Run experimental live UI harnesses
$env:RUN_EXPERIMENTAL_UI_TESTS = "true"

# Force skip
$env:SKIP_UI_TESTS = "true"

# Run the repo-owned window mutation slice
dotnet test Sources/DesktopManager.Tests/DesktopManager.Tests.csproj -f net8.0-windows10.0.19041.0 --no-build --filter "WindowPositionTests|WindowStateHelpersTests|WindowVisibilityTests|WindowTransparencyTests|WindowStyleModificationTests|WindowLayoutTests"

# Run the foreground-window slice
dotnet test Sources/DesktopManager.Tests/DesktopManager.Tests.csproj -f net8.0-windows10.0.19041.0 --no-build --filter "DesktopAutomationAssertionTests|WindowManagerFilterTests|WindowTopMostActivationTests"

# Run the live MCP desktop pack backed by the repo-owned DesktopManager.TestApp harness
dotnet test Sources/DesktopManager.Tests/DesktopManager.Tests.csproj -f net8.0-windows10.0.19041.0 --no-build --filter "McpServer_TestApp"

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 for the hosted-session artifact flow and gate guidance.

Usage

Example in C#

The DesktopManager.Example project contains additional examples. Its default mode is read-only; mutation demos require the explicit --run-mutations option.

var monitors = new Monitors();
foreach (var monitor in monitors.GetMonitors(connectedOnly: true)) {
    MonitorPosition bounds = monitor.GetMonitorPosition();
    Console.WriteLine($"{monitor.Index}: {monitor.DeviceName} at {bounds.Left},{bounds.Top} " +
        $"({bounds.Right - bounds.Left}x{bounds.Bottom - bounds.Top})");
}

// Moving a monitor changes only its top-left coordinate. Change resolution separately.
// monitors.SetMonitorPosition(selected.DeviceId, left: -1920, top: 0);

Example in C# - Getting/Setting Window Position

var manager = new WindowManager();
WindowInfo? window = manager.GetWindows(processName: "notepad").FirstOrDefault();
if (window != null) {
    manager.SetWindowPosition(window, left: 100, top: 100, width: 1000, height: 700);
    manager.ActivateWindow(window);
}

Platform notes

When retrieving a window's style the library uses a helper method that calls GetWindowLong on 32-bit processes and GetWindowLongPtr on 64-bit ones. The method returns an IntPtr, so callers should convert the value to the appropriate numeric type.

Example in PowerShell - Getting Monitor Information

Get-DesktopMonitor | Format-Table

Get-DesktopWallpaper -Index 0

Set-DesktopWallpaper -Index 1 -WallpaperPath "C:\Wallpapers\Landscape.jpg" -Position Fit
Set-DesktopWallpaper -Index 0 -WallpaperPath "C:\Wallpapers\Portrait.jpg"
Set-DesktopBackgroundColor -Color 0x0000FF
Get-DesktopBackgroundColor

Example in PowerShell - Wallpaper Slideshow

Start-DesktopSlideshow -ImagePath 'C:\Wallpapers\img1.jpg','C:\Wallpapers\img2.jpg' -Shuffle -SlideshowTick 300000
Get-DesktopSlideshow
Set-DesktopSlideshowOptions -NoShuffle -SlideshowTick 600000
Step-DesktopSlideshow -Direction Forward
Stop-DesktopSlideshow

$Desktop1 = Get-DesktopMonitor
$Desktop1 | Format-Table

$Desktop2 = Get-DesktopMonitor -ConnectedOnly
$Desktop2 | Format-Table

$Desktop3 = Get-DesktopMonitor -PrimaryOnly
$Desktop3 | Format-Table

$Desktop4 = Get-DesktopMonitor -Index 1
$Desktop4 | Format-Table

$Desktop5 = Get-DesktopMonitor -DeviceName "\\.\DISPLAY2"
$Desktop5 | Format-Table

Example in PowerShell - Setting Monitor Position

$Desktop2 = Get-DesktopMonitor -ConnectedOnly
$Desktop2 | Format-Table

Set-DesktopPosition -Index 0 -Left -3840 -Top 0 -WhatIf
Set-DesktopPosition -Index 1 -Left 0 -Top 0 -WhatIf

Example in PowerShell - Getting/Setting Window Position

Get-DesktopWindow | Format-Table *

$np = Start-Process notepad -PassThru
Get-DesktopWindow -ProcessId $np.Id
$np | Stop-Process

Set-DesktopWindow -Name '*Zadanie - Notepad' -Height 800 -Width 1200 -Left 100
Set-DesktopWindow -Name '*Zadanie - Notepad' -State Maximize

Set-DesktopWindowText -Name '*Notepad*' -Text 'Hello world'

# Send Ctrl+S to Notepad
$notepad = Get-DesktopWindow -Name '*Notepad*'
Invoke-DesktopKeyPress -Window $notepad -Keys @(
    [DesktopManager.VirtualKey]::VK_CONTROL,
    [DesktopManager.VirtualKey]::VK_S
)
# See Examples/KeyboardActions.ps1

Example in PowerShell - Activating and Setting Window Top-Most

Set-DesktopWindow -Name '*Notepad*' -TopMost -Activate

Example in C# - Activating and Setting Window Top-Most

var manager = new WindowManager();
var window = manager.GetWindows().First();
manager.SetWindowTopMost(window, true);
manager.ActivateWindow(window);
#### Example in PowerShell - Monitoring Display Changes

Use `Register-DesktopMonitorEvent` to react when monitors are plugged in or the display configuration changes.

```powershell
Register-DesktopMonitorEvent -Duration 30 -Action { Write-Host 'Display settings changed' }

Use Register-DesktopOrientationEvent or Register-DesktopResolutionEvent to handle orientation or resolution changes individually.

Register-DesktopResolutionEvent -Duration 30 -Action { Write-Host 'Resolution changed' }
Register-DesktopOrientationEvent -Duration 30 -Action { Write-Host 'Orientation changed' }

Example in C# - Monitoring Display Changes

Applications can subscribe to the MonitorWatcher.DisplaySettingsChanged event.

MonitorWatcherExample.Run(TimeSpan.FromSeconds(30));

Example in PowerShell - Saving and Restoring Window Layout

Save-DesktopWindowLayout -Path './layout.json'
# ... move windows around ...
Restore-DesktopWindowLayout -Path './layout.json' -Validate

Example in C# - Saving and Restoring Window Layout

var manager = new WindowManager();
manager.SaveLayout("layout.json");
// ... move windows around ...
manager.LoadLayout("layout.json", validate: true);

Examples in PowerShell - Window Keep-Alive Cmdlets

# Keep Notepad alive for one minute
Start-DesktopWindowKeepAlive -Name '*Notepad*' -Interval 00:01:00

# List active sessions
Get-DesktopWindowKeepAlive

# Stop the session
Stop-DesktopWindowKeepAlive -Name '*Notepad*'

# Keep Notepad and Calculator alive
Start-DesktopWindowKeepAlive -Name '*Notepad*'
Start-DesktopWindowKeepAlive -Name '*Calculator*' -Interval 00:00:30
Start-Sleep -Seconds 5
Get-DesktopWindowKeepAlive | Format-Table Title, Handle
Stop-DesktopWindowKeepAlive -All

# Monitor RDP windows
Start-DesktopWindowKeepAlive -Name '*RDP*' -Interval 00:00:30
1..3 | ForEach-Object {
    Start-Sleep -Seconds 10
    Get-DesktopWindowKeepAlive | ForEach-Object { "Active: $($_.Title)" }
}
Stop-DesktopWindowKeepAlive -Name '*RDP*'

Examples in C# - Window Keep-Alive

var manager = new WindowManager();
var notepad = manager.GetWindows("*Notepad*").FirstOrDefault();
if (notepad != null) {
    WindowKeepAlive.Instance.Start(notepad, TimeSpan.FromMinutes(1));
}

foreach (var window in new WindowManager().GetWindows("*Chrome*")) {
    WindowKeepAlive.Instance.Start(window, TimeSpan.FromSeconds(30));
}

foreach (var handle in WindowKeepAlive.Instance.ActiveHandles) {
    Console.WriteLine($"Keeping {handle} alive");
}
WindowKeepAlive.Instance.StopAll();

C# API Highlights

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:

• Monitors for monitor enumeration, wallpaper management, brightness, resolution, orientation and slideshow control.
• WindowManager for window enumeration, positioning, resizing and layout persistence.
• MonitorWatcher to receive events when display settings change.
• ScreenshotService to capture the desktop or custom regions.
• WorkstationProfileService and WorkstationProfileStore for cohesive named workstation state.
• AudioService and AudioEndpointWatcher for Core Audio endpoints, default roles, volume, mute, and changes.
• SystemPowerService, DesktopSessionService, and DesktopSessionWatcher for power and session state/actions.
• PersonalizationService, PersonalizationStateStore, and TaskbarService for reversible user settings and taskbars.
• RadioService for supported per-radio operations and ExperimentalAirplaneModeService for the separately acknowledged undocumented global switch.
• WifiProfileService for saved-profile inventory and exact profile connection without nearby-network scanning.
• VirtualDesktopService for the supported window-to-desktop operations.