ConvertFrom-PDF PowerShell Cmdlet

§ July 8, 2009 06:14 by beefarino |

I hate PDFs. 

And now I need to search through several hundred of them, ranging from 30 to 300 pages in length, for cross-references and personnel names which ... um ... well, let's just say they no longer apply.  Sure reader has the search feature built-in, so does explorer, but that's so 1980's.  And I sure don't want to do each one manually...

I poked around the 'net for a few minutes to find a way to read PDFs in powershell, but no donut.  So I rolled my own cmdlet around the iTextSharp library and Zollor's PDF to Text converter project.

There isn't much to the cmdlet code, given that all of the hard work of extracting the PDF text is done in the PDFParser class of the converter project:

using System;
using System.IO;
using System.Management.Automation;
namespace PowerShell.PDF
{
    [Cmdlet( VerbsData.ConvertFrom, "PDF" )]
    public class ConvertFromPDF : Cmdlet
    {
        [Parameter( ValueFromPipeline = true, Mandatory = true )]
        public string PDFFile { get; set; }
        
        protected override void ProcessRecord()
        {
            var parser = new PDFParser();
            using( Stream s = new MemoryStream() )
            {
                if( ! parser.ExtractText(File.OpenRead(PDFFile), s) )
                {
                    WriteError( 
                        new ErrorRecord(
                            new ApplicationException(),
                            "failed to extract text from pdf",
                            ErrorCategory.ReadError,
                            PDFFile
                        )    
                    );
                    return;
                }
                s.Position = 0;
                using( StreamReader reader = new StreamReader( s ) )
                {
                    WriteObject( reader.ReadToEnd() );
                }
            }
        }
    }
}

The code accepts a file path as input; it runs the conversion on the PDF data and writes the text content of the file to the pipeline.  Not pretty, but done.

Usage

Here is the simple case of transforming a single file:

> convertfrom-pdf -pdf my.pdf

or

> my.pdf | convertfrom-pdf 

More complex processing can be accomplished using PowerShell's built-in features; e.g., to convert an entire directory of PDFs to text files:

> dir *.pdf | %{ $_ | convertfrom-pdf | out-file "$_.txt" } 

More relevant to my current situation would be something along these lines:

> dir *.pdf | ?{ ( $_ | convertfrom-pdf ) -match "ex-employee name" } 

Download the source: PowerShell.PDF.zip (1.10 mb) 

Enjoy!




Creating a PowerShell Provider pt 3: Getting Items

§ July 7, 2009 04:51 by beefarino |

Now that the drive object of the ASP.NET Membership PowerShell provider is fully functional, it's time to extend the PowerShell provider to fetch users from the membership store.

The PowerShell cmdlet used to retrieve one or more items from a provider is get-item, or gi for you alias monkeys out there.  get-item works against any provider that support item retrieval; e.g., it works for files and folders:

> get-item c:\temp
    Directory: Microsoft.PowerShell.Core\FileSystem::C:\
Mode           LastWriteTime       Length Name
----           -------------       ------ ----
d----     3/12/2009  2:23 PM        <DIR> temp

It works for environment variables:

> get-item env:PROGRAMFILES
Name                           Value
----                           -----
ProgramFiles                   C:\Program Files

It works for certificates:

> get-item cert:/CurrentUser/My/E0ADE6F1340FDF59B63452D067B91FFFA09A621F
    Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My
Thumbprint                                Subject
----------                                -------
E0ADE6F1340FDF59B63452D067B91FFFA09A621F  E=jimbo@null.com, CN=127.0.0.1, OU=sec, O=ptek, L=here, S=nc, C=US

So, how does PowerShell know which provider to invoke when it processes a get-item cmdlet?  

PowerShell Paths

The item's full path contains all of information necessary to locate the appropriate provider.  In the examples above, the drive portion of the path indicates which provider should be used to process the item request; you can see the mapping of drives to providers using the get-psdrive cmdlet:

> get-psdrive
Name       Provider      Root
----       --------      ----       
Alias      Alias
C          FileSystem    C:\   
cert       Certificate   \
Env        Environment
Function   Function
Gac        AssemblyCache Gac
HKCU       Registry      HKEY_CURRENT_USER
HKLM       Registry      HKEY_LOCAL_MACHINE
Variable   Variable

Each PowerShell drive is directly associated with a provider type: the C: drive maps to the FileSystem provider, the cert: drive to the Certificate provider, and the env: drive to the Environment provider.

PowerShell recognizes several forms of path syntax, all of them designed to allow for provider discovery; providers are expected to support these path formats as appropriate:

  • Drive-qualified: this is equivalent to a fully-qualified file path.  The drive is explicitly specified at the start of the path, as in "c:/temp/junk.txt" or "cert:/localmachine".  
  • Provider-direct: starts with "\\" (or "//"); the provider for the current location (i.e., the value of $pwd) is assumed to be the provider of the path. This syntax is often used to identify resources on other machines, such as UNC paths or remote registry hives.
  • Provider-qualified: the provider name is prepended to the drive-qualified or provider-direct item path, delimited by '::'.  E.g., "FileSystem::c:/temp/junk.txt", or "FileSystem::\\share\temp\junk.txt".  This format is used when the appropriate provider must be explicity stated.
  • Provider-internal: this is the portion of the provider-qualified path following the '::' delimiter. 

Of the four supported path formats, the ASP.NET Membership PowerShell provider will support these three:

  • Drive-qualified: users:/username
  • Provider-qualified: ASPNETMembership::users:/username
  • Provider-internal: this is idential to the drive-qualified path syntax

Provider-direct paths and UNC-style provider-internal paths will not be supported by the ASP.NET Membership PowerShell provider.

Knowing the path formats to expect, it's time to implement support for the get-item cmdlet.

Enabling Get-Item

Enabling item cmdlet support for the ASP.NET Membership PowerShell provider begins with deriving the provider from ContainerCmdletProvider:

using System.Management.Automation;
using System.Management.Automation.Provider;
namespace ASPNETMembership
{
    [CmdletProvider( "ASPNETMembership", ProviderCapabilities.None )]
    public class Provider : ContainerCmdletProvider
    {
        // ...
    }
}

Deriving from ContainerCmdletProvider adds many item-related methods to the provider.  To enabling the get-item cmdlet, at least two of these methods must be overridden. 

GetItem

The first required override is the GetItem method, which is called to process a get-item invocation at runtime:

protected override void GetItem( string path )
{
    var user = GetUserFromPath(path);
    if( null != user )
    {
        WriteItemObject( user, path, false );
    }
}

The GetItem override delegates almost all of the work to the GetUserFromPath utility method; if GetUserFromPath returns a valid object reference, it is written back to the current pipeline using the WriteItemObject method of the provider object's base (line 6).

GetUserFromPath uses the provider's custom drive object to access the ASP.NET Membership provider.  The drive object for the path is available in the PSDriveInfo property; PowerShell conveniently sets this value to the appropriate DriveInfo object for the item's path before calling GetItem:

MembershipUser GetUserFromPath( string path )
{
    var drive = this.PSDriveInfo as MembershipDriveInfo;
    var username = ExtractUserNameFromPath( path );
    return drive.MembershipProvider.GetUser( username, false );
}
static string ExtractUserNameFromPath( string path )
{
    if( String.IsNullOrEmpty( path ) )
    {
        return path;
    }
    // this regex matches all supported powershell path syntaxes:
    //  drive-qualified - users:/username
    //  provider-qualified - membership::users:/username
    //  provider-internal - users:/username
    var match = Regex.Match( path, @"(?:membership::)?(?:\w+:[\\/])?(?<username>[-a-z0-9_]*)$", RegexOptions.IgnoreCase );
    if( match.Success )
    {
        return match.Groups[ "username" ].Value;
    }
    return String.Empty;
}

The custom drive object exposes the ASP.NET Membership Provider, which offers a GetUser method that returns the MembershipUser object for a valid username (line 5).  The username is extracted from the path string using a simple regular expression that matches the three path formats supported by the PowerShell provider (line 17).

ItemExists

The second required override is the ItemExists method, which is called by PowerShell to determine if the provider contains an item at a specified path (e.g., by the test-path cmdlet).

PowerShell calls ItemExists before the GetItem method when processing get-item; if ItemExists returns false, GetItem is not called and a "cannot find path" error is reported on the pipeline.  The ASP.NET Membership provider reuses the GetUserFromPath utility method to ascertain whether the path contains a valid username:

protected override bool ItemExists( string path )
{
    return null != GetUserFromPath( path );
} 

With these two overrides and their supporting utility methods, our provider can support the get-item cmdlet.

Testing Get-Item

Build and run; in the PowerShell console, create the users drive as follows:

> new-psdrive -psp aspnetmembership -root "" -name users -server localhost -catalog awesomewebsitedb; 
Name       Provider      Root                                   CurrentLocation
----       --------      ----                                   ---------------
users      ASPNETMemb... 

Once the drive is created, you can use get-item to fetch MembershipUser objects from the ASP.NET Membership user store:

> get-item users:/testuser
PSPath                  : ASPNETMembership::testuser
PSDrive                 : users
PSProvider              : ASPNETMembership
PSIsContainer           : False
UserName                : testuser
ProviderUserKey         : 09a9c356-a400-4cff-825d-231207946c94
Email                   : user@hotmail.com
PasswordQuestion        : what is your favorite color?
Comment                 :
IsApproved              : True
IsLockedOut             : False
LastLockoutDate         : 12/31/1753 7:00:00 PM
CreationDate            : 6/11/2009 12:59:45 PM
LastLoginDate           : 6/11/2009 12:59:45 PM
LastActivityDate        : 6/11/2009 12:59:45 PM
LastPasswordChangedDate : 6/11/2009 12:59:45 PM
IsOnline                : False
ProviderName            : AspNetSqlMembershipProvider

At this point, a whole new world of complexity is available from our provider:

> ( get-item users:/testuser ).ResetPassword( 'asdf1234' )
^PlpmNMON@7A]w

We can also leverage some of the built-in goodies of PowerShell against our ASP.NET Membership store in a natural way:

$u = get-item users:/testuser;
if( $u.IsLockedOut ) 
{ 
    $u.UnlockUser(); 
}  

Pretty cool.

Coming Up

Discovery is a big part of PowerShell, and in the post I'll extend the ASP.Net Membership PowerShell provider to support the get-childitem (alias dir or ls) cmdlet, to enable listing of all users in the store.  I'll also add support for the set-location (alias cd) cmdlet, which will allow operators to set the shell's current location to our custom users drive.

The code for this post is available here: ASPNETMembership_GetItem.zip (5.55 kb)

As always, thanks for reading, and if you liked this post, please Kick It, Shout It, trackback, tweet it, and comment using the clicky thingies below!



Creating a PowerShell Provider pt 2: Parameters and Default Drives

§ June 11, 2009 16:26 by beefarino |

My previous post in this series discussed the first major step in developing a PowerShell provider: creating a custom drive object.  This post rounds out the discussion by making the drive configurable with custom initialization parameters.  In addition, I'll demonstrate how a provider can create one or more "default" drives without user intervention.

This post builds on code from the previous post, which you can download from here.  The completed code for this post is also available.

Parameterizing the Drive

At the moment, the ASP.NET Membership provider configuration lives in code; that should really change so this drive can be used with other providers or for multiple sites.  Such drive configurability is gained by supporting the NewDriveDynamicParameters method of the PowerShell provider.

The NewDriveDynamicParameters method is called each time the new-psdrive cmdlet is invoked to allow the provider to add drive creation parameters.  Although the MSDN documentation of this method isn't terribly helpful, implementing it is pretty simple.  All you need to do is return an object containing properties or fields for each custom parameter.  

First, we need to know what parameters are needed to create the ASP.NET Membership provider.  Take a quick look at the configuration items hard-coded in the drive creation logic:

// DriveInfo.cs
public MembershipDriveInfo( PSDriveInfo driveInfo )
    : base( driveInfo )
{
    var connectionStrings = ConfigurationManager.ConnectionStrings;
 
    var fi = typeof( ConfigurationElementCollection )
        .GetField( "bReadOnly", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic );
    fi.SetValue( connectionStrings, false );
 
    connectionStrings.Add(
        new ConnectionStringSettings(
            "ProviderConnectionString",
            "data source=localhost;Integrated Security=SSPI;Initial Catalog=AwesomeWebsiteDB"
        )
    );
 
    provider = new SqlMembershipProvider();
    var nvc = new System.Collections.Specialized.NameValueCollection
    {
        { "connectionStringName", "ProviderConnectionString" },
        { "enablePasswordRetrieval", "false" },
        { "enablePasswordReset", "true" },
        { "requiresQuestionAndAnswer", "false" },
        { "requiresUniqueEmail", "false" },
        { "passwordFormat", "Hashed" },
        { "maxInvalidPasswordAttempts", "5" },
        { "minRequiredPasswordLength", "6" },
        { "minRequiredNonalphanumericCharacters", "0" },
        { "passwordAttemptWindow", "10" },
        { "passwordStrengthRegularExpression", "" },
        { "applicationName", "/" },
    };
    provider.Initialize( "AspNetSqlMembershipProvider", nvc );
}

There are a number of parameters used to initialize the ASP.NET membership provider.  Based on the code, I would want to configure any of the following facets of the ASP.NET Membership provider:

  • the Connection String server and databse name;
  • EnablePasswordRetrieval;
  • EnablePasswordReset;
  • RequiresQuestionAndAnswer;
  • RequiresUniqueEmail;
  • PasswordFormat;
  • MaxInvalidPassordAttempts;
  • MinRequiredPasswordLength;
  • MinRequiredNonalphanumericCharacters;
  • PasswordAttemptWindow;
  • PasswordStrengthRegularExpression;
  • ApplicationName.

While all of these should be configurable, assumptions can be made for most of them. 

The first step towards implementing the NewDriveDynamicParameters method is to define an object containing read/write properties for each configurable parameter:

// DriveParameters.cs
using System;
using System.Management.Automation;
using System.Web.Security;
namespace ASPNETMembership
{
    public class DriveParameters
    {
        public DriveParameters()
        {
            EnablePasswordReset = true;
            EnablePasswordRetrieval = false;
            RequiresQuestionAndAnswer = false;
            RequiresUniqueEmail = false;
            MaxInvalidPasswordAttempts = 5;
            MinRequiredNonalphanumericCharacters = 0;
            MinRequiredPasswordLength = 6;
            PasswordAttemptWindow = 10;
            PasswordStrengthRegularExpression = String.Empty;
            ApplicationName = "/";
            PasswordFormat = MembershipPasswordFormat.Hashed;
        }
 
        [Parameter( Mandatory=true )]       
        public string Server { get; set; }        
 
        [Parameter( Mandatory = true )]
        public string Catalog { get; set; }
 
        public bool EnablePasswordRetrieval { get; set; }
        public bool EnablePasswordReset { get; set; }
        public bool RequiresQuestionAndAnswer { get; set; }
        public bool RequiresUniqueEmail { get; set; }
        public MembershipPasswordFormat PasswordFormat { get; set; }
        public int MaxInvalidPasswordAttempts { get; set; }
        public int MinRequiredPasswordLength { get; set; }
        public int MinRequiredNonalphanumericCharacters { get; set; }
        public int PasswordAttemptWindow { get; set; }
        public string PasswordStrengthRegularExpression { get; set; }
        public string ApplicationName { get; set; }
    }
}

Note the use of the System.Management.Automation.ParameterAttribute on lines 24 and 27 to identify the Server and Catalog parameters as required (Mandatory=true).  The remaining optional parameters are initialized to default values in the constructor.

With the DriveParameters type defined, the NewDriveDyanmicParameters method of the ASP.NET Membership provider can now be implemented:

// Provider.cs
protected override object NewDriveDynamicParameters()
{
    return new DriveParameters();
}

PowerShell will call this method each time the new-psdrive cmdlet is invoked for this provider.  The object returned to PowerShell is filled with parameter values and passed back to the provider's NewDrive method via the DynamicParameters property; in the Membership PowerShell provider, NewDrive simply passes the parameters to the MembershipDriveInfo constructor:

// Provider.cs
protected override System.Management.Automation.PSDriveInfo NewDrive( PSDriveInfo drive )
{
    var driveParams = this.DynamicParameters as DriveParameters;
    return new MembershipDriveInfo(drive, driveParams);
}

which must then act on the parameters when initializing the ASP.NET Membership provider:

// DriveInfo.cs
using System;
using System.Configuration;
using System.Management.Automation;
using System.Web.Security;
namespace ASPNETMembership
{
    public class MembershipDriveInfo : PSDriveInfo
    {
        MembershipProvider provider;
        public MembershipDriveInfo( PSDriveInfo driveInfo, DriveParameters parameters )
            : base( driveInfo )
        {
            var connectionStrings = ConfigurationManager.ConnectionStrings;
 
            var fi = typeof( ConfigurationElementCollection )
                .GetField( "bReadOnly", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic );
            fi.SetValue( connectionStrings, false );
 
            var connectionString = String.Format(
                "data source={0};Integrated Security=SSPI;Initial Catalog={1}",
                parameters.Server,
                parameters.Catalog
                );
 
            var moniker = Guid.NewGuid().ToString("N");
            var connectionStringName = "cxn_" + moniker;
            var providerName = "pvdr_" + moniker;
 
            connectionStrings.Add(
                new ConnectionStringSettings(
                    connectionStringName,
                    connectionString
                )
            );
 
            provider = new SqlMembershipProvider();
            var nvc = new System.Collections.Specialized.NameValueCollection
            {
                { "connectionStringName", connectionStringName },
                { "enablePasswordRetrieval", parameters.EnablePasswordRetrieval.ToString() },
                { "enablePasswordReset", parameters.EnablePasswordReset.ToString() },
                { "requiresQuestionAndAnswer", parameters.RequiresQuestionAndAnswer.ToString() },
                { "requiresUniqueEmail", parameters.RequiresUniqueEmail.ToString() },
                { "passwordFormat", parameters.PasswordFormat.ToString() },
                { "maxInvalidPasswordAttempts", parameters.MaxInvalidPasswordAttempts.ToString() },
                { "minRequiredPasswordLength", parameters.MinRequiredPasswordLength.ToString() },
                { "minRequiredNonalphanumericCharacters", parameters.MinRequiredNonalphanumericCharacters.ToString() },
                { "passwordAttemptWindow", parameters.PasswordAttemptWindow.ToString() },
                { "passwordStrengthRegularExpression", parameters.PasswordStrengthRegularExpression },
                { "applicationName", parameters.ApplicationName },
            };
            provider.Initialize( providerName, nvc );
        }
        
        public MembershipProvider MembershipProvider
        {
            get
            {
                return this.provider;
            }
        }
    }
}

Not a lot of new code here; the constructor now accepts an additional DriveParameters argument that is used to initialize the connection string and membership provider configuration.  Using dynamically-generated connection string and provider names prevents naming collisions if more than one drive is initialized by the provider (lines 26-28).

Using the Drive Parameters

Build and run. The new dynamic drive parameters can be specified directly to the new-psdrive cmdlet just like any other cmdlet parameter:

> new-psdrive -psprovider aspnetmembership -name users -root '' 
    -server localhost -catalog AwesomeWebsiteDB 
    -MinRequiredPasswordLength 8 -PasswordAttemptWindow 4 
 
Name       Provider      Root                                   CurrentLocation
----       --------      ----                                   ---------------
users      ASPNETMemb...

Note that PowerShell prompts the user for the any required parameters if they aren't supplied:

> remove-psdrive users
> new-psdrive -psprovider aspnetmembership -name users -root ''
cmdlet New-PSDrive at command pipeline position 1
Supply values for the following parameters:
Catalog: 
> AwesomeWebsiteDB
Server:
> localhost
 
Name       Provider      Root                                   CurrentLocation
----       --------      ----                                   ---------------
users      ASPNETMemb...

Creating Default Drives

Another feature available to PowerShell providers is the ability to initialize a set of default drives when the provider assembly is first loaded.  This is accomplished by overriding the provider's InitializeDefaultDrives method to return a list of PSDriveInfo objects describing the drives to create:

// Provider.cs
 
protected override Collection<PSDriveInfo> InitializeDefaultDrives()
{
    var driveInfo = new PSDriveInfo(
        "users",
        this.ProviderInfo,
        "",
        "Default ASP.NET Membership Drive",
        null
        );
    
    var parameters = new DriveParameters
                     {
                         Catalog = "AwesomeWebsiteDB",
                         Server = "localhost"
                     };
 
    return new Collection<PSDriveInfo>
           {
               new MembershipDriveInfo(
                   driveInfo,
                   parameters
                   )
           };
}

Each PSDriveInfo object in the returned collection will then be passed to the NewDrive method of the provider to complete the drive creation (the NewDriveDynamicParameters method is not called in this case).  As such, the ASP.NET Membership PowerShell provider's NewDrive method must be modified to acommodate pre-initialized drives:

protected override PSDriveInfo NewDrive( PSDriveInfo drive )
{
    // see if the drive has already been initialized
    //    e.g., via InitializeDefaultDrives()
    if( drive is MembershipDriveInfo )
    {
        return drive;
    }
 
    var driveParams = this.DynamicParameters as DriveParameters;
    return new MembershipDriveInfo(drive, driveParams);
}

Testing Default Drive Creation

Build and run; you can verify that the default drive was created using the get-psdrive cmdlet:

> get-psdrive
 
Name       Provider      Root                                   CurrentLocation
----       --------      ----                                   ---------------
...
users      ASPNETMemb...

No need to use the new-psdrive cmdlet - the users drive is created automagically as PowerShell loads the provider assembly.

Coming Up

That's about it for drives; for here on in, the focus will be on making the provider work with all the features available in PowerShell.  The next post will add support for the get-item cmdlet and discuss the various flavors of item paths the provider must support.

The code for this post is available here:

ASPNETMembership_pt1_drives.zip (4.26 kb) 

As always, thanks for reading, and if you liked this post, please Kick It, Shout It, trackback, tweet it, and comment using the clicky thingies below!




Creating a PowerShell Provider pt 1: Creating the Drive

§ June 9, 2009 14:06 by beefarino |

The first step to creating a full-featured PowerShell provider is to be able to create a new drive.  The goal of this post is to enable the most basic functional drive that provides access to the ASP.NET Membership user store.  Before you begin, make sure you have the project set up properly as I describe here, or you can download the project pre-coded (3.24 kb).

We'll start by creating a minimal provider implementation.  Add a class to the project named Provider and fill it in like so:

// Provider.cs
using System.Management.Automation;
using System.Management.Automation.Provider;
namespace ASPNETMembership
{
    [CmdletProvider( "ASPNETMembership", ProviderCapabilities.None )]
    public class Provider : DriveCmdletProvider
    {
        protected override PSDriveInfo NewDrive( PSDriveInfo drive )
        {
            return base.NewDrive( drive );
        }
        protected override object NewDriveDynamicParameters()
        {
            return base.NewDriveDynamicParameters();
        }
    }
}  

A few items of note:

  • the Provider class derives from System.Automation.Provider.DriveCmdletProvider. All PowerShell providers derive from one of the abstract *CmdletProvider base classes. I'll discuss these classes a bit in the next post, but for now know that DriveCmdletProvider is the most basic base class you can use to create a provider.
  • the class is decorated with a System.Management.Automation.Provider.CmdletProviderAttribute.  This attribute is required to get PowerShell to recognize your class as a provider when the assembly is loaded.  In addition, the attribute identifies some of the capabilities the provider supports; more on this in a later post.

The class overrides two methods related to drive creation - at the moment they are simply placeholders and defer to the DriveCmdletProvider implementations.  When PowerShell is presented with a new-psdrive cmdlet specifying the ASPNETMembership provider, it will ferret the call to our provider's NewDrive method to create the drive.

Compile and run; in the PowerShell console that opens, enter the following command (note that my convention is to mark commands you type in with leading >'s):

> new-psdrive -PsProvider ASPNETMembership -Name users -Root "";

This will invoke the NewDrive method of the ASPNETMembership provider and create a new drive named "users" in the PowerShell session.  To verify the drive exists, use the get-psdrive cmdlet.  You should see output similar to the following :

> get-psdrive
Name       Provider      Root                                   CurrentLocation
----       --------      ----                                   ---------------
C          FileSystem    C:\                                 ...ensions\Profile
cert       Certificate   \
Env        Environment
Function   Function
Gac        AssemblyCache Gac
HKCU       Registry      HKEY_CURRENT_USER
HKLM       Registry      HKEY_LOCAL_MACHINE
users      ASPNETMemb...

Custom Drive Objects

Providers are transient: PowerShell will create many instances of this provider in response to different cmdlets.  So it's not possible to persist any state in a provider object.  Instead, state needs to be stored in a custom drive object that is returned from the NewDrive method of the provider.  PowerShell caches this instance and makes it available to the provider via the DriveCmdletProvider.PsDriveInfo property.

The only real requirement for a custom drive object is that it derive from System.Automation.PSDriveInfo.  This class is the most basic implementation of a custom drive object possible; go ahead and add it to the project:

// DriveInfo.cs
using System.Management.Automation;
namespace ASPNETMembership
{
    public class MembershipDriveInfo : PSDriveInfo
    {
        public MembershipDriveInfo( PSDriveInfo driveInfo )
            : base( driveInfo )
        {
        }      
    }
}

Then modify the Provider class to return a new instance of this drive object in the NewDrive method:

// Provider.cs
// ... 
        protected override PSDriveInfo NewDrive( PSDriveInfo drive )
        {
            return new MembershipDriveInfo( drive );
        }
// ...

Build and run; in the console, enter the following commands:

> new-psdrive -psp aspnetmembership -name users -root ""
Name       Provider      Root                                   CurrentLocation
----       --------      ----                                   ---------------
users      ASPNETMemb...
> ( get-psdrive users ).gettype().fullname
ASPNETMembership.MembershipDriveInfo

Note that the type of the users drive is now our custom drive object type - at this point, we have our first soild hook into the powershell provider system.  Now it's time to fold ASP.NET Membership into the custom drive.... but there's a small problem to deal with first.

Configuring ASP.NET Membership Programatically

Configuring ASP.NET Membership in a web application is pretty easy.  You just pop in a little config section into the web.config and everything just works; e.g., this web.config sets up the SqlMembershipProvider for a website:

<configuration>
... 
    <connectionStrings>
        <add name="MembershipProviderServices" 
                 connectionString="data source=localhost;Integrated Security=SSPI;Initial Catalog=AwesomeWebsiteDB"/>
    </connectionStrings>
... 
        <membership>
            <providers>
                <clear/>
                <add name="AspNetSqlMembershipProvider" 
                         type="System.Web.Security.SqlMembershipProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" 
                         connectionStringName="MembershipProviderServices" 
                         enablePasswordRetrieval="false" 
                         enablePasswordReset="true" 
                         requiresQuestionAndAnswer="false" 
                         requiresUniqueEmail="false" 
                         passwordFormat="Hashed" 
                         maxInvalidPasswordAttempts="5" 
                         minRequiredPasswordLength="6" 
                         minRequiredNonalphanumericCharacters="0" 
                         passwordAttemptWindow="10" 
                         passwordStrengthRegularExpression="" 
                         applicationName="/" />
            </providers>
        </membership>
...
</configuration> 

In PowerShell, there is no equivalent to a web.config or app.config we can use to configure the membership provider.  Instead, we have to configure the memberhip provider via code.  Not a big deal; this short snippit of code results in the same membership provider configuration defined by the web.config example:

var provider = new SqlMembershipProvider();
var nvc = new System.Collections.Specialized.NameValueCollection
{
    { "connectionStringName", "MembershipProviderServices" },
    { "enablePasswordRetrieval", "false" },
    { "enablePasswordReset", "true" },
    { "requiresQuestionAndAnswer", "false" },
    { "requiresUniqueEmail", "false" },
    { "passwordFormat", "Hashed" },
    { "maxInvalidPasswordAttempts", "5" },
    { "minRequiredPasswordLength", "6" },
    { "minRequiredNonalphanumericCharacters", "0" },
    { "passwordAttemptWindow", "10" },
    { "passwordStrengthRegularExpression", "" },
    { "applicationName", "/" },
};
provider.Initialize( "AspNetSqlMembershipProvider", nvc );

The only wrinkle is on line 4, where we reference a connection string by its name.  The ConfigurationManager.ConnectionStrings collection is read-only, so how can we add a new connection string to it?  Simple, we cheat and make the collection writeable (many thanks to David Gardiner for posting a similar solution on his blog!):

using System.Configuration;
var connectionStrings = ConfigurationManager.ConnectionStrings;
// find the private bReadOnly field in the connection strings base type
var fi = typeof( ConfigurationElementCollection );
    .GetField( "bReadOnly", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic );
// change the field value to false, making the object writeable
fi.SetValue( connectionStrings, false );
// add a new connection string
connectionStrings.Add(
    new ConnectionStringSettings(
        "MembershipProviderServices",
        "data source=localhost;Integrated Security=SSPI;Initial Catalog=AwesomeWebsiteDB"
        )
    );

Now with the ability to add connection strings to the configuration manager programmatically, we can add ASP.NET Membership services to our custom drive object.

Adding ASP.NET Membership Features to the Drive

Modify the custom drive class with our ASP.NET Membership configuration code as follows:

// DriveInfo.cs
using System.Configuration;
using System.Management.Automation;
using System.Web.Security;
namespace ASPNETMembership
{
    public class MembershipDriveInfo : PSDriveInfo
    {
        MembershipProvider provider;
        public MembershipDriveInfo( PSDriveInfo driveInfo )
            : base( driveInfo )
        {
            var connectionStrings = ConfigurationManager.ConnectionStrings;
            var fi = typeof( ConfigurationElementCollection )
                .GetField( "bReadOnly", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic );
            fi.SetValue( connectionStrings, false );
            connectionStrings.Add(
                new ConnectionStringSettings(
                    "ProviderConnectionString",
                    "data source=localhost;Integrated Security=SSPI;Initial Catalog=AwesomeWebsiteDB"
                )
            );
            provider = new SqlMembershipProvider();
            var nvc = new System.Collections.Specialized.NameValueCollection
            {
                { "connectionStringName", "ProviderConnectionString" },
                { "enablePasswordRetrieval", "false" },
                { "enablePasswordReset", "true" },
                { "requiresQuestionAndAnswer", "false" },
                { "requiresUniqueEmail", "false" },
                { "passwordFormat", "Hashed" },
                { "maxInvalidPasswordAttempts", "5" },
                { "minRequiredPasswordLength", "6" },
                { "minRequiredNonalphanumericCharacters", "0" },
                { "passwordAttemptWindow", "10" },
                { "passwordStrengthRegularExpression", "" },
                { "applicationName", "/" },
            };
            provider.Initialize( "AspNetSqlMembershipProvider", nvc );
        }
        
        public MembershipProvider MembershipProvider
        {
            get
            {
                return this.provider;
            }
        }
    }
}

Note that the custom drive holds a reference to the ASP.NET Membership provider that is initialized in the constructor - since PowerShell caches the drive object, it's safe to save the provider reference.  The drive also exposes the membership provider through the public MembershipProvider property.

Build and run.  Now the fun begins - first, let's create get a reference to our drive:

> $d = new-psdrive -P
sProvider ASPNETMembership -Name users -Root ""
> $d.MembershipProvider | get-member
   TypeName: System.Web.Security.SqlMembershipProvider
Name                                 MemberType Definition
----                                 ---------- ----------
ValidatingPassword                   Event      System.Web.Security.Membersh...
ChangePassword                       Method     System.Boolean ChangePasswor...
ChangePasswordQuestionAndAnswer      Method     System.Boolean ChangePasswor...
CreateUser                           Method     System.Web.Security.Membersh...
DeleteUser                           Method     System.Boolean DeleteUser(St...
Equals                               Method     System.Boolean Equals(Object...
FindUsersByEmail                     Method     System.Web.Security.Membersh...
FindUsersByName                      Method     System.Web.Security.Membersh...
GeneratePassword                     Method     System.String GeneratePasswo...
GetAllUsers                          Method     System.Web.Security.Membersh...
GetHashCode                          Method     System.Int32 GetHashCode()
GetNumberOfUsersOnline               Method     System.Int32 GetNumberOfUser...
GetPassword                          Method     System.String GetPassword(St...
GetType                              Method     System.Type GetType()
GetUser                              Method     System.Web.Security.Membersh...
GetUserNameByEmail                   Method     System.String GetUserNameByE...
Initialize                           Method     System.Void Initialize(Strin...
ResetPassword                        Method     System.String ResetPassword(...
ToString                             Method     System.String ToString()
UnlockUser                           Method     System.Boolean UnlockUser(St...
UpdateUser                           Method     System.Void UpdateUser(Membe...
ValidateUser                         Method     System.Boolean ValidateUser(...
ApplicationName                      Property   System.String ApplicationNam...
Description                          Property   System.String Description {g...
EnablePasswordReset                  Property   System.Boolean EnablePasswor...
EnablePasswordRetrieval              Property   System.Boolean EnablePasswor...
MaxInvalidPasswordAttempts           Property   System.Int32 MaxInvalidPassw...
MinRequiredNonAlphanumericCharacters Property   System.Int32 MinRequiredNonA...
MinRequiredPasswordLength            Property   System.Int32 MinRequiredPass...
Name                                 Property   System.String Name {get;}
PasswordAttemptWindow                Property   System.Int32 PasswordAttempt...
PasswordFormat                       Property   System.Web.Security.Membersh...
PasswordStrengthRegularExpression    Property   System.String PasswordStreng...
RequiresQuestionAndAnswer            Property   System.Boolean RequiresQuest...
RequiresUniqueEmail                  Property   System.Boolean RequiresUniqu...

As you can see, the membership provider is fully accessible from PowerShell via the drive object.  We can create users:

> $status = 0;
> $d.MembershipProvider.CreateUser( "myuser", "mypassword1234", "myuser@hotmail.com", "what is your favorite color?", "plaid", $true, [Guid]::NewGuid(), ([ref]$status))
UserName                : myuser
ProviderUserKey         : b6ebc2a4-2ff8-4cf8-928e-969416edd704
Email                   : myuser@hotmail.com
PasswordQuestion        : what is your favorite color?
Comment                 :
IsApproved              : True
IsLockedOut             : False
LastLockoutDate         : 1/1/1754 12:00:00 AM
CreationDate            : 6/11/2009 1:13:50 PM
LastLoginDate           : 6/11/2009 1:13:50 PM
LastActivityDate        : 6/11/2009 1:13:50 PM
LastPasswordChangedDate : 6/11/2009 1:13:50 PM
IsOnline                : True
ProviderName            : AspNetSqlMembershipProvider

We can get existing users:

> $d.MembershipProvider.GetUser( "myuser", $false )
UserName                : myuser
ProviderUserKey         : b6ebc2a4-2ff8-4cf8-928e-969416edd704
Email                   : myuser@hotmail.com
PasswordQuestion        : what is your favorite color?
Comment                 :
IsApproved              : True
IsLockedOut             : False
LastLockoutDate         : 12/31/1753 7:00:00 PM
CreationDate            : 6/11/2009 1:13:50 PM
LastLoginDate           : 6/11/2009 1:13:50 PM
LastActivityDate        : 6/11/2009 1:13:50 PM
LastPasswordChangedDate : 6/11/2009 1:13:50 PM
IsOnline                : True
ProviderName            : AspNetSqlMembershipProvider 

We can even remove users:

> $d.MembershipProvider.DeleteUser( "myuser", $true )
True
> $d.MembershipProvider.GetUser( "myuser",$false ) 
#note that no output is returned this time 

Using the drive directly to manage users may work, but it is a bit clumsy.  You may be asking yourself why we implemented the drive at all, given that PowerShell could create the MembershipProvider object directly.  The drive is the basis on which all PowerShell provider functionality will be based; many standard cmdlets leverage the data stored in a drive object.  So things may look cumbersome at the moment, but soon we'll be working with cmdlets, pipes, and sets of user objects - all thanks to our custom drive object.

Coming Up

At the moment, the ASP.NET Membership provider configuration lives code; that should really change so this drive can be used with other providers or for multiple sites.  The NewDriveDynamicParameters method of the PowerShell provider object allows the provider to request additional drive creation parameters from the new-psdrive cmdlet.  My next post will describe how to properly implement this method.

In upcoming posts, I'll show you how to implement support for different core cmdlets, such as get-item, remove-item, new-item, and get-childitem (or 'dir' for you alias users).  In addition, I'll dig deep into the various path syntaxes that PowerShell expects your provider to support. 

The code for this post is available here:

ASPNETMembership_pt1.zip (3.24 kb)

As always, thanks for reading, and if you liked this post, please Kick It, Shout It, trackback, or comment.