Advanced Usage Information

This section of the documentation describes how to leverage the operations supported by the Membership PowerShell Provider. All samples in this area assume you have imported the Membership PowerShell Provider and created a Membership drive named "users". For instructions on this, see Basic Usage.

This provider is capable of performing the following activities against your Membership user store:

Creating New Users

New users can be added to the Membership store using the standard new-item cmdlet. The username is specified in the path argument. To accommodate the minimum needs of the Membership framework, two extra arguments are required in the call to new-item:
  • email: this is the email address of the user
  • password: this is the plaintext password for the new user account.
This example creates a new user with the following properties:
  • UserName: myNewUserName;
  • Email: myNewUser@null.com
  • Password: myNewUserPassword123
PS> new-item users:/myNewUserName -email 'myNewUser@null.com' -password 'myNewUserPassword123'

Retrieving Users

The Membership PowerShell Provider supports several methods of retrieving users from the membership store.

Retrieving a Single User

A single user can be fetched from the membership store using the get-item cmdlet:
PS> get-item users:/beefarino

If you specify a username that does not already exist, an error is written to the pipeline.

Retrieving Multiple Users

A collection of all users can be fetched using the get-childitem cmdlet:
PS> get-childitem users:/

Note that specifying any path except the root of the Membership drive will result in an empty collection; however, no error will be written to the pipeline.

Filtering Users

There are two ways to filter the list of users returned from the get-childitem cmdlet. The first uses PowerShell's built-in filtering capabilities and can filter on any Membership User property or custom criteria. The second can only filter on the UserName property of the Membership User object; however, it runs in the native provider and can yield a large performance benefit.

Filtering using PowerShell

You can filter the list of users returned from get-childitem using PowerShell's where-object cmdlet. The benefit to this approach is that you are able to provide a custom filter expression, filtering the users on any criteria possible. The drawback is that the filter is executed locally, so every user in the Membership store is retrieved. If your Membership store is very large, this may be prohibitive.
The example below filters the list of users to those who have logged in in the past 24 hours:
PS> get-childitem users:/ | where-object { $_.LastLoginDate -gt [DateTime]::Now.AddDays( -1 ) }

Native Filtering

You can also rely on the Membership store to filter the list of users for you. The benefit to this approach is that the number of users returned to your PowerShell session is minimized. The drawback is that you can only filter on the user's username property.
To execute a native filter, specify the -Filter parameter in your call to get-childitem. The format of the Filter string is identical to that used by the Membership::FindUsersByName method.
This example uses a native filter to isolate those users whose username contains the text "beef":
PS> get-childitem users:/ -filter '%beef%'

Updating Users

You can edit properties and call methods on the MembershipUser objects in your PowerShell session directly. Note that the MembershipUser objects are not "live" and you must use the set-item cmdlet to propagate your changes back to the membership store.
PS> $user = get-item users:/beefarino
PS> $user.IsApproved = $true;
PS> $user | set-item;

For a list of all available MembershipUser operations and parameters, please see http://msdn.microsoft.com/en-us/library/system.web.security.membershipuser_members.aspx or run the following PowerShell command:
PS> get-childitem users:/ | get-member

Removing Users

Removing one or more users from the Membership store is accomplished using the remove-item cmdlet:
PS> remove-item users:/beefarino

Note that nothing is written to the pipeline as a result of a successful operation. If the specified item does not exist, and error is written to the pipeline, but the pipeline is not terminated.

Verifying Remove Operations

The Membership PowerShell Provider supports the use of the -Confirm common parameter when using the remove-item cmdlet. This will prompt the user for each remove operation, as show here:
PS> get-childitem users:/ | where-object { !$_.IsApproved } | remove-item -confirm

Confirm
Are you sure you want to perform this action?
Performing operation "Remove-Item" on Target "1883146ff6d1".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"):

Removing Users using a Native Filter

When using the remove-item cmdlet against the Membership PowerShell Provider, you can use the native username filtering feature to isolate the list of users you wish to remove. To use the native filter, specify the root of the Membership drive as the item path parameter, and specify a filter in the -Filter parameter:
PS> remove-item users:/ -filter '%beef%'

In the example above, all users with a username containing the string 'beef' will be removed.
Note that you may receive confirmation prompts when using the native filter unless you specify the -Recurse parameter to remove-item.

Last edited Aug 9, 2010 at 11:14 AM by beefarino, version 3

Comments

No comments yet.