Set-CsDiagnosticHeaderConfiguration [-Identity <XdsIdentity>] [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-SendToExternalNetworks <$true | $false>] [-SendToOutsideUnauthenticatedUsers <$true | $false>] [-WhatIf [<SwitchParameter>]]

Set-CsDiagnosticHeaderConfiguration [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Instance <PSObject>] [-SendToExternalNetworks <$true | $false>] [-SendToOutsideUnauthenticatedUsers <$true | $false>] [-WhatIf [<SwitchParameter>]]

Parameters

When you send SIP (Session Initiation Protocol) messages, you have the option of attaching an ms-diagnostics header to each message. This message (which is not visible to end users) contains information that might be useful in troubleshooting connection problems or in reporting errors. For example, the diagnostics header might contain error codes that enable the client application (for example, Communicator) to take a predetermined course of action should a specific situation arise.

For SIP messages sent within your internal network, there’s little reason not to include these diagnostic headers: they have a minimal impact on message size and can be an invaluable tool for administrators trying to troubleshoot connectivity problems. However, diagnostic headers also contain information, such as the fully qualified domain names of your SIP servers, that you might not want to make available to people outside the internal network. Because of this, the diagnostics header configuration settings enable you to decide whether you want diagnostics headers sent to users on external networks (such as users in a federated domain) and/or to unauthenticated users (for example, anonymous users participating in an online conference). By default, headers are not included in messages sent either to external networks or to unauthenticated users. However, you can modify the global diagnostics header settings to include headers to external networks and/or unauthenticated users. Alternatively, you can create custom settings at the site scope or at the service scope (for the Edge Server or Registrar service). That way, you can choose to include diagnostics headers on messages sent from one site, or through one Edge Server, while disallowing headers on messages sent from other sites or through other Edge Servers.

The Set-CsDiagnosticsHeaderConfiguration cmdlet provides a way for you to modify an existing diagnostic header configuration setting collection. You can use this cmdlet to enable (or disable) the transmission of diagnostic headers to external networks and/or to unauthenticated users.

Set-CsDiagnosticHeaderConfiguration does not return any objects or values. Instead, the cmdlet modifies existing instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Diagnostics.DiagnosticHeaderSettings object.

-------------------------- Example 1 ------------------------

	Copy Code
Set-CsDiagnosticHeaderConfiguration -Identity site:Redmond -SendToOutsideUnauthenticatedUsers $True

The preceding command modifies the diagnostic header configuration settings that have the Identity site:Redmond. In this example, the value of the SendToOutsideUnauthenticatedUsers property is set to True ($True).

-------------------------- Example 2 ------------------------

	Copy Code
Get-CsDiagnosticHeaderConfiguration | Set-CsDiagnosticHeaderConfiguration -SendToOutsideUnauthenticatedUsers $True

The command shown in Example 2 is a variation of the command shown in Example 1; in this case, however, the SendToOutsideUnauthenticatedUsers property is updated for all the diagnostic header configuration settings currently in use. To do this, Get-CsDiagnosticHeaderConfiguration is first called without any parameters; this returns a collection of all the diagnostic header settings currently in use. This collection is then piped to Set-CsDiagnosticHeaderConfiguration, which sets the SendToOutsideUnauthenticatedUsers property of each item in the collection to True ($True).

-------------------------- Example 3 ------------------------

	Copy Code
Get-CsDiagnosticHeaderConfiguration | Where-Object {$_.SendToExternalNetworks -eq $True} | Set-CsDiagnosticHeaderConfiguration -SendToOutsideUnauthenticatedUsers $True

In Example 3, the SendToOutsideUnauthenticatedUsers property is modified again, but this time only for those diagnostic header settings where the SendToExternalNetworks property is True. To carry out this task, the command first uses Get-CsDiagnosticHeaderConfiguration to return a collection of all the diagnostic header configuration settings currently in use. That collection is piped to the Where-Object cmdlet, which selects only those settings where the SendToExternalNetworks property is equal to (-eq) true ($True). That filtered collection is then piped to Set-CsDiagnosticHeaderConfiguration, which takes each item in the collection and sets the value of the SendToOutsideUnauthenticatedUsers property to True.