Use DcDiag with PowerShell to check domain controller health

• Author
• Recent Posts

Adam Bertram

Adam Bertram is a 20-year IT veteran, Microsoft MVP, blogger, and trainer.

Latest posts by Adam Bertram (see all)

• Create a certificate-signed RDP shortcut via Group Policy - Fri, Aug 9 2019
• Monitor web server uptime with a PowerShell script - Tue, Aug 6 2019
• How to build a PowerShell inventory script for Windows Servers - Fri, Aug 2 2019

In the earlier 2000s, a command-line utility that returned dumb strings would have been OK, but today we have smart objects with PowerShell! Let's build a wrapper around the dcdiag tool with PowerShell to bring this handy tool into the current times.

If you run dcdiag by itself, you can see that it returns some useful information, but this is just loose text. Dcdiag does not return objects we can parse and manipulate as we can in PowerShell.

Use DcDiag with PowerShell to check domain controller health

To wrap this tool in PowerShell, we'll need to build a function. I'll call my function Invoke-DcDiag. We can get crazy with this, but to keep it simple, I want to pass a single domain controller (DC) to dcdiag, so I'll create this function with a parameter called DomainController.

function Invoke-DcDiag {
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$DomainController
    )

    ## Code goes here
}

Once I've built the skeleton, I can then add in the code. To run dcdiag against a domain controller, I need to use the /s switch, so I'll add that to my function. I need to capture the output, so I'll assign it to a variable. To mimic the code that will go into the function, I'll assign $DomainController a value of DC representing the name of the DC in my environment.

$DomainController = 'DC'
$result = dcdiag /s:$DomainController

I've now captured the output to a variable. That's great and all, but we now need to parse the output. Let's get our regex on! Before we get that far though, I need to define what the output should look like. Eyeballing our sample output, it seems like for every test that happens, dcdiag always returns one of two strings:

<DomainControllerName> passed test <TestName>
<DomainControllerName> failed test <TestName>

I want PowerShell to return an object for each test result with a TestName, TestResult, and an EntityName to represent a domain controller, NT Directory Service (NTDS) partition, or whatever else the test is running against.

We'll need to parse each line in the string. One way to do this is to use Select-String. Select-String has a parameter called Pattern that allows us to try to match a string against a regular expression. Without teaching you regex, I'll give you the answer here. The regex you need for this is '\. (.*) \b(passed|failed)\b test (.*)'.

When you run it as is, you may think that either I'm crazy or it doesn't work. One of these things is right.

PS> $dcDiagOutput | select-string -pattern '\. (.*) \b(passed|failed)\b test (.*)'

         ......................... DC passed test Connectivity
         ......................... DC passed test Advertising
         ......................... DC passed test FrsEvent
         ......................... DC passed test DFSREvent
         ......................... DC passed test SysVolCheck
         ......................... DC passed test KccEvent
         ......................... DC passed test KnowsOfRoleHolders

However, PowerShell is hiding regex groups from you. Each regex group contains each of the properties we'd like the resulting output to have. We reference these groups by looking at the various indexes in the Groups array that the Matches property contains that Select-String returns.

You can see below that I'm looping over each match, assigning each group value to an object property we'd like, and then returning the object.

$result | select-string -pattern '\. (.*) \b(passed|failed)\b test (.*)' | foreach {
    $obj = @{
        TestName = $_.Matches.Groups[3].Value
        TestResult = $_.Matches.Groups[2].Value
        Entity = $_.Matches.Groups[1].Value
    }
    [pscustomobject]$obj
}

Bringing this code all back into our function makes the function look like this:

function Invoke-DcDiag {
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$DomainController
    )

    $result = dcdiag /s:$DomainController
    $result | select-string -pattern '\. (.*) \b(passed|failed)\b test (.*)' | foreach {
        $obj = @{
            TestName = $_.Matches.Groups[3].Value
            TestResult = $_.Matches.Groups[2].Value
            Entity = $_.Matches.Groups[1].Value
        }
        [pscustomobject]$obj
    }
}

At this time, we bring this function into our session, run it via Invoke-DcDiag -DomainController DC, and voila, dcdiag for the modern age!

PS> Invoke-DcDiag -DomainController DC

TestResult Entity          TestName
---------- ------          --------
passed     DC              Connectivity
passed     DC              Advertising
passed     DC              FrsEvent
passed     DC              DFSREvent
passed     DC              SysVolCheck
passed     DC              KccEvent
passed     DC              KnowsOfRoleHolders
passed     DC              MachineAccount
passed     DC              NCSecDesc
passed     DC              NetLogons
passed     DC              ObjectsReplicated
passed     DC              Replications
passed     DC              RidManager
passed     DC              Services
passed     DC              SystemLog
passed     DC              VerifyReferences
passed     ForestDnsZones  CheckSDRefDom
passed     DomainDnsZones  CheckSDRefDom
passed     Schema          CheckSDRefDom
passed     Schema          CrossRefValidation
passed     Configuration   CheckSDRefDom
passed     Configuration   CrossRefValidation
passed     techsnips       CheckSDRefDom
passed     techsnips       CrossRefValidation
passed     techsnips.local LocatorCheck
passed     techsnips.local Intersite