New-CsDiagnosticHeaderConfiguration
上一次修改主题： 2012-03-23
创建新的诊断标头配置设置集合。诊断标头配置设置确定 SIP 消息是否附带提供对故障排除和错误报告有帮助的标头信息。
语法
New-CsDiagnosticHeaderConfiguration -Identity <XdsIdentity> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-SendToExternalNetworks <$true | $false>] [-SendToOutsideUnauthenticatedUsers <$true | $false>] [-WhatIf [<SwitchParameter>]]
详细说明
管理员可以选择将 MS 诊断标头附加到组织中发送的每条 SIP 消息。此消息（对最终用户不可见）包含可用于排除连接问题或报告错误的信息。例如，诊断标头可能包含错误代码，如果发生特定情况，客户端应用程序（例如 Microsoft Lync 2010）可以通过这些错误代码采取预先确定的操作过程。
对于在您的内部网络中发送的 SIP 消息，几乎没有理由不包括这些诊断标头：它们对消息大小影响甚微，而且可用作管理员尝试解决连接问题的宝贵工具。但是，诊断标头还可能包含您不希望提供给内部网络之外的人的信息，如 SIP 服务器的完全限定域名 (FQDN)。因此，诊断标头配置设置使您可以确定是否要将诊断标头发送给外部网络上的用户（例如，联盟域中的用户）和/或外部用户。（外部用户是已从内部网络外部连接但尚未通过身份验证的用户。）
默认情况下，诊断标头不包括在发送给外部网络用户或未经身份验证的用户的消息中。但是，可以修改全局诊断标头设置以对外部网络用户和/或未经身份验证的用户包括标头。或者，您还可在 site 作用域或 service 作用域（适用于边缘服务器或 Registrar 服务）创建自定义设置。这样，可以选择在从一个站点或通过一个 边缘服务器 发送的消息中包括诊断标头，而在从其他站点或通过其他边缘服务器发送的消息中禁止使用标头。
可使用 New-CsDiagnosticHeaderConfiguration cmdlet 创建自定义诊断标头设置。如前所述，可以在 site 作用域或 service 作用域（但仅限 边缘服务器 和 Registrar 服务）创建新设置。请记住，每个站点或服务只能有一个此类设置集合。例如，假设您尝试为 Redmond 站点创建一个新集合，而该站点已托管了一个诊断标头设置集合。在这种情况下，命令将会失败。同样，如果您尝试在 global 作用域创建新集合，命令也将失败。
谁能运行此 cmdlet：默认情况下，以下各组的成员有权在本地运行 New-CsDiagnosticHeaderConfiguration cmdlet：RTCUniversalServerAdmins。要返回分配了此 cmdlet 的所有基于角色的访问控制 (RBAC) 角色列表（包括您自己创建的任何自定义 RBAC 角色），请从 Windows PowerShell 提示符处运行以下命令：
Get-CsAdminRole | Where-Object {$_.Cmdlets –match "New-CsDiagnosticHeaderConfiguration"}
参数
| 参数 | 必需 | 类型 | 描述 |
|---|---|---|---|
Identity |
必需 |
Xds 标识 |
要创建的诊断标头配置设置的唯一标识符。要在 site 作用域创建新的设置集合，请使用以下类似语法：-Identity "site:Redmond"。要在 service 作用域创建新的设置集合，请使用以下类似语法：-Identity "service:EdgeServer:atl-cs-001.litwareinc.com"。 无法在 global 作用域创建新设置。此外，如果指定的站点或服务（例如 site:Redmond）已托管了一个设置集合，则无法在 site 作用域或 service 作用域创建新设置。 |
SendToExternalNetworks |
可选 |
布尔值 |
设置为 True 时，诊断标头将附加到发送给外部网络用户（例如，联盟域中的用户）的消息中。默认值为 False。 |
SendToOutsideUnauthenticatedUsers |
可选 |
布尔值 |
设置为 True 时，诊断标头将附加到发送给外部用户的消息中。外部用户是已从内部网络外部（例如，通过代理服务器）连接但尚未通过身份验证的用户。 默认值为 False。 |
Force |
可选 |
开关参数 |
禁止显示运行此命令时可能出现的任何非严重错误消息。 |
InMemory |
可选 |
开关参数 |
创建对象引用，但并不作为永久性更改实际提交对象。如果将使用此参数调用的 cmdlet 的输出分配给一个变量，您可以更改对象引用的属性，然后通过调用与此 cmdlet 匹配的 Set- cmdlet 提交这些更改。 |
WhatIf |
可选 |
开关参数 |
描述如果执行命令会发生什么情况（无需实际执行命令）。 |
Confirm |
可选 |
开关参数 |
在执行命令之前提示您进行确认。 |
输入类型
无。New-CsDiagnosticHeaderConfiguration 不接受通过管道传递的输入。
返回类型
New-CsDiagnosticHeaderConfiguration 创建 Microsoft.Rtc.Management.WritableConfig.Settings.Diagnostics.DiagnosticHeaderSettings 对象的新实例。
示例
-------------------------- 示例 1 --------------------------
New-CsDiagnosticHeaderConfiguration -Identity site:Redmond -SendToOutsideUnauthenticatedUsers $True
示例 1 为 Redmond 站点创建一个新的诊断标头配置 (-Identity site:Redmond)。除了指定 Identity 之外，该命令还使用 SendToOutsideAuthenticatedUsers 参数及参数值 $True；这样，便可以将信息发送给内部网络之外的未经身份验证的用户。
-------------------------- 示例 2 --------------------------
$x = New-CsDiagnosticHeaderConfiguration -Identity site:Redmond
$x.SendToOutsideUnauthenticatedUsers = $True
$x.SendToExternalNetworks = $True
Set-CsDiagnosticHeaderConfiguration -Instance $x
示例 2 中显示的命令演示如何创建一个最初仅存在于内存中的诊断标头设置集合。为执行此操作，此示例中的第一个命令调用带有 Identity 参数的 New-CsDiagnosticHeaderConfiguration。生成的对象存储在变量 $x 中。
在创建了虚拟设置之后，命令 2 和 3 分别用于修改 SendToOutsideUnauthenticatedUsers 和 SendToExternalNetworks 属性的值。最后，命令 4 用于将虚拟诊断标头配置设置转换为应用于 Redmond 站点的实际设置集合。请注意，最后一个命令是必需的。如果未调用 Set-CsDiagnosticHeaderConfiguration，则不会将任何设置应用于该站点，而且一旦结束 Windows PowerShell 会话或删除变量 $x，虚拟设置将立即消失。