Exchange Server 2010 : Object-Oriented Use of PowerShell (part 1) - Filtering Output

PowerShell is even more flexible because the output of commands is not text-based, but rather object-based. PowerShell uses an object model that is based on the Microsoft .NET Framework. PowerShell cmdlets accept and return structured data. Don't let the terms "object model" or "object oriented" scare you, though. This is really quite simple. For example, Figure 1 shows the output of the Get-Mailbox cmdlet.

Figure 1. Output of the Get-Mailbox cmdlet

What you see on the screen is text to the user interface, but to PowerShell it is really a list of objects. You can manipulate the output to see the properties you want, filter the output, or pipe the output (the objects) to another cmdlet.

1. Filtering Output

In Figure 1, you can see that the cmdlet we used (Get-Mailbox) outputs every mailbox in the entire organization. There are a number of ways that you can filter or narrow the scope of the output that you are looking for from a specific cmdlet. In the case of Get-Mailbox and other cmdlets, you can specify just the identity of the mailbox that you are looking for.

PowerShell includes two options that can be used specifically for filtering the output. These are the Where-Object (or Where alias) and the Filter-Object (or Filter) objects. The Where clause can be used on most cmdlets and the filter is applied at the client. The Filter clause is only available on a subset of the commands because this filter is applied by the server.

Get-Mailbox | Where-Object {$_.MaxSendSize -gt 25000000}

In the preceding command, the output of the Get-Mailbox cmdlet is piped to the Where clause, which filters the output. In this case, the output is any mailbox whose -MaxSendSize parameter is greater than 25,000,000 bytes. Did you notice the portion of the Where statement $_.MaxSendSize? The $_ portion represents the current object that is being piped to the Where-Object cmdlet, and .MaxSendSize represents the MaxSendSize property of that object.

For nonprogrammers, this might seem a little difficult at first, but we promise it gets much easier as you go along. The operators are also simple to remember. Table 1Where-Object or just the Where alias. shows a list of common operators that can be used in clauses such as

Sometimes, finding all of the properties that can be used with a particular cmdlet can be difficult. There are a couple of tips that we would like to share that will help illustrate or discover these properties. Let's take the Set-Mailbox cmdlet as an example. First, you can simply use the available online help such as this:

set-mailbox -?

NAME
    Set-Mailbox

SYNOPSIS
    Use the Set-Mailbox cmdlet to modify the settings of an existing
mailbox. You can use this cmdlet for one mailbox at a time. To perform bulk
management, you can pipeline the output of various Get- cmdlets (for
example, the Get-Mailbox or Get-User cmdlets) and configure several
mailboxes in a single-line command. You can also use the Set-Mailbox cmdlet
in scripts.


SYNTAX
    Set-Mailbox -Identity <MailboxIdParameter> [-AcceptMessagesOnlyFrom
<RecipientIdParameter[]>] [-AcceptMessagesOnlyF
    romDLMembers <RecipientIdParameter[]>]
[-AcceptMessagesOnlyFromSendersOrMembers  <RecipientIdParameter[]>]
[-Alias <String>]
[-AntispamBypassEnabled <$true |
$false>] [-ApplyMandatoryProperties <SwitchParameter>] [-Arbitration
<SwitchParameter>] [-ArbitrationMailbox <MailboxIdParameter>] [-ArchiveName
<MultiValuedProperty>] [-ArchiveQuota <Unlimited>] [-ArchiveWarningQuota
<Unlimited>] [-BypassModerationFromSendersOrMembers <RecipientIdParameter[]>]
[-CalendarRepairDisabled <$true | $false>] [-CalendarVersionStoreDisabled <$true
| $false>] [-Confirm [<SwitchParameter>]] [-CreateDTMFMap <$true | $false>]
[-CustomAttribute1 <String>] [-CustomAttribute10 <String>] [-CustomAttribute11
<String>] [-CustomAttribute12 <String>] [-CustomAttribute13 <String>]
[-CustomAttribute14 <String>] [-CustomAttribute15 <String>] [-CustomAttribute2
<String>] [-CustomAttribute3 <String>] [-CustomAttribute4 <String>]
[-CustomAttribute5 <String>] [-CustomAttribute6 <String>] [-CustomAttribute7
<String>] [-CustomAttribute8 <String>] [-CustomAttribute9 <String>] [-Database
<DatabaseIdParameter>] [-DeliverToMailboxAndForward <$true | $false>]
[-DisplayName <String>] [-DomainController <Fqdn>]
[-DowngradeHighPriorityMessagesEnabled <$true | $false>] [-EmailAddresses
<ProxyAddressCollection>] [-EmailAddressPolicyEnabled <$true | $false>]
[-EndDateForRetentionHold <Nullable>] [-ExternalOofOptions <InternalOnly |
External>] [-Force <SwitchParameter>] [-ForwardingAddress
<RecipientIdParameter>] [-GrantSendOnBehalfTo
<MailboxOrMailUserOrMailContactIdParameter[]>]
[-HiddenFromAddressListsEnabled <$true | $false>] [-IgnoreDefaultScope
<SwitchParameter>] [-IssueWarningQuota <Unlimited>] [-Languages
<MultiValuedProperty>] [-LinkedCredential <PSCredential>] [-LinkedDomainController

					  

<String>] [-LinkedMasterAccount <UserIdParameter>] [-LitigationHoldEnabled
<$true | $false>] [-MailboxPlan <MailboxPlanIdParameter>] [-MailTip <String>]
[-MailTipTranslations <MultiValuedProperty>] [-ManagedFolderMailboxPolicy
<MailboxPolicyIdParameter>] [-ManagedFolderMailboxPolicyAllowed <SwitchParameter>]
[-MaxBlockedSenders <Nullable>] [-MaxReceiveSize <Unlimited>] [-MaxSafeSenders
<Nullable>] [-MaxSendSize <Unlimited>] [-MessageTrackingReadStatusEnabled <$true
| $false>] [-ModeratedBy <MultiValuedProperty>] [-ModerationEnabled <$true
| $false>]
[-Name <String>] [-Office <String>] [-OfflineAddressBook
<OfflineAddressBookIdParameter>] [-Password <SecureString>]
[-Pop3AggregationEnabled <$true | $false>] [-PrimarySmtpAddress <SmtpAddress>]
[-ProhibitSendQuota <Unlimited>] [-ProhibitSendReceiveQuota <Unlimited>]
[-QueryBaseDNRestrictionEnabled <$true | $false>] [-RecipientLimits <Unlimited>]
[-RecoverableItemsQuota <Unlimited>] [-RecoverableItemsWarningQuota <Unlimited>]
[-RejectMessagesFrom <RecipientIdParameter[]>] [-RejectMessagesFromDLMembers
<RecipientIdParameter[]>] [-RejectMessagesFromSendersOrMembers
<RecipientIdParameter[]>] [-RemoteAccountPolicy <RemoteAccountPolicyIdParameter>]
[-RemoveManagedFolderAndPolicy <SwitchParameter>] [-RemovePicture
<SwitchParameter>]
 [-RemoveSpokenName <SwitchParameter>] [-RequireSecretQA <$true | $false>]
[-RequireSenderAuthenticationEnabled <$true | $false>] [-ResetPasswordOnNextLogon
<$true | $false>] [-ResourceCapacity <Nullable>] [-ResourceCustom
<MultiValuedProperty>] [-RetainDeletedItemsFor<EnhancedTimeSpan>] [-
RetainDeletedItemsUntilBackup <$true | $false>] [-RetentionComment <String>]
[-RetentionHoldEnabled <$true | $false>] [-RetentionPolicy
<MailboxPolicyIdParameter>] [-RetentionUrl <String>] [-RoleAssignmentPolicy
<MailboxPolicyIdParameter>]
[-RssAggregationEnabled <$true | $false>] [-RulesQuota <ByteQuantifiedSize>]
[-SamAccountName <String>] [-SCLDeleteEnabled <Nullable>] [-SCLDeleteThreshold
<Nullable>] [-SCLJunkEnabled <Nullable>] [-SCLJunkThreshold <Nullable>] [-
SCLQuarantineEnabled <Nullable>] [-SCLQuarantineThreshold <Nullable>]
[-SCLRejectEnabled <Nullable>] [-SCLRejectThreshold <Nullable>]
[-SecondaryAddress <String>] [-SecondaryDialPlan <UMDialPlanIdParameter>]
[-SendModerationNotifications <Never | Internal | Always>] [-SharingPolicy
<SharingPolicyIdParameter>] [-SimpleDisplayName <String>]
[-SingleItemRecoveryEnabled <$true | $false>] [-StartDateForRetentionHold
 <Nullable>] [-ThrottlingPolicy <ThrottlingPolicyIdParameter>] [-Type
<Regular | Room | Equipment | Shared>] [-UMDtmfMap <MultiValuedProperty>]
[-UseDatabaseQuotaDefaults <Nullable>] [-UseDatabaseRetentionDefaults <$true
| $false>] [-UserCertificate <MultiValuedProperty>] [-UserPrincipalName
<String>] [-UserSMimeCertificate <MultiValuedProperty>] [-WhatIf
[<SwitchParameter>]] [-WindowsEmailAddress <SmtpAddress>] [-WindowsLiveID
<SmtpAddress>] [<CommonParameters>]

					  

The Set-Mailbox -? command generates a lot of output to the screen, and it is compressed into a hard-to-read format. Since the Set-Mailbox cmdlet is manipulating the same object as the Get-Mailbox cmdlet, you could also use the following command to view all the properties that have been set on a particular mailbox (Matt.Cook in this example):

Get-Mailbox Matt.Cook | Format-List

RunspaceId                             : ba5c4d2d-ada0-43a5-a3fa-
b19af7d7e3cd
Database                               : DB01
DeletedItemFlags                       : DatabaseDefault
UseDatabaseRetentionDefaults           : True
RetainDeletedItemsUntilBackup          : False
DeliverToMailboxAndForward             : False
LitigationHoldEnabled                  : False
SingleItemRecoveryEnabled              : False
RetentionHoldEnabled                   : False
EndDateForRetentionHold                :
StartDateForRetentionHold              :
RetentionComment                       :
RetentionUrl                           :
ManagedFolderMailboxPolicy             :
RetentionPolicy                        :
CalendarRepairDisabled                 : False
ExchangeGuid                           : ad903a00-0ab3-453d-925d-
5218c5e8ad48
ExchangeSecurityDescriptor             :
System.Security.AccessControl.RawSecurityDescriptor
ExchangeUserAccountControl             : None
MessageTrackingReadStatusEnabled       : True
ExternalOofOptions                     : External
ForwardingAddress                      :
RetainDeletedItemsFor                  : 14.00:00:00
IsMailboxEnabled                       : True
Languages                              : {en-US}
OfflineAddressBook                     :
ProhibitSendQuota                      : unlimited
ProhibitSendReceiveQuota               : unlimited
RecoverableItemsQuota                  : unlimited
RecoverableItemsWarningQuota           : unlimited
DowngradeHighPriorityMessagesEnabled   : False
ProtocolSettings                       : {}
RecipientLimits                        : unlimited
IsResource                             : False
IsLinked                               : False
IsShared                               : False

					  

This example is a partial listing since a full listing would include a few pages of information you can easily look up yourself. Further, note that some of the properties you see as a result of a Get- cmdlet cannot be set since they are system-controlled properties or they are manipulated using other cmdlets, such as ExchangeGuid or Database.

The third way to view all of the properties associated with an object is to simply use the Get-Member cmdlet. Here is an example where the Get-Mailbox cmdlet pipes its output to the Get-Member cmdlet and filters only the members that are properties. Again, the output is a partial output listing only.

Get-Mailbox | Get-Member -MemberType Property

   TypeName: Microsoft.Exchange.Data.Directory.Management.Mailbox

Name                            MemberType Definition
----                            ---------- ----------
AcceptMessagesOnlyFrom          Property
Microsoft.Exchange.Data.MultiValuedProperty'1[[Microsoft.Exchange....
AcceptMessagesOnlyFromDLMembers Property
Microsoft.Exchange.Data.MultiValuedProperty'1[[Microsoft.Exchange....
AddressListMembership           Property
Microsoft.Exchange.Data.MultiValuedProperty'1[[Microsoft.Exchange....
Alias                           Property   System.String Alias
{get;set;}
{get;set;}
ArbitrationMailbox              Property   Microsoft.Exchange.Data.Directory
ArbitrationMailbox {g...
ArchiveGuid                     Property   System.Guid ArchiveGuid {get;}
ArchiveName                     Property
Microsoft.Exchange.Data.MultiValuedProperty'1[[System.String, msco...
ArchiveQuota                    Property
Microsoft.Exchange.Data.Unlimited'1[[Microsoft.Exchange.Data.ByteQ...
ArchiveWarningQuota             Property
Microsoft.Exchange.Data.Unlimited'1[[Microsoft.Exchange.Data.ByteQ...
BypassModerationFromSendersOrMembersProperty
Microsoft.Exchange.Data.MultiValuedProperty'1[[Microsoft.Exchange....
CalendarRepairDisabled          Property   System.Boolean
CalendarRepairDisabled {get;set;}
CalendarVersionStoreDisabled    Property   System.Boolean
CalendarVersionStoreDisabled {get;set;}
CustomAttribute1                Property   System.String CustomAttribute1
{get;set;}
CustomAttribute10               Property   System.String CustomAttribute10
{get;set;}
CustomAttribute11               Property   System.String CustomAttribute11
{get;set;}
CustomAttribute12               Property   System.String CustomAttribute12
{get;set;}
CustomAttribute13               Property   System.String CustomAttribute13
{get;set;}
CustomAttribute14               Property   System.String CustomAttribute14
{get;set;}