When testing Functions in PowerShell or just executing cmdlets, you don’t always get enough information when things don’t work. The Trace-Command cmdlet is a valuable tool that gives you much information about what’s going on behind the scenes. In this blog post, I will show you how to use it.
Sources that Trace-Command can use
There are different sources that Trace-Command can use to show you debug information. To get a list of the resources that are available on your system, you can use the following: (With sorting options and a well-formatted Table view)
Get-TraceSource | Sort-Object Name | Format-Table -AutoSize
On my system, these sources are available:
Using Trace-Command
Now that we have a list of trace sources, we can use that to debug specific things. In the example below, I use Trace-Command to test the DomainName parameter of one of my scripts.
Note: The -PSHost parameter specifies that the output should be shown on the screen. You can replace it with the -FilePath parameter to output it to a text file. For example, “Trace-Command -Name ParameterBinding -Expression {Get-MailDomainInfo -DomainName powershellisfun.com} -FilePath c:\temp\debug.txt”
C:\Users\HarmVeenstra> Trace-Command -Name ParameterBinding -Expression {Get-MailDomainInfo -DomainName powershellisfun.com} -PSHost
DEBUG: 2023-03-06 18:06:08.9569 ParameterBinding Information: 0 : BIND NAMED cmd line args [Get-MailDomainInfo]
DEBUG: 2023-03-06 18:06:08.9572 ParameterBinding Information: 0 : BIND arg [powershellisfun.com] to parameter [DomainName]
DEBUG: 2023-03-06 18:06:08.9574 ParameterBinding Information: 0 : Executing DATA GENERATION metadata: [System.Management.Automation.ArgumentTypeConverterAttribute]
DEBUG: 2023-03-06 18:06:08.9576 ParameterBinding Information: 0 : result returned from DATA GENERATION: powershellisfun.com
DEBUG: 2023-03-06 18:06:08.9578 ParameterBinding Information: 0 : COERCE arg to [System.String]
DEBUG: 2023-03-06 18:06:08.9581 ParameterBinding Information: 0 : Parameter and arg types the same, no coercion is needed.
DEBUG: 2023-03-06 18:06:08.9584 ParameterBinding Information: 0 : BIND arg [powershellisfun.com] to param [DomainName] SUCCESSFUL
DEBUG: 2023-03-06 18:06:08.9587 ParameterBinding Information: 0 : BIND POSITIONAL cmd line args [Get-MailDomainInfo]
DEBUG: 2023-03-06 18:06:08.9590 ParameterBinding Information: 0 : MANDATORY PARAMETER CHECK on cmdlet [Get-MailDomainInfo]
DEBUG: 2023-03-06 18:06:08.9593 ParameterBinding Information: 0 : BIND arg [] to parameter [DNSserver]
DEBUG: 2023-03-06 18:06:08.9596 ParameterBinding Information: 0 : Executing DATA GENERATION metadata: [System.Management.Automation.ArgumentTypeConverterAttribute]
DEBUG: 2023-03-06 18:06:08.9598 ParameterBinding Information: 0 : result returned from DATA GENERATION:
DEBUG: 2023-03-06 18:06:08.9599 ParameterBinding Information: 0 : COERCE arg to [System.String]
DEBUG: 2023-03-06 18:06:08.9600 ParameterBinding Information: 0 : Parameter and arg types the same, no coercion is needed.
DEBUG: 2023-03-06 18:06:08.9601 ParameterBinding Information: 0 : BIND arg [] to param [DNSserver] SUCCESSFUL
DEBUG: 2023-03-06 18:06:08.9602 ParameterBinding Information: 0 : CALLING BeginProcessing
DEBUG: 2023-03-06 18:06:08.9603 ParameterBinding Information: 0 : CALLING ProcessRecord
DEBUG: 2023-03-06 18:06:08.9604 ParameterBinding Information: 0 : CALLING EndProcessing
DEBUG: 2023-03-06 18:06:08.9606 ParameterBinding Information: 0 : BIND NAMED cmd line args [Resolve-DnsName]
DEBUG: 2023-03-06 18:06:08.9607 ParameterBinding Information: 0 : BIND arg [autodiscover.powershellisfun.com] to parameter [Name]
DEBUG: 2023-03-06 18:06:08.9608 ParameterBinding Information: 0 : COERCE arg to [System.String]
DEBUG: 2023-03-06 18:06:08.9609 ParameterBinding Information: 0 : Parameter and arg types the same, no coercion is needed.
DEBUG: 2023-03-06 18:06:08.9610 ParameterBinding Information: 0 : Executing VALIDATION metadata: [System.Management.Automation.ValidateNotNullOrEmptyAttribute]
DEBUG: 2023-03-06 18:06:08.9611 ParameterBinding Information: 0 : BIND arg [autodiscover.powershellisfun.com] to param [Name] SUCCESSFUL
DEBUG: 2023-03-06 18:06:08.9611 ParameterBinding Information: 0 : BIND arg [A] to parameter [Type]
DEBUG: 2023-03-06 18:06:08.9612 ParameterBinding Information: 0 : COERCE arg to [Microsoft.DnsClient.Commands.RecordType]
DEBUG: 2023-03-06 18:06:08.9613 ParameterBinding Information: 0 : Trying to convert argument value from System.String to Microsoft.DnsClient.Commands.RecordType
DEBUG: 2023-03-06 18:06:08.9614 ParameterBinding Information: 0 : CONVERT arg type to param type using LanguagePrimitives.ConvertTo
DEBUG: 2023-03-06 18:06:08.9615 ParameterBinding Information: 0 : CONVERT SUCCESSFUL using LanguagePrimitives.ConvertTo: [A]
DEBUG: 2023-03-06 18:06:08.9616 ParameterBinding Information: 0 : Executing VALIDATION metadata: [System.Management.Automation.ValidateRangeAttribute]
DEBUG: 2023-03-06 18:06:08.9617 ParameterBinding Information: 0 : BIND arg [A] to param [Type] SUCCESSFUL
DEBUG: 2023-03-06 18:06:08.9618 ParameterBinding Information: 0 : BIND arg [1.1.1.1] to parameter [Server]
DEBUG: 2023-03-06 18:06:08.9619 ParameterBinding Information: 0 : COERCE arg to [System.String[]]
DEBUG: 2023-03-06 18:06:08.9620 ParameterBinding Information: 0 : Trying to convert argument value from System.String to System.String[]
DEBUG: 2023-03-06 18:06:08.9621 ParameterBinding Information: 0 : ENCODING arg into collection
DEBUG: 2023-03-06 18:06:08.9622 ParameterBinding Information: 0 : Binding collection parameter Server: argument type [String], parameter type [System.String[]], collection type Array, element type [System.String], coerceElementType
This is only a part of the output that Trace-Command will give you, but you can see the following things:
- The -DomainName parameter was used, and the output was considered a String.
- The -DNSserver parameter was empty.
- The Resolve-DnsName cmdlet was used to find the autodiscover.powershellisfun.com DNS A-record using 1.1.1.1 as the Server being queried.
When specifying the ParameterBinding Trace-Source, it only looks for that. You can also specify * to let Trace-Command run using all the Trace-Source options. This will give you 510 lines of debugging information. When only the ParameterBinding source was used it was 329 lines. You should always try to be as specific as possible, and you can use multiple sources with a comma operator. For example:
Trace-Command -Name ParameterBinding, MemberResolution -Expression {Get-MailDomainInfo -DomainName powershellisfun.com} -PSHost
This will add more information to your Trace-Command but not too much like when using the * for the -Name parameter:
DEBUG: 2023-03-06 18:23:07.2935 MemberResolution Information: 0 : Lookup DEBUG: 2023-03-06 18:23:07.2936 MemberResolution Information: 0 : "Domain Name" NOT present in type table. DEBUG: 2023-03-06 18:23:07.2938 MemberResolution Information: 0 : Adapted member: not found. DEBUG: 2023-03-06 18:23:07.2939 MemberResolution Information: 0 : Lookup DEBUG: 2023-03-06 18:23:07.2940 MemberResolution Information: 0 : "Autodiscover IP-Address" NOT present in type table. DEBUG: 2023-03-06 18:23:07.2942 MemberResolution Information: 0 : Adapted member: not found. DEBUG: 2023-03-06 18:23:07.2943 MemberResolution Information: 0 : Lookup DEBUG: 2023-03-06 18:23:07.2944 MemberResolution Information: 0 : "Autodiscover CNAME " NOT present in type table. DEBUG: 2023-03-06 18:23:07.2946 MemberResolution Information: 0 : Adapted member: not found. DEBUG: 2023-03-06 18:23:07.2949 MemberResolution Information: 0 : Lookup DEBUG: 2023-03-06 18:23:07.2953 MemberResolution Information: 0 : "DKIM Record" NOT present in type table. DEBUG: 2023-03-06 18:23:07.2957 MemberResolution Information: 0 : Adapted member: not found. DEBUG: 2023-03-06 18:23:07.2961 MemberResolution Information: 0 : Lookup DEBUG: 2023-03-06 18:23:07.2963 MemberResolution Information: 0 : "DMARC Record" NOT present in type table. DEBUG: 2023-03-06 18:23:07.2965 MemberResolution Information: 0 : Adapted member: not found. DEBUG: 2023-03-06 18:23:07.2966 MemberResolution Information: 0 : Lookup DEBUG: 2023-03-06 18:23:07.2968 MemberResolution Information: 0 : "MX Record(s)" NOT present in type table. DEBUG: 2023-03-06 18:23:07.2970 MemberResolution Information: 0 : Adapted member: not found. DEBUG: 2023-03-06 18:23:07.2973 MemberResolution Information: 0 : Lookup DEBUG: 2023-03-06 18:23:07.2976 MemberResolution Information: 0 : "SPF Record" NOT present in type table. DEBUG: 2023-03-06 18:23:07.2978 MemberResolution Information: 0 : Adapted member: not found.
More information
You can go to https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/trace-command?view=powershell-7.3 for more parameter options and general information.