Azure Virtual Desktop with PowerShell 7: Host Health, Sessions and Safe Restarts

I spent a lot of my career running virtual desktops for MSP clients. Today I work as an M365 cloud admin.

Azure Virtual Desktop is easy to stand up. Keeping it healthy day to day is the harder part.

So I cleaned up the checks I use and shared them on GitHub. This toolkit uses PowerShell 7 and the Az.DesktopVirtualization module.

Repo: azure-virtual-desktop-powershell-toolkit

The problem it solves

A host gets left in drain mode after patching. Nobody notices until the other hosts are full.

A disconnected session holds a profile lock. The user can't sign in, and the ticket says "AVD is broken."

Pools run all night with no scaling plan. The bill shows it.

These scripts make those checks quick and repeatable.

Highlight scripts

Get-AvdSessionHostReport.ps1

Checks every session host in every pool. It flags hosts that are unavailable, stuck in drain mode, missing heartbeats or failing health checks.

./Get-AvdSessionHostReport.ps1 -HeartbeatMinutes 30

Remove-AvdDisconnectedSession.ps1

Signs out disconnected sessions older than a set number of hours. You can exclude accounts. Always run with -WhatIf first.

./Remove-AvdDisconnectedSession.ps1 -ResourceGroupName rg-avd-prod -HostPoolName hp-contoso-pooled -OlderThanHours 24 -WhatIf

Restart-AvdSessionHost.ps1

Drains a host, skips it if users are still on it, restarts the VM and waits for it to come back. Then it turns drain mode off. If the host does not come back, it stays drained.

./Restart-AvdSessionHost.ps1 -ResourceGroupName rg-avd-prod -HostPoolName hp-contoso-pooled -SessionHostName avd-contoso-0.contoso.com -WhatIf

Get-AvdScalingPlanReport.ps1

Lists your scaling plans and their schedules. It also lists every host pool with no scaling plan turned on. That is where the savings are.

./Get-AvdScalingPlanReport.ps1

Other scripts cover an environment inventory, finding a user's session, messaging users, drain mode and app group access reviews.

How the scripts are built

• PowerShell 7.4 or later.
• Comment-based help on every script. Run Get-Help ./script.ps1 -Full.
• Reports export to CSV.
• Change scripts support -WhatIf and -Confirm.
• Certificate (app-only) or interactive sign-in for Azure.
• No secrets in the repo. Examples use contoso.com and placeholder GUIDs.

Please test in a test subscription or a validation host pool first. Read each script before you run it.

My usual workflow

I run the session host report every morning. It takes seconds.

Before patching, I drain the host and send users a message. Once it is empty, I run the restart script. Then I run the report again to make sure every host is back.

One tip. Set up a small validation host pool. It gets AVD agent updates first, so you catch problems before your users do.

Getting started

Clone the repo:

git clone https://github.com/anthonybuhnerkemper/azure-virtual-desktop-powershell-toolkit.git
cd azure-virtual-desktop-powershell-toolkit

Every toolkit ships the same Connect-M365Admin script. Dot-source it, then connect.

# Interactive sign-in
. ./scripts/Connect/Connect-M365Admin.ps1
Connect-M365Admin -Service Azure -Interactive -SubscriptionId 00000000-0000-0000-0000-000000000000

# Or app-only with a certificate
$env:M365_TENANT_ID       = '00000000-0000-0000-0000-000000000000'
$env:M365_CLIENT_ID       = '00000000-0000-0000-0000-000000000000'
$env:M365_CERT_THUMBPRINT = '0000000000000000000000000000000000000000'
$env:AZ_SUBSCRIPTION_ID   = '00000000-0000-0000-0000-000000000000'
Connect-M365Admin -Service Azure

Run a report, check the CSV, then call Disconnect-M365Admin when you are done. The README lists the modules and roles each script needs.

More toolkits

I have more free toolkits that use the same pattern, including intune-powershell-toolkit, entra-id-powershell-toolkit and citrix-powershell-toolkit.

You can find them all on my GitHub profile.

Feedback welcome

Issues, ideas and pull requests are welcome. What would you add? Tell me in the comments.