Creates a new diagnostic filter configuration settings collection. Diagnostic filter configuration settings are used to determine whether traffic to or from a given domain or Uniform Resource Identifier (URI) is recorded in your Microsoft Communications Server 2010 log files.
Syntax
New-CsDiagnosticFilterConfiguration -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 filter configuration settings to be created. To create settings at the site scope, use syntax similar to this: -Identity "site:Redmond". To create settings at the service scope, use syntax similar to this: -Identity "service:EdgeServer:atl-cs-001.litwareinc.com". Settings can be created only for the Edge Server and Registrar services. |
|
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. (Technically, the host portion of a SIP address.) For example an FQDN (fully qualified domain name) 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. (Technically, 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 employed. If diagnostic filtering is enabled, this property will be ignored and traffic from all domains and URIs will be logged. |
|
Enabled |
Optional |
Boolean |
When set to True ($True), diagnostic filtering is enabled and only traffic from the domains or URIs listed in the Filter property is logged. When set to False (the default value), traffic from all domains and URIs is logged. |
|
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. |
|
Force |
Optional |
Switch Parameter |
Suppresses the display of any non-fatal error message that might arise when running the command. |
|
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 Communications 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 specific 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 filter configuration settings make it possible for you to specify the domains or URIs that will be recorded in the log files; if diagnostic filtering is enabled, then the only traffic to or from the specified domains will be logged. Communications Server enables you to create diagnostic filter settings at the site scope or the service scope (for either the Edge Server or the Registrar service). In turn, this enables you to apply filtering to, for instance, the Redmond site while leaving filtering disabled on your other sites. These new collections are created using the New-CsDiagnosticFilterConfiguration cmdlet.
Note that you cannot create diagnostic filter settings at the global scope; that’s because the global scope already hosts a collection of diagnostic filter settings. Likewise, you cannot create a new collection at the site or service scope if the specified site or service already contains a collection of diagnostic filter settings. For instance, your command will fail if you try to create a new collection for the Redmond site, and that site already hosts a collection of diagnostic filter settings.
Return Types
New-CsDiagnosticFilterConfiguration creates new instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Diagnostics.DiagnosticFilterSettings.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
New-CsDiagnosticFilterConfiguration -Identity site:Redmond -Enabled $True |
|
The preceding command creates a new collection of diagnostic filter configuration settings for the Redmond site. In addition to using the Identity parameter to specify the Identity, the Enabled parameter and the parameter value $True are used to enable the new collection.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsDiagnosticsFilter -Fqdn fabrikam.com -Uri user@fabrikam.com -Enabled $False New-CsDiagnosticFilterConfiguration -Identity site:Redmond -Enabled $True -Filter $x |
|
The commands shown in Example 2 create a new diagnostics filter and then assign that filter to a new collection of diagnostics filter settings. To carry out this task, the first command calls New-CsDiagnosticsFilter to create an in-memory-only diagnostics filter; this filter adds the FQDN fabrikam.com and the URI 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-DiagnosticFilterConfiguration is used to create a new collection of settings for the Redmond site. This new collection will be enabled (-Enabled $True) and will use the diagnostic filter stored in the variable $x.
-------------------------- Example 3 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsDiagnosticFilterConfiguration -Identity site:Redmond -InMemory $x.Enabled = $True Set-CsDiagnosticFilterConfiguration -Instance $x |
|
The commands shown in Example 3 demonstrate how you can create a diagnostic filter configuration collection that initially exists only in memory. To do this, the first command calls New-CsDiagnosticFilterConfiguration 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. (Note that the resulting object is stored in the variable $x.) After these virtual settings have been created, the second command is used to configure the virtual settings’ Enabled property to true ($True). The final command is then used to transform the virtual diagnostic filter 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-CsDiagnosticFilterConfiguration, no settings will be applied to the Redmond site, and the virtual settings will disappear as soon as you terminate your Windows PowerShell session or delete the variable $x.