Active Directory Health Check using PowerShell Tools (DCDiag)

Active Directory Health Check using PowerShell Tools (DCDiag). If you use Active Directory (AD) in your organization, it is probably your most critical system. Without it, users can’t log in, and machines can’t communicate. In addition it will teach us to gather information from AD with PowerShell using DCDiag. This article will also help us recognize and fix issues related to your AD environment.

The title of this article serves as a follow-up article to our previously published article regarding AD Health Check Using PowerShell and repadmin.

Active Directory Health Check Using DCDiag


If we would like to follow along with the guides in this tutorial and ensure they apply to your environment, ensure you have the following:


  • At least one Domain Controller (DC) running Windows Server 2012R2 or greater.
  • The Remote Server Administration Tools (RSAT) package
  • A GitHub repository that will be downloaded later on in this article.

Overview of DCDiag

DCDiag (domain controller diagnostics) is the Microsoft-approved way of validating Active Directory services. It’s installed on all servers with the Active Directory Domain Services role and Microsoft Windows 10 servers with the RSAT package.

You may refer to this article on how to install the RSAT package. To further visualize DCDiag, here is an example report that runs through a script that will output a report into an HTML format. In the following section, we will talk about the core components and arguments that make DCDiag useful.

Using DCDiag to Test AD Health with PowerShell

Using DCDiag, although a handy utility and a great addition to any Active Directory health check, has a significant drawback – the output. The result is produced using outdated formatting, which creates a loose string that is difficult to parse. You must convert that output into a PowerShell object to include DCDiag in a lengthy PowerShell AD health check routine.

It’s simple to turn the DCdiag result into an object we can send to reports, monitoring systems, test frameworks, and other applications by parsing and using DCDiag with Powershell.

The key to integrating PowerShell and DCDiag is running each dcdiag test separately with the /test: argument. Separating tests like this makes it much easier to distinguish a failed test from a passed one. In addition, note that dcdiag performs tests querying a DC’s event log. These tests return a different output structure and should be parsed with other techniques we will learn in this article.

However, if we want to run DCDiag on all tests, we can simply call the /s:<DCName> argument.

Setting up a Third Party Test-AdHcDcDiag PowerShell Function

You can utilize a specially created PowerShell function called Test-AdHcDcDiag to expedite the creation of your DCDiag parsing script. This function is available for download via a GitHub Gist here.

All dcdiag tests are run via the Test-AdhcDcDiag function, except for the DFSREvent, FRSEvent, and SystemLog tests. Additional benefit is that, we can use some settings in all AD environments to solve some of the problems that dcdiag does not handle by default. As shown below, you can make this function available in a PowerShell console by dot-sourcing.

					. C:\Path\To\Test-AdhcDcDiag.ps1

Running the Test-AdHcDcDiag PowerShell Function

We can call the function without using any parameters once it is accessible. An output similar to the one below should then appear. Of course, this assumes you’re like to execute DCDiag (the utility the function calls behind the scenes) on a domain controller.

					Source      : WINDCO1
TestName    : DCDiagCheckSecurityError
Pass        : True
Was         : {0, 0}
ShouldBe    : {0, 0}
Category    : DCDIAG
SubCategory : CheckSecurityError
Message     :
Data        : {........................ Test passed}
Tags        : {DCDIAG, CheckSecurityError}

However, manually invoking the code on call DCs would be too difficult. To avoid this, you can either additional supply DCs through the pipeline, as shown below, or by using the ComputerName argument, as indicated.

					Test-AdhcDCDiag -ComputerName WINDC02
"WINDC01","WINDC02" | Test-AdhcDCDiag

We can also perform particular tests by directly specifying them via the Tests parameter or excluding them via the ExcludeTests argument in your Active Directory health check using the Test-AdHcDcDiag function. Below is a sample of this syntax.

					Test-AdhcDCDiag -Tests DCPromo,RegisterInDNS
Test-AdhcDCDiag -ExcludeTests DCPromo

Testing Windows Event Logs for Errors

A crucial, proactive step for the early identification of potential issues is to check the event log for mistakes. Several tests in Dcdiag question the Windows event logs. However, these tests are noisy and will sometimes produce false-positive results, such as when DFS Replication (DFSR) pauses for backup.

If we build a PowerShell function that can filter out the noise, it will be easier to test Active Directory without dealing with false positives. Keep in mind that sending domain controller logs to a third-party logging solution that can issue a nearly immediate alarm is preferable.

Common Errors in the DFSR Event Log

Every DC’s DFSR service is in charge of replicating the SYSVOL folders that hold group policy files. Error events in the DFSR log are one sign of a bad DFSR. While we should investigate every event log error, not every error is significant. For instance, if error ID 9036 (paused for backup) is defined in the event, then event ID 5014 is a typical error.

Using DCDiag can generate noise and will always declare failure if executed incorrectly because it does not check for the error 9036 in the event viewer. The most trustworthy method for locating and tracking this particular issue. To view the DFS Replication log and filter out any events with the ID 5014 and an error ID of 9036 in the seventh string of the event, use the Get-EventLog or Get-WinEvent cmdlet. An example of this is shown below.

					$Events = Get-EventLog -LogName "DFS Replication" -EntryType Error -After (get-date).AddDays(-1)
$Events | Where-Object {$_.EventId -ne 5014 -and $_.ReplacementStrings[6] -ne 9036}

Next in Active Directory Health Check using PowerShell Tools (DCDiag) is to check if there is any duplicates in Active Directory Attributes. 

Checking for Duplicate AD Attributes

Even though they’re usually not a problem, duplicate AD attributes might become a nightmare in the appropriate situation. For instance, difficulties with Azure AD, Office 365 and general authentication issues will result from duplicating UPNs, mail, or ProxyAddresses properties. Duplicate attributes may also prevent the synchronization of that user’s AD attributes from succeeding.

Here the duplicate SPNs might result in even more significant issues with Kerberos and authentication related faults if Active Directory isn’t adequately tested. For example, if there are duplicate SPNs, authentication will fail when a user uses Kerberos to reference a particular SPN. Because Kerberos only expects one SPN, the attempt will fail.

Speeding up Duplicate AD Attribute Discovery

There are several different techniques to look for duplicate AD characteristics in PowerShell. There are more effective ways to combine characteristics than using Get-ADObject and the Group-Object cmdlets to query AD. Instead, you can expedite your search by using a hashtable. To apply this approach:

  1. Get every characteristic in a list
  2. Make a hashtable that has no keys.
  3. Put the attribute names and the number of instances in the hashtable’s keys.
  4. Find all greater-than-one hashtable values.

Below is the example snippet of code ran through PowerShell.

					$adAttribName = 'AttributeName'
$adAttrib = (Get-AdObject -LDAPFilter "$adAttribName=*" -Properties $adAttribName).$adAttribName

$hash = @{}

$adAttrib.foreach({ $hash[$_]++ })

$hash.GetEnumerator().where({ $_.Value -gt 1 }).Key

You may instantly identify any duplicate AD attribute by simply changing the value of the $adAttribName variable.

Usual AD Attribute Duplicates

A few attributes are recognized to be cause of problematic issues:

  • User principal names (UPNs)
  • Service principal names (SPNs)
  • mail attributes
  • proxyAddresses attributes

You may enter these characteristics into the script above to discover duplicate values for all of them using the search method explained in the previous section. To check,  replace the value of the $adAttribName just like the example below.

					$adAttribName = 'UserPrincipalName','ServicePrincipalName','mail','ProxyAddresses'

Active Directory Reporting and Monitoring Tool


Why don’t you have a look at our Reporting and monitoring tool by developed by Active Directory experts. With AD reporting solution you get detailed reports on Active Directory, Office 365, Azure AD on all your Active Directory Objects and attributes. That is the only SaaS reporting platform for Active Directory Auditing.

InfraSOS is the leading active directory reporting and monitoring tool on the market. In there you can have 200+ reports for Office 365 plus other comprehensive AD reports that can be exported in various formats.

Find your users that are active or inactive, blocked, locked out or have their accounts disabled. Information that can be reported includes the last time they had logged on or changed their passwords.

The Admin can also access information about the current status of user accounts, their security permissions, password expiry dates (or when they had changed their passwords), failed login attempts, and much more.

That tool offers unique settings, so that you can create custom filters to search for AD attributes – including missing attributes – based on user attribute entries.

Not to mention Active Directory Health Check reports that report on the status of the domain controller (DC) itself and any Domain Nameservers (DNS) with the ability to set alerts on AD DC replication statuses.

Thank you for reading about Active Directory Health Check using PowerShell Tools (DCDiag). Let’s conclude.

Active Directory Health Check using PowerShell Tools (DCDiag) Conclusion

This article discussed DCDiag’s purpose in checking our Active Directory environment. We also explored alternatives such as the third-party Test-ADHCDCDiag function, which efficiently checks the affected AD objects and their attributes. Finally, we discussed properly filtering out necessary Windows Events Logs and AD attributes to augment our DCDiag Health Check script.

Please check our blog content about Active Directory here.

Avatar for Marion Mendoza
Marion Mendoza

Windows Server and VMware SME. Powershell Guru. Currently working with Fortune 500 companies responsible for participating in 3rd level systems support across the enterprise. Acting as a Windows Server engineer and VMware Specialist.

0 0 votes
Article Rating
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x