PowerShell cmdlet Get Unhealthy Agents in SCOM

In customer environments where resources are strained and
agent health may have degraded over time this PowerShell cmdlet could help
identify the agents in your environment that are currently not functioning.
This sample cmdlet can verify if unavailable agents are responding to ping and
also remotely check if the HealthService is installed, running and whether it
is disabled or set to automatic startup. It also remotely gets the last five or
six event log errors from the OpsMgr Event log to help with diagnosing agent

Cmdlet gets all agents that are reporting to the specified
Management Group (RMS Server) and returns systems that are “Unavailable” and
not in maintenance mode. A System in maintenance mode returns unavailable as it
is not currently monitoring, so we exclude those systems from the list

This sample cmdlet takes two parameters:

  • First parameter is the RMS Server name, example
  • Second parameter is YES or NO, where YES will
    perform the remote checking via ping and WMI query to get the state of the
    HealthService. NO will only return the system names

Below are the instructions on how to install this sample
cmdlet on Windows Server 2008 R2 64 bit.

I ran this in a test environment and it does not have to run
on a RMS or MS to work. It must meet the below requirements in order to run

  • .NET 4.0 Framework
  • PowerShell
  • SCOM R2 Console (User Interface installed)
  • Run as account that has administrative rights to
    the SCOM Management Group
  • When using “YES” for second parameter: Run as
    account that has admin rights to systems remotely checking HealthService state
    OR will not return data for HealthService state

Download the ZIP file that contains PowerShell cmdlet dll
file and xml help file (GetUnhealthySCOMAgent.dll and UnhealthyAgentCheck.dll-Help.xml)
and save to c:\cmdlets

PowerShell can read from Powershell.exe.config file that adjusts settings PowerShell uses.  If the
Powershell.exe.config file does not exist in C:\WINDOWS\system32\WindowsPowerShell\v1.0
then create a Powershell.exe.config file in that directory. If the file exists
verify that it is similar to below if required add supportedRuntime v4 line to
ensure the cmdlet built on v4 of .NET will work.

Copy the contents below into the config file and save:

<?xml version=”1.0″?>



<supportedRuntime version=”v4.0.30319″/>

<supportedRuntime version=”v2.0.50727″/>



Open PowerShell and Run as administrator.

Run commands below:

set-alias installutil $env:windir\Microsoft.Net\Framework64\v4.0.30319\installutil

cd c:\cmdlets

installutil .\GetUnhealthySCOMAgent.dll

get-Pssnapin -registered

Verify the cmdlet is displayed in the registered list by running below command

add-pssnapin GetUnhealthySCOMAgentPSSnapin

 Get-UnhealthyAgent MMSCOMRMS NO


It is likely that your list is larger than mine, so you may want to pipe results to some file and then copy the contents to excel. Strings
are tab delimited so it will format nicely with a paste into Excel.

Get-UnhealthyAgent MMSCOMRMS YES | out-file

Then you can open the file and copy and paste to Excel.


NOTE: This is the command line to use if you want to uninstall the cmdlet:

installutil /u .\GetUnhealthySCOMAgent.dll

Cmdlets can help automate many tasks to reduce workload and improve your environments health. Let me know what you think.


This example is provided “AS IS” with no warranty expressed
or implied. Run at your own risk.

The opinions and views expressed in this
blog are those of the author and do not necessarily state or reflect those of


Comments (0)

Skip to main content