See Also
Topic Last Modified: 2010-11-04
Creates new diagnostic configuration settings. Diagnostic configuration settings are used to determine whether traffic to or from a given domain or Uniform Resource Identifier (URI) is recorded in your Microsoft Lync Server 2010 log files.
Syntax
New-CsDiagnosticConfiguration -Identity
<XdsIdentity> [-Confirm [<SwitchParameter>]] [-Enabled
<$true | $false>] [-Filter <Filter>] [-Force
<SwitchParameter>] [-InMemory <SwitchParameter>]
[-WhatIf [<SwitchParameter>]]
|
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Required |
Xds Identity |
Unique identifier for the diagnostics configuration settings to be created. Because new settings can only be created at the site scope you must use syntax similar to this: -Identity "site:Redmond". |
|
Filter |
Optional |
PS List Modifier |
Collection of domains and URIs whose traffic will be logged if diagnostic filtering is enabled. The Filter property consists of three separate items: Fqdn – Collection of domains to be included in the filter. (More technically, this is the host portion of a SIP address.) For example a fully qualified domain name (FQDN) might look like this: fabrikam.com. Alternatively, you can use wildcards to represent multiple domains: *.fabrikam.com. You can include more than one domain in a single filter. Uri – Collection of URIs to be included in the filter. (The Uri is the user@host portion of a SIP address.) A Uri can consist of any of the following patterns: user@fabrikam.com; user@*; *@fabrikam.com. You can include multiple URIs in a single filter. Enabled – Indicates whether or not the filter should be activated. |
|
LoggingShare |
Optional |
String |
Shared folder where the diagnostic logs can be uploaded. |
|
Force |
Optional |
Switch Parameter |
Suppresses the display of any non-fatal error message that might arise when running the command. |
|
InMemory |
Optional |
Switch Parameter |
Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet’s matching Set- cmdlet. |
|
WhatIf |
Optional |
Switch Parameter |
Describes what would happen if you executed the command without actually executing the command. |
|
Confirm |
Optional |
Switch Parameter |
Prompts you for confirmation before executing the command. |
Detailed Description
If you enable logging for Lync Server 2010 then, by default, traffic traveling to or from any domain or URI is included in those log files. This ensures that as much information as possible is recorded in the log files.
However, this can occasionally result in too much information. For example, if you are experiencing connectivity problems with a particular domain, you might want to limit logging to traffic between your network and that domain; that makes it easier for you to identify the relevant records and, in turn, might make it easier for you to diagnose and correct the problem.
Diagnostic configuration settings make it possible for you to specify the domains or URIs that will be recorded in the log files; for example, you can log only the traffic to or from specified domains. Lync Server enables you to create diagnostic configuration settings at the site scope. In turn, this enables you to apply different settings to, say, the Redmond site than you do on your other sites.
Note that you cannot create diagnostic configuration settings at the global scope; that’s because the global scope already hosts these settings. Likewise, you cannot create a new settings collection at the site scope if the specified site already contains diagnostic configuration settings. For example, your command will fail if you try to create a new collection for the Redmond site and that site already hosts diagnostic configuration settings.
Who can run this cmdlet: By default, members of the following groups are authorized to run the New-CsDiagnosticConfiguration cmdlet locally: RTCUniversalServerAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:
Get-CsAdminRole | Where-Object {$_.Cmdlets –match "New-CsDiagnosticConfiguration"}
Input Types
None. New-CsDiagnosticConfiguration does not accept pipelined input.
Return Types
New-CsDiagnosticConfiguration creates new instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Diagnostics.DiagnosticFilterSettings.
Example
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
New-CsDiagnosticConfiguration -Identity site:Redmond |
|
The preceding command creates a new collection of diagnostic configuration settings for the Redmond site.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsDiagnosticsFilter -Fqdn fabrikam.com -Uri "sip:user@fabrikam.com" -Enabled $False New-CsDiagnosticConfiguration -Identity site:Redmond -Filter $x |
|
The commands shown in Example 2 create a new diagnostics filter and then assign that filter to a new collection of diagnostic settings. To carry out this task, the first command calls New-CsDiagnosticsFilter to create an in-memory-only diagnostics filter; this command adds the FQDN fabrikam.com and the URI sip:user@fabrikam.com to the filter. The command also sets the Enabled property to True ($True) in order to activate the filter. The resulting virtual filter is then stored in the variable $x.
In command 2, New-CsDiagnosticConfiguration is used to create a new diagnostic configuration settings collection for the Redmond site. These new settings will use the diagnostic filter stored in the variable $x.
-------------------------- Example 3 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsDiagnosticConfiguration -Identity site:Redmond -InMemory $x.LoggingShare = "\\atl-fs-001\logs" Set-CsDiagnosticConfiguration -Instance $x |
|
The commands shown in Example 3 demonstrate how you can create diagnostic configuration settings that initially exist only in memory. To do this, the first command calls New-CsDiagnosticConfiguration along with two parameters: Identity (which specifies the Identity for the settings) and InMemory, which indicates that the new settings should be created in memory only. The resulting object is stored in the variable $x.
After the virtual settings have been created, the second command is used to configure the LoggingShare property to the UNC path \\atl-fs-001\logs. The final command is then used to transform the virtual diagnostic configuration settings into an actual collection of settings applied to the Redmond site. Note that this final command is mandatory. If you do not call Set-CsDiagnosticConfiguration, no settings will be applied to the Redmond site, and the virtual settings will disappear as soon as you end your Windows PowerShell session or delete the variable $x.