[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Creates a new diagnostic filter to be used with a collection of diagnostic filter configuration settings. 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-CsDiagnosticFilter [-Enabled <$true | $false>] [-ExcludeConferenceMessages <$true | $false>] [-ExcludePresenceNotifications <$true | $false>] [-ExcludeRegisterMessages <$true | $false>] [-Fqdn <PSListModifier>] [-Uri <PSListModifier>]

Parameters

Parameter Required Type Description

Fqdn

Optional

PS List Modifier

Collection of domains to be included in the filter. (More technically, 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 have more than one domain in a single filter.

Uri

Optional

PS List Modifier

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.

ExcludeConferenceMessages

Optional

Boolean

If set to True, information about conference messages will not be recorded in the log files. The default value is False.

ExcludePresenceNotifications

Optional

Boolean

If set to True, information about presence notifications will not be recorded in the log files. The default value is False.

ExcludeRegisterMessages

Optional

Boolean

If set to True, information about client registrations will not be recorded in the log files. The default value is False.

Enabled

Required

Boolean

Indicates whether or not the filter should be employed. The default value is True ($True).

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.

On the other hand, this can also result in cases of 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, say, the Redmond site while leaving filtering disabled on your other sites.

The New-CsDiagnosticsFilter enables you to add an actual filter to a collection of diagnostic filter settings. This collection contains the domains and URIs that will have their traffic recorded in the log files. If diagnostic filtering is enabled, only information pertaining to the domains and URIs in the filter will be logged; for logging purposes, traffic from other domains and URIs will be ignored.

Note that the New-CsDiagnosticsFilter cmdlet creates in-memory-only instances of a diagnostic filter. After creating one of these virtual filters, you will then need to use either New-CsDiagnosticFilterConfiguration or Set-CsDiagnosticFilterConfiguration to add the filter to a collection.

Return Types

New-CsDiagnosticsFilter creates new instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Diagnostics.Filter object.

Examples

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

Copy Code
$x = New-CsDiagnosticsFilter -Fqdn "fabrikam.com" -Enabled $False
Set-CsDiagnosticFilterConfiguration -Identity global -Filter $x 

The commands shown in Example 1 use New-CsDiagnosticsFilter to create a new diagnostic filter and then assign that filter to the global collection of diagnostic filter settings. To carry out this task, the first command calls New-CsDiagnosticsFilter to create an in-memory-only diagnostic 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 the second command, Set-DiagnosticFilterConfiguration is used to assign the new filter to the global collection of diagnostic filter settings. In this case, any existing values in the Filter property will be replaced by the newly-created filter stored in $x.

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

Copy Code
$x = New-CsDiagnosticsFilter -Fqdn "fabrikam.com","contoso.com" -Enabled $False
Set-CsDiagnosticFilterConfiguration -Identity global -Filter $x

The commands shown in Example 2 are a variation of the commands shown in Example 1; in Example 2, however, two FQDNs (fabrikam.com and contoso.com) are added to the filter’s Fqdn property. To do this, both names (separated by a comma) are used as parameter values for the Fqdn parameter.