Write your own PowerShell provider using only script, no C# required. Module definition is provided by a Windows PowerShell 2.0 Module, which may be pure script, binary or a mix of both.

Debugging is as easy as any ordinary ps1 script file:

All functions in backing module reflect the same signature as those found on MSDN. This means that you go to MSDN documentation on providers to learn about how to write the corresponding script.

Current Release PSProvider 0.4

Samples and Templates

• See Documentation

Roadmap

0.1

• ContainerCmdletProvider support through "ModuleBoundProvider" provider
• Demo provider included navigating a Hashtable
• Can be debugged in the debugger of your choice: console, ISE, PowerGUI.

0.2

• NavigationCmdletProvider support
• Providers rename to ContainerScriptProvider and TreeScriptProvider
• Container Sample & Tree Template modules
• Supports: Clear-Item, Copy-Item, Get-Item, Invoke-Item, Move-Item, New-Item, Remove-Item, Rename-Item, Set-Item

0.3

• IContentCmdletProvider support
• New Commands: New-ContentReader, New-ContentWriter implement IContentReader, IContentWriter
• Adds support for: Add-Content, Clear-Content, Get-Content, Set-Content

0.4 (Current Release)

• IPropertyCmdletProvider support
• Adds support for: Clear-ItemProperty, Copy-ItemProperty, Get-ItemProperty, Move-ItemProperty, New-ItemProperty, Remove-ItemProperty, Rename-ItemProperty, Set-ItemProperty

0.5

• Dynamic Parameter support

0.6

• Security Interfaces
• Adds support for: Get-ACL, Set-ACL

http://psprovider.codeplex.com/

If you want to do this, you won’t really need much of an explanation as to why I’m posting this. As to the rest of you, never mind; stick with your BigEndian Unicode (hint: powershell console and other console applications prefer ASCII) :)

First up, create yourself a Windows ISE Profile script that will be loaded by default when ISE starts (and/or when you open a new “Tab”)

# run this one-liner from within ISE through the interactive window (command pane):
if (-not (test-path $profile)) { md -force (split-path $profile); "" > $profile; psedit $profile }

Now, put this one-liner (well, it could fit on one line) in your $profile:

# watch for changes to the Files collection of the current Tab
register-objectevent $psise.CurrentPowerShellTab.Files collectionchanged -action {
    # iterate ISEFile objects
    $event.sender | % {
         # set private field which holds default encoding to ASCII
         $_.gettype().getfield("encoding","nonpublic,instance").setvalue($_, [text.encoding]::ascii)
    }
}

Have fun!

These days I'm incredibly busy both in my professional and private life, so I’ve not had a lot of time to construct the usual meaty posts I like to write. Instead I figured I could write a series of short – very short – posts centered around the little tricks that you would need to be an efficient developer when targeting PowerShell. Here's the first tip: how to create a Runspace and have one or more Module(s) preloaded. The RunspaceInvoke class is a handy wrapper that will do most of the plumbing for you if you just want to run scripts or commands. If you want to manually construct your own Pipeline instances then you must work with the Runspace class directly.

    InitialSessionState initial = InitialSessionState.CreateDefault();
    initialSession.ImportPSModule(new[] { modulePathOrModuleName1, ... });
    Runspace runspace = RunspaceFactory.CreateRunspace(initial);
    runspace.Open();
    RunspaceInvoke invoker = new RunspaceInvoke(runspace);
    Collection<PSObject> results = invoker.Invoke("...");

Have fun!

This is a just a short post to remind myself (and you, frustrated googlers/bingers) about the different ways resources are defined and accessed within SharePoint. While some .NET applications use embedded resources or satellite assemblies, SharePoint has a preference for raw RESX files. These resx files are dumped in one of two places:

12\CONFIG\RESOURCES

- application-level "global" resources
- propagated at site definition instantiation
- later modifications require stsadm -o copyappbincontent
- they live in <approot>\App_GlobalAppResources
- accessed via HttpContext.GetGlobalResourceObject / TemplateControl.GetGlobalResourceObject
- http://msdn.microsoft.com/en-us/library/system.web.httpcontext.getglobalresourceobject.aspx
- declaratively accessible <asp:foo runat="server" text="<%$ Resources: myapp.core, ResKeyName %>" />
   (where myapp.core represents myapp.core.resx)

12\RESOURCES
- farm-level global resources
- available to all applications
- remain in 12\RESOURCEs, not copied anywhere
- typically used programatically via SPUtility.GetLocalizedString  ( Microsoft.SharePoint.Utilities )
- http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.utilities.sputility.getlocalizedstring.aspx

PowerShell guru and Admin-extraordinare Jeff Hicks asked a great question that many a Windows administrator has probably asked themselves when working with Hashtables in PowerShell: Why do the key/values come out in a different order than put in? This is a great question and the answer lies in computer science theory, particularly computational complexity theory. Rather than bore you with a ton of nonsense about O(1), O(n) and other propeller-head dribble, I figure I could explain it in terms everyone should be able to understand.

Hashtables, Buckets and HashCodes = Rolodex, Index Cards and Surnames

Yes, if the light hasn’t gone on yet, it will soon. Every .NET object includes a method called GetHashCode. This method returns a number that represents the identity of the object in a kind of fuzzy way. I say “fuzzy” because the hash code for a given instance of an object can be different on different platforms (xp, vista, 2003 etc) or on different bitness (64 vs 32 bit.) This method is used by hashtable to get the “surname” of an object. Instead of Index Cards, a Hashtable uses “buckets” to separate groups of objects. Any given Hashcode will naturally fall into a particular bucket as the function (result) of a high-speed optimized algorithm, much like any given surname naturally falls under a particular letter of the alphabet. Finally, it should be clear to you that using index cards [Hashtable buckets] is way faster than flicking through an unsorted folder [randomized list.]

Just like a Rolodex, the order you add names to it doesn’t dictate the order they are in as you flip through the cards sequentially, which is analogous to sending a Hashtable to out-default.

( from: http://support.microsoft.com/default.aspx/kb/968929 – downloads at foot of page )

Windows PowerShell is a command-line shell and scripting language that is designed for system administration and Automation. Built on the Microsoft .NET Framework, Windows PowerShell enables IT professionals and developers to control and automate the administration of Windows and applications.

New features that are introduced in Windows PowerShell 2.0 include the following:

• Remoting
  Windows PowerShell 2.0 lets you run commands on one or more remote computers from a single computer that is running Windows PowerShell. PowerShell remoting allows for multiple ways of connecting. These ways include interactive (1:1), fan-out (1:many), and fan-in (many:1 by using the IIS hosting model).
• Integrated Scripting Environment
  PowerShell Integrated Scripting Environment (ISE) enables you to run interactive commands and edit and debug scripts in a graphical environment. The main features include color-coded syntax, selective execution, graphical debugging, Unicode support, and context-sensitive help.
• Modules
  Modules allow for script developers and administrators to partition and organize their Windows PowerShell code in self-contained, reusable units. Code from a module executes in its own self-contained context and does not affect the state outside the module.
• Advanced functions
  Advanced functions are functions that have the same capabilities and behavior as cmdlets. However, they are written completely in the Windows PowerShell language, instead of compiled C#.
• Background jobs
  Windows PowerShell 2.0 allows for running a command or expression asynchronously and "in the background" without interacting with the console.
• Eventing
  This feature adds support to the Windows PowerShell engine infrastructure for listening, forwarding, and acting on management and system events.
• Script internationalization
  This new feature enables Windows PowerShell scripts to display messages in the spoken language that is specified by the UI culture setting on the user's computer.
• Script debugging
  New debugging features were added to Windows PowerShell that let you set breakpoints on lines, columns, variables, and commands, and that let you specify the action that occurs when the breakpoint is hit.
• New cmdlets
  Windows PowerShell 2.0 introduces over 100 built-in cmdlets. These cmdlets, excluding other tasks, enables you to do computer-related, event log, and performance counter management tasks.

WinRM 2.0

WinRM is the Microsoft implementation of WS-Management Protocol, a standard Simple Object Access Protocol (SOAP)–based, firewall-friendly protocol that allows for hardware and operating systems from different vendors to interoperate. The WS-Management Protocol specification provides a common way for systems to access and exchange management information across an IT infrastructure.

WinRM 2.0 includes the following new features:

• The WinRM Client Shell API provides functionality to create and manage shells and shell operations, commands, and data streams on remote computers.
• The WinRM Plug-in API provides functionality that enables a user to write plug-ins by implementing certain APIs for supported resources and operations.
• WinRM 2.0 introduces a hosting framework. Two hosting models are supported. One is Internet Information Services (IIS)-based and the other is WinRM service-based.
• Association traversal lets a user retrieve instances of Association classes by using a standard filtering mechanism.
• WinRM 2.0 supports delegating user credentials across multiple remote computers.
• Users of WinRM 2.0 can use Windows PowerShell cmdlets for system management.
• WinRM has added a specific set of quotas that provide a better quality of service and allocate server resources to concurrent users. The WinRM quota set is based on the quota infrastructure that is implemented for the IIS service.

System requirements

WinRM 2.0 and PowerShell 2.0 can be installed on the following supported operating systems:

• Windows Server 2008 with Service Pack 2
• Windows Server 2003 with Service Pack 2
• Windows Vista with Service Pack 2
• Windows Vista with Service Pack 1
• Windows XP with Service Pack 3

BITS 4.0

• Windows Server 2008 with Service Pack 2
• Windows Vista with Service Pack 2
• Windows Vista with Service Pack 1

Updated: now use a temporary file to set text to avoid overflowing command-line buffer

The Windows Clipboard – accessible via System.Windows.Forms.Clipboard – requires an STA thread to read/write to it. By default, the console version of PowerShell 2.0 (i.e. not ISE) starts in MTA mode. This means that read/writing via this class is unreliable. Rather than always starting up console PowerShell in STA mode via the –STA flag, you can use this flag in a sneakier way to get what you want:

function Set-ClipboardText {
        param($text)

        # need to use temp file to avoid exceeding command-line length limit
        $temp = [io.path]::GetTempFileName()

        try {
            set-content -Path $temp -Value $text

            $command = {
                    add-type -an system.windows.forms
                    [System.Windows.Forms.Clipboard]::SetText((get-content $args))
            }
            
            powershell -sta -noprofile -command $command -args $temp

        } finally {
            if ((test-path $temp)) {
                remove-item $temp
            }
        }
}

function Get-ClipboardText {
        $command = {
                add-type -an system.windows.forms
                [System.Windows.Forms.Clipboard]::GetText()
        }
        powershell -sta -noprofile -command $command
}

Essentially we are running PowerShell as a child process temporarily in STA mode, skipping loading the profile and executing a scriptblock.

Asynchronous callback delegates are not a friend to PowerShell. They are serviced by the .NET threadpool which means that if they point to script blocks, there will be no Runspace available to execute them. Runspaces are thread-local resources in the PowerShell threadpool. The .NET threadpool, operating independently, is not too interested in coordinating callbacks with PowerShell. So what do we do?

There is one feature of PowerShell 2.0 that is capable of running scriptblocks in a pseudo-asynchronous manner: Eventing. Any events bound to with Register-ObjectEvent, EngineEvent or WmIEvent can have associated scriptblocks that will get executed when the associated event is raised. So, if we can somehow convert an asynchronous callback to a .NET event then we can run scriptblocks in response to Async .NET Callbacks. I’ve written a simple function called New-ScriptBlockCallback that helps us do exactly that:

#requires -version 2.0

function New-ScriptBlockCallback {
    param(
        [parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [scriptblock]$Callback
    )
<#
    .SYNOPSIS
        Allows running ScriptBlocks via .NET async callbacks.

    .DESCRIPTION
        Allows running ScriptBlocks via .NET async callbacks. Internally this is
        managed by converting .NET async callbacks into .NET events. This enables
        PowerShell 2.0 to run ScriptBlocks indirectly through Register-ObjectEvent.         

    .PARAMETER Callback
        Specify a ScriptBlock to be executed in response to the callback.
        Because the ScriptBlock is executed by the eventing subsystem, it only has
        access to global scope. Any additional arguments to this function will be
        passed as event MessageData.
        
    .EXAMPLE
        You wish to run a scriptblock in reponse to a callback. Here is the .NET
        method signature:
        
        void Bar(AsyncCallback handler, int blah)
        
        ps> [foo]::bar((New-ScriptBlockCallback { ... }), 42)                        

    .OUTPUTS
        A System.AsyncCallback delegate.
#>
    # is this type already defined?    
    if (-not ("CallbackEventBridge" -as [type])) {
        Add-Type @"
            using System;
            
            public sealed class CallbackEventBridge
            {
                public event AsyncCallback CallbackComplete = delegate { };

                private CallbackEventBridge() {}

                private void CallbackInternal(IAsyncResult result)
                {
                    CallbackComplete(result);
                }

                public AsyncCallback Callback
                {
                    get { return new AsyncCallback(CallbackInternal); }
                }

                public static CallbackEventBridge Create()
                {
                    return new CallbackEventBridge();
                }
            }
"@
    }
    $bridge = [callbackeventbridge]::create()
    Register-ObjectEvent -input $bridge -EventName callbackcomplete -action $callback -messagedata $args > $null
    $bridge.callback
}

ArgumentTransformationAttributes are attached to function parameters. They intercept the value coming in and optionally transform it before it is assigned to the target parameter. This is how the powershell type system is enforced:

function Foo ( [string]$str ) { ... }
(gi function:foo).parameters.str.attributes

TypeId
------
System.Management.Automation.ArgumentTypeConverterAttribute
System.Management.Automation.ParameterAttribute

This type converter derives from ArgumentTransformationAttribute. It uses the public utility type [Management.Automation.LanguagePrimitives] (which is full of cool stuff btw) to coerce incoming types to the designated type constraint, in this case [string].

As an aside, you can use the credential attribute on a function parameter too:

function do-something ([system.management.automation.credential()]$cred) { $cred }
do-something # get-credential dialog pops up if $cred is not explicitly passed

And while a little strange but definitely empowering from a future extensibility point of view, you can decorate parameters with entirely inappropriate attributes:

function Foo ( [obsolete($true)][string]$bar ) { ... }

System.ObsoleteAttribute is used in C#/VB.NET to tell the compiler that usage of the decorated item should raise a warning (false) or error (true)

One thing that has been lamented frequently about PowerShell is that it is very difficult to log, if not impossible, to log all of the various types of streams it has to a single source. The legacy Windows shell CMD, and Unix shells like Bash, Ksh etc only deal with three streams: stdin, stdout and stderr for Input, Ouput and Error respectively. PowerShell has many more: Input, Output, Verbose, Warning, Debug, Progress and Error. Finally, the APIs in v2.0 offer enough hooks to unify the logging but you got to work a bit to make it come together. Well, to be honest, you got me doing the work. The rest is easy ;)

import-module .\scriptlogger.psm1 -force

$logger = New-ScriptLogger

# override error handler
$logger.ErrorHandler = {
    param($record)
    
    $record.tostring() >> scriptlog.txt
}

# override verbose handler
$logger.VerboseHandler = {
    param($record)
    
    $record.message >> scriptlog.txt
}

# run scriptblock with logging
$logger.Invoke(
    {
        $verbosepreference='continue';
        $erroractionpreference = 'continue';
        $debugpreference = 'continue';
        write-verbose "verbose";
        write-error "an error";
        write-warning "a warning"
        Write-debug "debug string"
        "this is output"
        1,2,3
    })

<#
    Name     : Universal Script Logging Module (ScriptLogger.psm1)
    Version  : 0.1
    Author   : Oisin Grehan (MVP)
    Site     : http://www.nivot.org/
#>
function New-ScriptLogger {
    New-Module -AsCustomObject -ScriptBlock {
        
        $script:ps              = [powershell]::Create()
        $script:ar              = $null
        $script:module          = $ExecutionContext.SessionState.Module
        
        [scriptblock]
        $script:ErrorHandler    = {
            param(
                [Management.Automation.ErrorRecord]
                $record
            )
            [diagnostics.debug]::writeline(
                "Error: " + $record.tostring());
        }
        [scriptblock]
        $script:WarningHandler  = {
            param(
                [Management.Automation.WarningRecord]
                $record
            )        
            [diagnostics.debug]::writeline(
                "Warning: " + $record.message);
        }
        [scriptblock]
        $script:VerboseHandler  = {
            param(
                [Management.Automation.VerboseRecord]
                $record
            )
            [diagnostics.debug]::writeline(
                "Verbose: " + $record.message);
        }
        [scriptblock]
        $script:DebugHandler    = {
            param(
                [Management.Automation.DebugRecord]
                $record
            )
            [diagnostics.debug]::writeline(
                "Debug: " + $record.message);
        }
        [scriptblock]
        $script:ProgressHandler = {
            param(
                [Management.Automation.ProgressRecord]
                $record
            )        
            [diagnostics.debug]::writeline(
                "Progress: " + $record);
        }
        
        $script:Handlers   = @{
            Error = Register-ObjectEvent $ps.Streams.Error DataAdded -Action {
                & $event.MessageData {& $ErrorHandler @args} $event.sender[$eventargs.index]
            } -MessageData $module #-SupportEvent
            
            Warning = Register-ObjectEvent $ps.Streams.Warning DataAdded -Action {
                & $event.MessageData {& $WarningHandler @args} $event.sender[$eventargs.index]
            } -MessageData $module #-SupportEvent
            
            Verbose = Register-ObjectEvent $ps.Streams.Verbose DataAdded -Action {
                & $event.MessageData {& $VerboseHandler @args} $event.sender[$eventargs.index]
            } -MessageData $module #-SupportEvent
            
            Debug = Register-ObjectEvent $ps.Streams.Debug DataAdded -Action {
                & $event.MessageData {& $DebugHandler @args} $event.sender[$eventargs.index]
            } -MessageData $module #-SupportEvent
            
            Progress = Register-ObjectEvent $ps.Streams.Progress DataAdded -Action {
                & $event.MessageData {& $ProgressHandler @args} $event.sender[$eventargs.index]
            } -MessageData $module #-SupportEvent
        }
        
        function Invoke {
            param(
                [validatenotnullorempty()]
                [scriptblock]$script
            )
            
            try {
            
                write-host -foreground green "Running"
                
                $ps.commands.clear()
                $command = new-object management.automation.runspaces.command $script, $true            
                $ps.commands.addcommand($command) > $null                
                $ps.invoke() # returns output                
            
            } catch {
            
                # oops-ee!
                write-host -foreground red "Unhandled terminating error: $_"
                $record = new-object management.automation.errorrecord $(
                    new-object exception $_.tostring()), "TerminatingError", "NotSpecified", $null
                & $ErrorHandler $record
            
            } finally {
            
                write-host -foreground green "Complete"
            
            }
        }
                
        Export-ModuleMember -Function Invoke -Variable ErrorHandler, WarningHandler, VerboseHandler, DebugHandler, ProgressHandler
    }
}

Have fun!

I’ve been reliably informed (and double checked) and I’m happy to relay to you all that PowerShell 2.0 is available as part of the Windows Management Framework RC. This includes the following components:

• WinRM 2.0
• Windows PowerShell 2.0
• BITS 4.0

This is the culmination of nearly three years’ of work to bring Windows to the cutting edge of automation technology. Grab it while it’s toasty from:

https://connect.microsoft.com/windowsmanagement/Downloads

Spread the word!

updated 2009/7/20: added link to PSEventing for v1.0 event handling
updated 2009/7/24: added link to Get-Delegate script for v1.0 callbacks

There have been some nice improvements made in the latest build of PowerShell with respect to interop with the "callback” pattern in .NET. What exactly are callbacks anyway? It’s exactly what it sounds like, pretty much. In .NET there are sometimes APIs you need to call that expect you to hand them delegates (pointers to methods) which that API will call some time in the future, usually based on certain conditions being fulfilled. If that sounds a bit like .NET events, you’d be right. An event is a much gussied-up callback - it’s just a way of permitting multiple methods to be invoked in response to some condition.

Synchronous Callbacks in PowerShell v1.0

In .NET there are two types of callbacks: Asynchronous (non-blocking) and synchronous (blocking). In PowerShell v1.0, the only callbacks that were catered for were for EventHandler Delegates. This is the method signature that most of the Windows Forms controls expect to call back to in response to button clicks etc. You may have seen code similar to:

$button = new-object system.windows.forms.button
$button.add_Click( { $form.Close() } )

This works because in PowerShell v1.0, there is specialized support for this kind of callback to methods with the EventHandler signature, that is to say, methods with parameters of (object sender, EventArgs e). PowerShell is able to run the ScriptBlock in response to the button being clicked and will even pass the two arguments to the scriptblock for you. When the form is shown from a PowerShell script, there is a single thread that is running the message loop for the application. It is this same thread that handles running the script. In the PowerShell engine, there is a pool of threads created at startup, and each of them has its own “Runspace” for running scripts. Because it is one of the PowerShell threads that is running the application, that same thread is able to run the ScriptBlocks in its Runspace when called upon to do so. Although it is in a slightly roundabout way, this is an example of a synchronous callback. This single application thread is effectively waiting (blocked) for the callback to occur in response to a button click (in reality, it’s doing other things while waiting, but it’s still waiting.)

Some rather creative folks, namely one of the primary developers of PowerShell, wrote a delegate/scriptblock binder in pure script some years ago which you can use to pass script to a .NET api to be called back to in a synchronous manner.  See: Creating arbitrary delegates to ScriptBlocks.

If you want to work with .NET events in version 1.0 of PowerShell, you’ll need an add-on, like my PSEventing Snap-In.

Synchronous Callbacks in PowerShell v2.0

In the latest and greatest version of PowerShell, v2.0 RC (which comes with the public Windows 7 RC), synchronous callbacks got a whole lot easier. PowerShell is now able to deal with pretty much ANY delegate signature, automatically. Lets test this by using the .NET 3.5 System.Func<T, TResult> delegate. This is a generic delegate which lets us pass a method to an API expecting a callback to a method which has one parameters of type T1, and will return type T2. Because it’s generic, we get to pick which parameters. Lets demo creating a ScriptBlock that will be passed a DateTime and returns a String:

add-type –assembly system.core # load .net 3.5
$callback = [system.func[datetime, string]] { param($date); "the date is $date" }
$callback.Invoke( [datetime]::now )
# returns
”the date is 2009/07/14 21:50:35”

We can even take advantage of PowerShell’s super-versatile parameter binder by passing it in a string and having it get coerced to DateTime with ne’er a Parse in sight!

$callback.Invoke(“1/1/2009”)
”the date is 2009/01/01 00:00:00”

So, what’s the point of all this? Why go to all that trouble? Why not just write a function? The point is that functions cannot be called by .NET directly. So when would you need a callback like this in a PowerShell script?

Calling Web Services with Invalid, Untrusted or Expired SSL Certificates

The title says it all – sometimes you need to do this. Usually it’s because you’re working with self-signed, expired or otherwise invalid certificates on a QA or Development system. The New-WebServiceProxy Cmdlet in v2.0 is great for calling Web Services, but it doesn’t have a switch to ignore invalid certificates. If you were writing .NET code in C# or VB.NET, the way go about this is to pass a callback method to an API that expects a RemoteCertificateValidationCallback Delegate. This delegate is designed to point to a method that is passed a handful of arguments describing the attempted connection, and is expected to return a boolean; that is to say, true or false. True means “sure, the connection looks fine – go for it.” A value of False being returned tells .NET to stop the connection before it happens.

The amount of .NET code needed to do this is not a ton, but it’s still a fair handful of lines. Check out this example here: http://blog.jameshiggs.com/2008/05/01/c-how-to-accept-an-invalid-ssl-certificate-programmatically/

Now let’s see how much PowerShell script is needed for this same task:

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

Bwahahahah! Eat that, Mr. C# coder! Again, PowerShell’s binder comes into play here and automatically casts our ScriptBlock to a RemoteCertificateValidateCallback delegate (it’s not really a cast – there is no conversion – it’s a sizeable chunk of code.) From this point on, any attempts to use the New-WebServiceProxy Cmdlet with dodgy SSL certificates will succeed without so much as a warning. In fact, pretty much any other classes, like WebRequest will behave the same way. It’s important to note that this only affects the current AppDomain, that is to say, the current PowerShell process. Other processes on the system will continue to stick their nose up at dodgy SSL certs. Quit PowerShell and restart it -- or set that ServerCertificateValidationCallback property to $null -- and all is right in the world again. This works as long as you use one of PowerShell’s threads to do the work of connecting; i.e. don’t use an asynchronous request. This ensures there is a Runspace available to execute this ScriptBlock.

Converting Synchronous Callbacks into Events

This is really quite straightforward. Taking the previous example, we would generate an event inside the scriptblock using New-Event, and then bind one or more event handlers using the Register-EngineEvent Cmdlet:

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {
		new-event -SourceIdentifier SslCheck -MessageData $args > $null
		$true
	}
# dump out arguments to cert validate callback
Register-EngineEvent -SourceIdentifier SslCheck -Action { write-output $args }

In Part Two: Asynchronous Callbacks in PowerShell v1.0 and v2.0

update: missing backtick ` to escape the $verbosepreference variable

A question came up on stack overflow (you don’t know what that is? shame on you!) today from someone asking how they could capture the Verbose stream from a pipeline they ran in a C# program. As it turns out, the same technique is used in script, so I’ll give that example instead since I’m sure the C# guys and gals will have no problem converting the script.

The key is using the new (to v2.0) System.Management.Automation.PowerShell Type, which has a built-in Type Accelerator of [powershell]. It has a static method, Create, which is used to create an instance. This instance is pretty much ready to roll. It has a Streams property, which is of Type PSDataStreams. This Type has properties representing each collection of Error, Progress, Verbose, Debug and Warning.

$ps = [powershell]::create()
$ps.Commands.AddScript("`$verbosepreference='continue'; write-verbose 42")
$ps.invoke()
$ps.streams.verbose

Message InvocationInfo                              PipelineIterationInfo
------- --------------                              ---------------------
42      System.Management.Automation.InvocationInfo {0, 0}

update #1 2009/5/23: noted that local jobs (start-job) no longer require an elevated shell.

update #2 2009/5/28: ISE object model and shortcut changes; update for set-psessionconfiguration cmdlet (new screenshot); module changes (highlighted new manifest member names, binary module can now be root module);

I’ve been meaning to write this for a while, but it’s been a busy time. This is a comparison of the significant differences between the standalone CTP3 or Windows 7 Beta version and the version that comes with Win7 RC (6.1.7100.0). For all intents and purposes, the CTP3 version (6.1.6469.0) is exactly the same as the Windows 7 Beta (6.1.7000.0) version.

This is not going to be an exhaustive list of differences, but I will continue to update this post as I find more things worth documenting. It should be safe to bookmark the permalink. One of the nicest things about this release is that it appears that, without exception, all built-in Cmdlets have help. A lot of things have been cleaned up and fixed in this build, from formatting of text to typos and minor bugs/glitches.

Cmdlet Differences

This is a table listing Cmdlets that have either changed (navy), been added (green, underlined) or removed (red, strike-through.) Changed Cmdlets have their parameters listed in the second column. A changed parameter means that its Type has been changed; e.g. it accepts a different .NET object than before. This is generally nothing to worry about since the corresponding source of such objects is usually changed to match – typically another Cmdlet. Parameters  and Cmdlets that have not changed, are not listed.

Cmdlet	Parameters
Invoke-Command	NoCompression   Session   SessionOption
Remove-Computer	Force   Reboot   ComputerName
Add-Computer	ComputerName   Reboot
Rename-Computer
Test-Connection	ComputerName   Quiet   Destination
Export-FormatData	Path   FilePath
Receive-Job	Session
Start-Job	InitializationScript   RunAs32   ConfigurationName   CertificateThumbprint   NoCompression
Get-Module	Recurse
New-ModuleManifest	ProcessorArchitecture   DotNetFrameworkVersion   PowerShellHostName   PowerShellHostVersion   FileList   ModuleList   FunctionsToExport   AliasesToExport   VariablesToExport   CmdletsToExport   OtherFiles   ExportedFunctions   ExportedAliases   ExportedVariables   ExportedCmdlets   RequiredModules
Set-PSBreakpoint	Script
Enable-PSRemoting
Remove-PSSession	Session
Enter-PSSession	NoCompression   Session   SessionOption
New-PSSession	NoCompression   Session   SessionOption
Export-PSSession	OutputModule   Module   ModuleName   PSSnapin   Session
Import-PSSession	Module   PSSnapin   Session
New-PSSessionOption
Get-WSManInstance	Associations   CertificateThumbprint   References
Set-PSSessionConfiguration	ShowSecurityDescriptorUI

Alias Changes

Some tweaking of aliases here. Personally I find alias changes in general to get under my skin. Aliases are the first thing I learn and the first thing to trip me up when things change. Regardless, the changes appear to make sense and are perhaps a bit more mnemonic than before.

Removed

emm (Export-ModuleMember), which (Get-Command) and grid (Out-Gridview)

Added

ise (powershell_ise.exe), rmo (Remove-Module) and saps (Start-Process)

Changed

imo –> ipmo (Import-Module)

Language Enhancements

The major change that has come to light so far is that statements are now allowed on the right hand of an expression without having to use subexpressions. This is a great fix, and one that will reduce the margin for error (and confusion) by a large amount. Previously in CTP3, in order to use a statement like “if”, you had to use the following syntax:

$result = $( if ($true) { 42 } )

Now, you can drop the $( and ):

$result = if ($true) { 42 }

or

$sequence = foreach ($i in 0..15) { [math]::pow(2, $i) }

This is truly great stuff.

Jobs/Remoting

The best news here is the abundant help now available at your fingertips. Lots of examples and meaty information concerning PSSessions and PSSessionConfigurations.

Local Jobs

Local jobs created now with Start-Job { ... } use an IPC channel to talk to the local WinRM service to create jobs instead of using the more heavyweight HTTP channel. Yes, you can infer from this that local jobs are still out of process; they run in their own isolated runspace and have no access to the interactive session. What this means in simpler terms is that local jobs are a lot faster now to get started. The biggest win for local jobs is that they no longer require an elevated shell! you can submit local jobs as a regular user now – just not remote ones (unless the applicable remote PSSessionConfiguration is set to allow this - by default the ACL is admins only).

Remoting

A welcome addition to this build is a new, dedicated Enable-PSRemoting Cmdlet:

To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, you must start Windows PowerShell with the "Run as administrator" option.

Session Configurations

There are a raft of Cmdlets dedicated to managing session configurations. So what is a session configuration? To qoute the ever-present help system:

That SecurityDescriptorSddl property looks like a lot of fun to modify, right? Don’t worry, the ShowSecurityDescriptorUI comes to the rescue:

Modules

Manifest Members

Modules have received some nice incremental improvements as well as some syntactic changes. You should have noticed above that the manifest fields (exposed as parameters on New-ModuleManifest)  have changed to reflect the two-stage process of how a module’s members get exposed to the importer’s scope. A module passively exports members with Export-ModuleMember, and the caller actively imports them with Import-Module; hence “FunctionsToExport,” which subtly says that this can be imported.

Binary Modules

A binary module is now allowed to be the root module in a manifest by pointing the ModuleToProcess key at the assembly, e.g. ModuleToProcess = “Pscx.dll.” This seems more intuitive than before with the [seemingly] arbitrary restriction that they must be secondary to a text based psm1.

Built-In Modules

Shipping with Windows 7 for PowerShell comes two new Modules along with the others you should have noticed that arrived with CTP3 (BitsTransfer/FileTransfer and PSDiagnostics.)

AppLocker

AppLocker provides simple, powerful, rule-based structures for specifying which applications can run that are centrally managed using Group Policy. It introduces "publisher rules" that are based on an application's digital signature, making it possible to build strong rules that account for application updates. For example, an organization can create a rule to "allow all versions greater than 1.0 of Microsoft Dynamics CRM to run if signed by Microsoft." With correctly structured rules, IT professionals can safely deploy updates to allowed applications without having to build a new rule for each version update.

About AppLocker on TechNet

TroubleshootingPack

Windows Troubleshooting Platform (WTP) provides ISVs, OEMs, and administrators the ability to write troubleshooting packs that discover and resolve software and hardware issues, such as configuration issues, failed hardware, network issues, and application compatibility issues. In WTP, an issue is referred to as a root cause. Previously, troubleshooting software and hardware issues was a manual process; however, using WTP you can automate the process of fixing the most common issues that the user might encounter.

About WTP on MSDN

PowerShell Integrated Scripting Environment

The ISE has been vastly improved in terms of usability and sharpness in this build. Difficult to isolate any one part of it that is much better; the whole experience is just way smoother and intuitive.

ISE Object Model

The object model naming has changed quite a bit to be more intuitive and friendly to beginners. Who needs to know about Runspaces? It’s a Tab, silly!

* Note: You may only invoke script on a tab other than the tab you’re using to execute this command (because you can’t run two commands at the same time on the same tab!)

The PowerShell team posted a way to make the RC build fairly compatible with CTP3 by adding new members to the $PSISE object which will proxy attempts to use the old API to the new API. The post is called “Update-TypeData, ISE CTP3 vs ISE RC, and Teched2009 Demos.”

Shortcut Changes

The shortcut to jump to the Script Pane is now Ctrl+I. (use Ctrl+D to jump to the Command pane).

Summary

The RC build is all about bugfixes and incremental improvements. I’m sure there’ll be more fixes and additions as we near RTW/RTM and I’ll be here to post as much info about them as possible. This is still just a drop in the ocean of what PowerShell 2.0 can do, and I’ll post more technical demos of features over the next little while.

Tips: run “Get-Help about_*” to get a list of all the overview topics for the various features in PowerShell v2.

Have fun!

After some hints from Ibrahim on the Microsoft PowerShell team, I realised it was possible to rewrite the dynamic module body generation from the Get-Interface function in my last post without using string literals and nested here-string tricks. I was able to increase the brevity by using a new [to PowerShell] v2 feature called “Closures.” Ibrahim talks a bit about the technique over on the official PowerShell Blog. It’s a common feature in so-called Functional languages and there are plenty of other tidbits to read about it, both academic and practical if you search online.

A closure in PowerShell, in short, lets you take a snapshot of a ScriptBlock by calling its GetNewClosure() method. The snapshot is taken of its variables and will let you pass it around so it is no longer directly tied to the particular scope chain it was declared in. As some are fond of saying though, Thar Be Dragons. Although closing around a ScriptBlock will make copies of the PSVariables that are within, it is still subject to the whims of .NET – particularly ByRef and ByValue semantics. If a ScriptBlock contains a PSVariable pointing to an integer, it’s safe to say that integer will be copied and is frozen as that value as long as you remain within the domain of the current SessionState context (more about this later).

.NET intervenes: ByRef and ByVal

Closing around a ScriptBlock that contains PSVariables that point to reference types, however - like Arrays for example – will only duplicate the reference, not the instance itself. If elements in the array are changed via the PSVariable from the originating scope, the corresponding array element in the closure will also change. After all – you got a copy of the pointer, not the value itself. This is the very essence of ByRef and ByVal.

Let’s take a look at the revised Get-Interface script:

function Get-Interface {

#.Synopsis
#   Allows PowerShell to call specific interface implementations on any .NET object. 
#.Description
#   Allows PowerShell to call specific interface implementations on any .NET object. 
#
#   As of v2.0, PowerShell cannot cast .NET instances to a particular interface. This makes it
#   impossible (shy of reflection) to call methods on explicitly implemented interfaces.   
#.Parameter Object
#   An instance of a .NET class from which you want to get a reference to a particular interface it defines.
#.Parameter InterfaceType
#   An interface type, e.g. [idisposable], implemented by the target object.
#.Example
#   // a class with explicitly implemented interface   
#   public class MyObj : IDisposable {
#      void IDisposable.Dispose()
#   }
#   
#   ps> $o = new-object MyObj
#   ps> $i = get-interface $o ([idisposable])
#   ps> $i.Dispose()      
#.ReturnValue
#   A PSCustomObject with ScriptMethods and ScriptProperties representing methods and properties on the target interface.
#.Notes
# AUTHOR:    Oisin Grehan http://www.nivot.org/
# LASTEDIT:  2009-03-28 18:37:23
# REVISION:  0.2

    [CmdletBinding()]
    param(
        [ValidateNotNull()]
        $Object,
        
        [ValidateScript( { $_.IsInterface } )]
        [type]$InterfaceType
    )

    $script:t  = $Object.GetType()
    
    try {
        
        $script:m  = $t.GetInterfaceMap($InterfaceType)

    } catch [argumentexception] {
        
        throw "Interface $($InterfaceType.Name) not found on ${t}!"
    }

    $script:im = $m.InterfaceMethods
    $script:tm = $m.TargetMethods
    
    # TODO: use param blocks in functions instead of $args
    #       so method signatures are visible via get-member
    
    $body = {
         param($o, $i) 
         
         $script:t  = $o.GetType()
         $script:m  = $t.GetInterfaceMap($i)
         $script:im = $m.InterfaceMethods
         $script:tm = $m.TargetMethods
                  
         for ($ix = 0; $ix -lt $im.Count; $ix++) {
            
            $mb = $im[$ix]

            # for the function body, we close over $ix to capture the index
            # so even on the next iteration of this loop, the $ix value will
            # be frozen within the function's scriptblock body
            set-item -path function:script:$($mb.Name) -value {

                # call corresponding target method
                $tm[$ix].Invoke($o, $args)

            }.GetNewClosure() -verbose -force

            if (!$mb.IsSpecialName) {
                # only export the function if it is not a getter or setter.
                Export-ModuleMember $mb.Name -verbose
            }
         }
    }

    write-verbose $body.tostring()    
    
    # create dynamic module
    $module = new-module -ScriptBlock $body -Args $Object, $InterfaceType -Verbose
    
    # generate method proxies - all exported members become scriptmethods
    # however, we are careful not to export getters and setters.
    $custom = $module.AsCustomObject()
    
    # add property proxies - need to use scriptproperties here.
    # modules cannot expose true properties, only variables and 
    # we cannot intercept variables get/set.
    
    $InterfaceType.GetProperties() | % {

        $propName = $_.Name
        $getter   = $null
        $setter   = $null
       
        if ($_.CanRead) {
            
            # where is the getter methodinfo on the interface map?
            $ix = [array]::indexof($im, $_.GetGetMethod())
            
            # bind the getter scriptblock to our module's scope
            # and generate script to call target method
            #
            # NOTE: we cannot use a closure here because sessionstate
            #       is rebound to the module's, and $ix would be lost
            $getter = $module.NewBoundScriptBlock(
                [scriptblock]::create("`$tm[{0}].Invoke(`$o, @())" -f $ix))
        }
        
        if ($_.CanWrite) {
            
            # where is the setter methodinfo on the interface map?
            $ix = [array]::indexof($im, $_.GetSetMethod())
            
            # bind the setter scriptblock to our module's scope
            # and generate script to call target method
            #
            # NOTE: we cannot use a closure here because sessionstate
            #       is rebound to the module's, and $ix would be lost
            $setter = $module.NewBoundScriptBlock(
                [scriptblock]::create(
                    "param(`$value); `$tm[{0}].Invoke(`$o, `$value)" -f $ix))
        }
        
        # add our property to the pscustomobject
        $prop = new-object management.automation.psscriptproperty $propName, $getter, $setter
        $custom.psobject.properties.add($prop)
    }
    
    # insert the interface name at the head of the typename chain (for get-member info)
    $custom.psobject.TypeNames.Insert(0, $InterfaceType.FullName)
    
    # dump our pscustomobject to pipeline
    $custom
}

The changes are around line 56, where I now declare $body with a script syntax, no longer using [scriptblock]::create. Where previously I used a subexpression inside a here-string to general literal function declarations, I now use a “for” loop and set-item to create the functions (thanks Ibrahim!). You can see that I am calling GetNewClosure() on the function body each time I create a new function. This “captures” the value of the $ix index variable, so that the value will not change on subsequent loops. If I did not use closures, when the for loop ended, all of the functions would be using the same terminating value of the loop for $ix, which would be $im.count + 1. Doh.

Module SessionState Context, Wha?

So if I ripped out that literal string parsing stuff for the module $body, why am I still using it for the property getter/setter generation? (lines 115 / 130)  Well, I have no choice: Creating a new module creates an entirely new SessionState; in simple terms, session state is essentially a giant Hashtable in which PSVariables are stored. If I closed over those get/set ScriptBlocks containing the $ix PSVariable, when it is bound to the module it will use the new module’s SessionState – which is empty! The value of $ix would be undefined. The other variables in those strings are escaped, because they will be evaluated in the module’s context later, when the getters and setters are invoked. Those variables are seeded by the module’s initialization done at the new-module call at line 88.

It’s all very succinct, but rest assured, very powerful.

Have fun!

NOTE: I realise that some more refactoring could probably eliminate this script parsing, but the value is in understanding how modules may affect usage of closures, and the problems that may occur.

This is a bit of a hardcore example of the power that modules have brought to the table in v2.0. First, a little background - PowerShell’s type adaptation system has always ignored the concept of interfaces. Frankly, it never really needed to pay them any attention. The adapted view of any instance of a .NET class is just an aggregate of all its methods; the most derived instance is the default, and only, view. This is the most simple and most frequently used view. However, this all goes to hell when you bring in the notion of explicit interfaces.

Explicit Interface Definitions

Here’s an example of a C# class, Test, with two interfaces: IFace, and IFaceEx. I’ve put this whole example in PowerShell script so you can easily test it without firing up Visual Studio. Add-Type cmdlet to the rescue!

if (-not ("Test" -as [type])) {    
    add-type @"
        public interface IFace {
            string Hello(string name);
            string Goodbye();
        }
        
        public interface IFaceEx {
            string Hello(string name);
            string Goodbye();
            string Prop1 {
                get;
                set;
            }                
        }
        
        public class Test : IFace, IFaceEx {
            public string Hello(string name) {
                return "Hello" + name + " from IFace";
            }
            public string Goodbye() {
                return "Goodbye from IFace";
            }            
            string IFaceEx.Hello(string name) {
                return "Hello " + name + " from IFaceEx";
            }
            string IFaceEx.Goodbye() {
                return "Goodbye from IFaceEx";
            }
            
            private string _prop1 = "Foo";
            
            string IFaceEx.Prop1 {
                get { return _prop1; }
                set { _prop1 = value; }
            }
        }
"@    
}

If you new up an instance of Test, you’ll see that the explicit interface definitions are hidden. Any calls to Hello(string) will invoke the IFace implementation.

There is no way to call IFaceEx.Hello without using reflection!

So, this is where the beauty of modules can help us. The following function will take an instance of a .NET class, and the interface you want a  reference to, and will return a PSCustomObject with ScriptMethods and ScriptProperties bound to that interface’s contract. You don’t have to do this only with explicit interfaces, any interfaces will work ;-)

Introducing Get-Interface

A script is worth a thousand words.

function Get-Interface {

#.Synopsis
#   Allows PowerShell to call specific interface implementations on any .NET object. 
#.Description
#   Allows PowerShell to call specific interface implementations on any .NET object. 
#
#   As of v2.0, PowerShell cannot cast .NET instances to a particular interface. This makes it
#   impossible (shy of reflection) to call methods on explicitly implemented interfaces.   
#.Parameter Object
#   An instance of a .NET class from which you want to get a reference to a particular interface it defines.
#.Parameter InterfaceType
#   An interface type, e.g. [idisposable], implemented by the target object.
#.Example
#   // a class with explicitly implemented interface   
#   public class MyObj : IDisposable {
#      void IDisposable.Dispose()
#   }
#   
#   ps> $o = new-object MyObj
#   ps> $i = get-interface $o ([idisposable])
#   ps> $i.Dispose()      
#.ReturnValue
#   A PSCustomObject with ScriptMethods and ScriptProperties representing methods and properties on the target interface.
#.Notes
#   AUTHOR:    Oisin Grehan http://www.nivot.org/
#   LASTEDIT:  2009-03-25 11:35:23

    [CmdletBinding()]
    param(
        [ValidateNotNull()]
        $Object,
        
        [ValidateScript( { $_.IsInterface } )]
        [type]$InterfaceType
    )

    $private:t  = $Object.GetType()
    
    try {
        
        $private:m  = $t.GetInterfaceMap($InterfaceType)

    } catch [argumentexception] {
        
        throw "Interface $($InterfaceType.Name) not found on ${t}!"
    }

    $private:im = $m.InterfaceMethods
    $private:tm = $m.TargetMethods
    
    # TODO: use param blocks in functions instead of $args
    #       so method signatures are visible via get-member
    
    $body = [scriptblock]::Create(@"
        param(`$o, `$i)    
        
        `$script:t  = `$o.GetType()
        `$script:m  = `$t.GetInterfaceMap(`$i)
        `$script:im = `$m.InterfaceMethods
        `$script:tm = `$m.TargetMethods
        
        # interface methods $($im.count)
        # target methods $($tm.count)
        
        $(
            for ($ix = 0; $ix -lt $im.Count; $ix++) {
                $mb = $im[$ix]
                @"
                function $($mb.Name) {
                    `$tm[$ix].Invoke(`$o, `$args)
                }

                $(if (!$mb.IsSpecialName) {
                    @"
                    Export-ModuleMember $($mb.Name)

"@
                })
"@
            }
        )
"@)
    write-verbose $body.tostring()    
    
    # create dynamic module
    $module = new-module -ScriptBlock $body -Args $Object, $InterfaceType -Verbose
        
    # generate method proxies - all exported members become scriptmethods
    # however, we are careful not to export getters and setters.
    $custom = $module.AsCustomObject()
    
    # add property proxies - need to use scriptproperties here.
    # modules cannot expose true properties, only variables and 
    # we cannot intercept variables get/set.
    
    $InterfaceType.GetProperties() | % {

        $propName = $_.Name
        $getter   = $null
        $setter   = $null
       
        if ($_.CanRead) {
            
            # where is the getter methodinfo on the interface map?
            $ix = [array]::indexof($im, $_.GetGetMethod())
            
            # bind the getter scriptblock to our module's scope
            # and generate script to call target method
            $getter = $module.NewBoundScriptBlock(
                [scriptblock]::create("`$tm[{0}].Invoke(`$o, @())" -f $ix))
        }
        
        if ($_.CanWrite) {
            
            # where is the setter methodinfo on the interface map?
            $ix = [array]::indexof($im, $_.GetSetMethod())
            
            # bind the setter scriptblock to our module's scope
            # and generate script to call target method
            $setter = $module.NewBoundScriptBlock(
                [scriptblock]::create(
                    "param(`$value); `$tm[{0}].Invoke(`$o, `$value)" -f $ix))
        }
        
        # add our property to the pscustomobject
        $prop = new-object management.automation.psscriptproperty $propName, $getter, $setter
        $custom.psobject.properties.add($prop)
    }
    
    # insert the interface name at the head of the typename chain (for get-member info)
    $custom.psobject.TypeNames.Insert(0, $InterfaceType.FullName)
    
    # dump our pscustomobject to pipeline
    $custom
}

$if = Get-Interface (new-object test) ([ifaceex]) -verbose
$if.Hello("Oisin") # returns Hello Oisin from IFaceEx

$if.Prop1 = "Test" # property setter
$if.Prop1 # propery getter

Have fun!

It looks like the SharePoint team is slowly catching up to what the community has had for years in various guises on CodePlex, but I’ve a good feeling that sometime in the future, the community will finally be able to relax and get back to real work as official support will surpass even the best of the open source offerings (optimistic? we’ll see). Here’s the feature set for the current CTP:

(These are features added in v1.3 which were not available in v1.2 or v1.1)

· Support for developing and deploying on 64 bit (x64).

• New menu commands within Visual Studio
  • Package - package the solution but does not deploy.
  • Retract - retracts and deletes the active solution from SharePoint.
  • Quick Deploy
    • Copy to 12 - copies template files, modules to the 12 Hive.
    • Copy Binarie(s) - deploys only the assemblies.
    • Copy Both
    • Recycle Application Pool
    • Attach to IIS Worker Processes

• WSP View Improvements (Create New Feature)
  • Allows specify feature scope (Web, Site, Web Application, Farm)
  • Allows creation of a feature receiver
  • Option to automatically create elements.xml with new feature
  • Elements can be dragged from one feature to another
• Build Commands Updates
  • Package command added to Visual Studio IDE and command line.
  • Retract command added to Visual Studio IDE and command line.

1) Command line operation is as follows:
devenv.exe <Project.csproj or Solution.sln and other usual flags> /deploy Debug
devenv.exe <Project.csproj or Solution.sln and other usual flags> /deploy Debug /package
devenv.exe <Project.csproj or Solution.sln and other usual flags> /deploy Debug /retract
Note that with the /package and /retract flags the /deploy flag is required.  

• CTRL-F5 no longer launches the debugger. Use F5 to launch the debugger. CTRL-F5 will just launch the web browser and show the SharePoint site.
• SharePoint Solution Generator Enhancements
  • Export from publishing sites. Note that round tripping of generated sites is not supported for anything but the simplest of sites. Instead some editing may be required.
• Correct VB and C# Inconsistency Correction
  • VB VSeWSS projects no longer use VSeWSS as the root namespace
• New Item Templates for RootFiles
  • Create a <RootFiles> item from template.
• Web Part Item Template Improvements
  • Allows selection of deployment model to the global assembly cache (GAC) or to the \BIN directory. For /BIN deployment a simple Code Access Security permissions set is provided.
• Easier Web Part Project Item Rename
  • Detect web part rename and modify dependent files
• Support for deploying dependant assemblies added as a reference with CopyLocal=true.
  • VSeWSS now checks for any "CopyLocal=true" reference and incorporates this binary in the manifest.  The binary is added to the manifest with a DeploymentTarget matching the first binary found in the manifest, usually the project target binary.  Subsequent changes to "CopyLocal", or removing a binary altogether will correctly be cleaned up when rebuilding the manifest (either through WSP view or through a deployment command).  Changes to the DeploymentTarget can be made by editing the manifest.
• Improved solution validation during full deployment
• Validation Logging
  • Adding the element <add key="IfLog" value="true" /> to the <appSettings> node of your web.config will turn on validation logging. Logging occurs during a full deployment from a VSeWSS project and can be used for diagnostic purposes. Note: The log location will be noted on the build output window."
• Conflict resolution dialog when deploying from within Visual Studio
  • Duplicate Features: If a feature with the same name as a feature you are trying to deploy is already on the server a dialog will give you the choice of uninstalling the existing feature first. If the feature was deployed via WSP the entire solution is retracted. If the feature was manually installed it will be deactivated then uninstalled.
  • Duplicate Site Definition Folders: Site definition folder is the same as 12/Templates/SiteTemplates or the WebTemp folder already exists. The option to delete the deployed folder is available.
  • RootFiles and Templates: If there is a RootFile or Template with the same name the option to delete the files first is given.
  • Solutions: If a solution with the same name exists on the server (possibly unique solution IDs) the option is given to retract and delete the existing solution.
• The List Definition from Content Type template now allows for the creation of a List Definition Event Receiver.

Grab it from the Microsoft Download Center.

UPDATED 2009-03-11: BUGFIXES FOR CTP3! PLEASE RE-DOWNLOAD v0.2.1

One of the things I hear now and then is that while PowerShell the language can be mastered with the requisite effort, the .NET namespace is considerable harder to get a handle on. Wouldn’t it be nice if you could type things like:

PS> get-help -object [string]::format

Since Functions take precedence over native Cmdlets in the command search order, the first thing you might think is to create a function with the same name, get-help, that can do this. The function itself would have the same parameters as the native Cmdlet, and add one of its own: -object. If the arguments do not belong to the “object” ParameterSet, then the function would splat (using the @ operator) the original arguments to the native Cmdlet transparently and transfer control. The user is none the wiser we had a quick peek at the arguments. So, before we run off duplicating a Cmdlet’s surface through script, first stop, Command Proxies!

Command Proxies

First off, required reading: Extending and/or Modifying Commands with Proxies. Ok, now that you’ve got read that entirely and gotten it  out of the way, you understand that the [ProxyCommand]::Create(…) method lets you automatically generate a function that delegates to a steppable pipeline wrapping the original Cmdlet, right? What I did then is to pack all of these functions into a psm1 module, create a nice psd1 module manifest and away we go.

The ObjectHelp Get-Help Extension Module

So here’s a quick look at the help for my module, in friendly, easy to read Cmdlet help style. The code for the PSM1 module file is way too large to dump here on my blog like I would usually do, so it’s available at as an attachment at the foot of the page. This help below is in a comment in the psm1 file itself.

    NAME
   
        ObjectHelp Extensions Module 0.2 for PowerShell 2.0 CTP3
    
    SYNOPSIS
   
         Get-Help -Object allows you to display usage and summary help for .NET Types and Members.
        
    DETAILED DESCRIPTION
   
        Get-Help -Object allows you to display usage and summary help for .NET Types and Members.
   
        If local documentation is not found and the object vendor is Microsoft, you will be directed
        to MSDN online to the correct page. If the vendor is not Microsoft and vendor information
        exists on the owning assembly, you will be prompted to search for information using Microsoft
        Live Search.
    
    TODO
    
         * localize strings into PSD1 file
         * Implement caching in hashtables. XMLDocuments are fat pigs.
         * Support getting property/field help
         * PowerTab integration
         * Test with Strict Parser
            
    EXAMPLES

        # get help on a type
        PS> get-help -obj [int]

        # get help against live instances
        PS> $obj = new-object system.xml.xmldocument
        PS> get-help -obj $obj

        or even:
       
        PS> get-help -obj 42
       
        # get help against methods
        PS> get-help -obj $obj.Load

        # explictly try msdn
        PS> get-help -obj [regex] -online

        # go to msdn for regex's members
        PS> get-help -obj [regex] -online -members

    CREDITS
   
        Author: Oisin Grehan (MVP)
        Blog  : http://www.nivot.org/
   
        Have fun! 

Usage Examples

So what does it actually look like when you call help? If the help is available locally, it is displayed inline in the console (or ISE). Help for all types in MSCorlib and System is pre-cached. Any other help for types in assemblies belonging to the BCL (Base Class Libraries – effectively the stock .NET assemblies) will be loaded on-demand. This typically takes just a few seconds and will cached for the rest of your session.

TODO and BUGS

Right now, it cannot deal with properties. That is to say, trying:

PS> get-help –object $s.length

where $s is a string, will get help on the property _type_, not the property itself. I have some ideas to get around this, so if you can wait for 0.3, I’d be happy. Of course you can wait. You have no choice. :D

Download

The two files come in a zip file. Unzip this file to ~\documents\windowspowershell\modules\objecthelp\ where ~ is your home directory. On vista/win7 this would be c:\users\username. On XP, it would be c:\documents and settings\username. To load it, just execute:

PS> import-module objecthelp

That’s it! Have fun!

A couple of months ago I had a brief Q&A with the cdndevs guys over on blogs.msdn.com. It looks like it went live recently because I’ve been getting stopped in the streets and harassed for a photo etc. No, not really. But if you want to read, take a look over at http://blogs.msdn.com/cdndevs/archive/2009/02/12/mvp-insider-q-a-with-oisin-grehan.aspx ;-)

Some of you may have heard that CTP3 has support for transferring files from remote servers using BITS (Background Intelligent Transfer Service) and quite possibly had a little dig around for it. It’s not easy to find as using “get-help BITS” will not return any help unless you’ve already loaded the module. Not a great win for discoverability, but hey, sometimes you just have to read the manual, expletive deleted. So, lets have a quick look at how this works.

So, ok, we can see we’ve got a module for FileTransfer (BITS), but where did this come from? Take a peek into $pshome\Modules to find out. This is the location for system-wide (global) modules. It rests under $PSHome, which is the home for PowerShell, in $env:systemroot\windowspowershell\v1.0.

Yes, even PowerShell v2 lives there. This is one of those unfortunate things whereby the team decided early on that they would support side-by-side versions of PowerShell, implying that v2 might not be backwards compatible with v1. This is reflected also in the choice of file extension: ps1. The extension ps2 would have been used for v2. This was probably a poor show of faith in their own abilities to design such a great version one product, because as it turns out, v1.0 was such an excellent release that they were able to build on it for v2 without compromising, or breaking backwards compatibility (apart from a couple of minor edge cases, mainly bugfixes). So, the end result is that future versions of PowerShell will inherit the $pshome, pay a little inheritance tax and hopefully avoid foreclosure :).

The files in the FileTransfer module directory are laid out as follows:

(Hey look! another built-in module – PSDiagnostics - I’ll leave that one for you guys to explore).

So, there are four files there. A ps1xml Format file, which tells PowerShell how to textually render the .NET objects returned by the Cmdlets. A psd1 Module Manifest file, which tells PowerShell what files comprise the Module and a binary DLL which in this case does NOT contain the Cmdlets, but instead is what’s called an “Interop Assembly.”  (sometimes known as Primary Interop Assemblies or PIAs, read about them here: Primary Interop Assemblies – there are subtle differences between IAs and PIAs, but not enough to warrant discussion here). Essentially this DLL lets .NET, and by extension, PowerShell, talk to the native COM APIs that wrap the BITS services on XP,Vista,Win7,Win 2003 and Win 2008. Lets take a peek into the Module Manifest:

If it looks like I just dumped a Hashtable out, you’re right. That’s all a manifest is: a Hashtable. Of course, the key names are important and in this case, lets take a look at two in particular, NestedModules and RequiredAssemblies.

The RequiredAssemblies key is responsible for actively loading .NET assemblies containing standard .NET types. It does not extract Providers and Cmdlets and add them to the runspace; this is what the other key, NestedModules, does. Like I said already, this DLL is the interop assembly. So where is the NestedModules loading that other module from? I don’t see any other DLLs in the directory, and I know there are no Cmdlets in that interop assembly. Lets take a peek at one of the Cmdlets itself and find out:

Aha, it’s reading it from the GAC. When PowerShell was installed, it must have installed this DLL there. This is the DLL that contains our Cmdlets. I know this is true because I used one of the Cmdlets to tell me where it lives. “GCM” is the alias for Get-Command which will get us metadata about any given command in PowerShell (including functions – new to v2).

So, lets use a one-liner to get the names of all the Cmdlets in this module, and the synopsis summary for the help:

This yields the following:

I guess this covers it for the moment. Going into a full discussion about how BITS actually works is worth another post in itself. Suffice it to say, there are plenty of examples in the help itself. Just run:

get-help add-filetransfer –example | more

To see an example on how to use the Cmdlet (or any of the others). The team have done a good job here.

Have fun!

It’s been quite a few years -- November 14, 2006 to be exact -- since the final release of PowerShell 1.0. Let’s see what the lazy buggers have been up to since then. Only kidding, they’re far from lazy; we’ve gained an extra one hundred and six new cmdlets, moving from 131 to 237. We’ve also gained another provider, WSManProvider which lets you explore and manipulate the WS-Man configuration. Finally, the number of public Types (.NET classes usable by 3rd parties to extend PowerShell) has increased from 447 to 749. So how do I know all this? Well, some months ago I wrote a suite of build analysis Cmdlets for examining the assemblies that comprise PowerShell. In its current form it’s of very little use to 3rd parties, but I’ve had some requests to open it up and allow it to analyze any binary modules and snap-ins, which is a good idea I think. Watch this space. Anyway, I’m going to dump out some interest information on the differences between v1.0 and v2.0 CTP3, along with the one-liners I’m using to generate the information.

update feb 5: added breaking changes

Breaking Changes to Windows PowerShell 1.0

The following changes in Windows PowerShell V2.0 CTP3 might prevent features designed for Windows PowerShell 1.0 from working correctly.

• The value of the PowerShellVersion registry entry in HKLM\SOFTWARE\Microsoft\PowerShell\1\PowerShellEngine has been changed to 2.0.
• New cmdlets and variables have been added. These are listed below. These new elements might conflict with variables and functions in profiles and scripts.
• -IEQ operator does a case insensitive comparison on characters.
• Get-Command gets functions along with cmdlets by default.
• Any native command that generates a user interface blocks if it is pipelined to the Out-Host cmdlet.
• Added new language keywords: Begin, Process, and End. Any commands called begin, process or end are interpreted as language keywords and might result in parsing errors.
• Cmdlet name resolution has changed. In Windows PowerShell 1.0, a runtime error was generated when two Windows PowerShell snap-ins exported cmdlets with the same name. In Windows PowerShell V2, the last cmdlet loaded is the one that is executed if the cmdlet name is not qualified by a snap-in name.
• Terminating errors that are thrown in a pipeline do not terminate the pipeline. Instead, they are written to the host.
• A function called with '-?' parameter gets the help topic for the function, if one is included in the function.

There are no changes to Cmdlets other than Get-Command’s –PSSnapin parameter is now an alias to a –Module parameter. This reflects the move away from administrator-installed snap-ins, and towards the friendlier Module system. For all intents and purposes, you can treat v1 snapins as modules as load them as such with the Import-Module Cmdlet.

New Cmdlets

Here are the new Cmdlets, sorted by noun and alongside the textual synopsis is one is present in the CTP3 help, or the syntax if there is no help. The command I ran to generate this was:

Whew, that’s quite a few. Now, onto the API.

.NET API Differences

This time, I’m just dumping out the namespaces and Types per namespace. It would be a bit much to dump out all the Types themselves. The one-liner:

Here are the namspaces and respective public Type count for v1.0:

v2.0 CTP3 API

Here are the namspaces and respective public Type count for v2.0 CTP3:

As you can see, there has been a nice expansion of namespaces and Types to work with, mostly coming from the sterling work being done to generalize the “Jobs” infrastructure. Also, a fair chunk is tied up with the refactoring and reorganizing of Runspaces to allow for jobs (which also covers eventing), remoting and background pipelines. This is something I will cover in more detail in a future post.

Have fun!

You might have noticed these two accelerators in the list I published recently along with the technique how to add your own type accelerators. It’s not immediately clear that they are related, but they very much are. This is going to be a fairly developer-oriented post, so there won’t be any hand-holding here.

[PowerShell]

The [PowerShell] accelerator is aliased to System.Management.Automation.PowerShell. It has one static method, Create(), which returns an instance of the class itself. In v1, if you wanted to set up asynchronous pipelines and do other fancy stuff, you had to get your hands dirty with Runspace and Pipeline instances and know how to wire them all together. The [PowerShell] class makes it a lot easier to do this; think of it a “PowerShell Pipeline Runner” class. At its simplest, you can just “new up” an instance, assign some script using the AddScript method and call Invoke(). You can run this asynchronously using the BeginInvoke/EndInvoke pattern which should be familiar to all .NET developers who’ve done a bit of threading work.

[RunspaceFactory]

This accelerator is aliased to System.Management.Automation.Runspaces.RunspaceFactory. It has two static methods of interest, CreateRunspace and CreateRunspacePool. I’m going to focus on the latter because it has more interesting uses which you will see. This latter method lets you create a collection of Runspace instances that are essentially reusable. The great thing is that you don’t have to worry about any of the details. It just works; this leads me to the next part: queuing local pipeline jobs to be run in the background.

The pool you create can be constrained in many ways by using the various overloads of the CreateRunspacePool. You can even pass it a RunspaceConnectionInfo object so that the queued pipelines are run on remote servers. This is done by using the New-PSSession cmdlet to create a session to a remote machine running PowerShell 2.0 with WinRM configured correctly.

Queueing Pipelines to a Runspace Pool

This is where the magic really happens. Simply new up a PowerShell instance, assign the pool to it and run a command. New up as many PowerShell instnaces as you like, and as long as you assign each of them the same pool, the pool automagically looks after processing them as fast as it can and will never go over its hard limits you give it for the number of simultaneous runspaces. In this next script, I set up a pool of three runspaces. I then queue up six pipelines to be run. I am using the BeginInvoke method to start the command in the background. You’ll see when it runs that each command will make a beep of a certain frequency when it finally starts up. You can hear the first three jobs start up pretty much straight away, as each completes, another starts up. Magic!

Feel free to post questions or requests for clarification, but I did say it was a bit tough and developer-oriented. I have a hint that our good friend and fellow MVP, Karl Prosser (aka Klumsy), will be wrapping up some of this stuff into some nice admin-oriented background  command functions.

IMPORTANT:

Due to the WaitAll call at line 40, this script will not work in an STA thread (i.e. in PowerShell ISE). Use PowerShell.EXE to run this script. Everything else will work in ISE fine.

Have fun!

Meson tweeted a request asking if it was possible to get a list of language keywords from PowerShell itself. The answer is officially “No,” but like most things of this nature, there’s always a sneaky way:

More interestingly this list turned up a new script keyword, dynamicparam. I haven’t seen it in action yet but it sounds like another “advanced function” feature to bring functions and cmdlets closer to parity. I may need to add another article to my dynamic parameter series ;-)

This is an interesting exercise to show the power of PowerShell’s language to explore and manipulate object models, specifically its own. You all should be familiar with Type Accelerators: The short name syntax for accessing commonly used .NET Types. An example would be [wmi] – this is the same as typing [System.Management.ManagementObject]. So, how can we find all of the current existing Type Accelerators? Well, after cracking open PowerShell with our favourite decompilation tool, Reflector, the class in question is System.Management.Automation.TypeAccelerators. Here’s what it looks like:

Interestingly, the methods that let you add and remove your own accelerators are marked Public. The Type itself is internal, but the dictionary named “userTypeAccelerators” is positively tantalizing. It looks like perhaps the team have plans to let people add their own accelerators! Then again, this is a CTP, and this may change in the future. Well, let’s see if we can finish off what the team half started ;-)

First thing we need to do is get a reference to the internal class. The C# heads amongst you will start thinking about using reflection to get your hands on the type, but actually there’s an easier way. PowerShell’s language is incredibly flexible and through sneakiness, you can use System.Type’s GetType method to invoke any public method without reverting to tricky reflection calls. First of all, lets add our own user-defined Type Accelerator which is aliased to this internal class itself:

I’ve split the Type retrieval and Add methods into two lines for brevity. The parser is actually flexible enough to understand the more pithy ([type]::gettype("System.Management.Automation.TypeAccelerators"))::Add(…).

So what do we have in CTP3?

Btw, I generated the above list with this one liner:

Have fun!

Just to be completely silly, I thought I’d do a series of posts on CTP3 features themed around Christmas. Hmm. That might read better as a series of Christmas posts themed around CTP3. A very original idea I’m sure, but hey, those who know me will know that I never pass up the opportunity to make a bad joke. So, without further adieu:

On the first day of Christmas, Jeffrey gave to me:

Nested Here-Strings

Here-Strings can now be embedded within each other to make it even easier to construct literal documents! Delimit any nested code between $( and ) and then continue to use a nested string within that as if it was completely stand alone. It just works! Cool, eh?

To quote the completely understated download blurb:

Windows PowerShell V2 CTP3 introduces several significant features to Windows PowerShell 1.0 and Windows PowerShell V2 CTPs that extends its use, improves its usability, and allows you to control and manage the Windows environment more easily and comprehensively.

The release notes are quite extensive. Here is the section on breaking changes from CTP2:

Breaking Changes to Windows PowerShell V2 (CTP2)

The following changes in Windows PowerShell V2.0 CTP3 might prevent features designed for Windows PowerShell 2.0 CTP2 from working correctly.

• Following cmdlets have been renamed
  • Add-Module to Import-Module
  • Get-Event to Get-WinEvent
  • *-Runspace to *-PSSession
  • Push-Runspace to Enter-PSSession
  • Pop-Runspace to Exit-PSSession
  • *-PSEvent to *-Event
  • Register-PSEvent to Register-EngineEvent
  • *-PSTransaction to *-Transaction
  • *-PSJob to *-Job
  • *-PSEventSubscriber to *-EventSubscriber
  • *-Bite to *-FileTransfer

• Following parameters have been renamed
  • Import-LocalizedData: Culture to UICulture
  • Invoke-Command: Runspace to Session, Shell to ConfigurationName
  • Get-Job: SessionId to Id
  • Receive-Job: Runspace to Session, SessionId to Id
  • Remove-Job: SessionId to Id
  • Start-Job: Command to Scriptblock
  • Stop-Job: SessionId to Id
  • Wait-Job: SessionId to Id
  • Get-PSSession: RemoteRunspaceID to InstanceId, SessionId to Id
  • New-PSSession: Runspace to Session, Shell to ConfigurationName
  • Enter-PSSession: Runspace to Session, RemoteRunspaceID to InstanceId, SessionId to Id, Shell to ConfigurationName
  • Remove-PSSession: Runspace to Session, RemoteRunspaceID to InstanceId, SessionId to Id

• Following parameters have been deleted
  • Export-ModuleMember: Update, ExportList
  • Set-Service: Include, Exclude

• Following variables have been renamed
  • $CommandLineParameters to $PSBoundParameters
  • $PSPackagePath to $PSModulePath

• Packages have been renamed to Modules. Packages folder is now renamed to Modules folder. A module imported into another module is now treated as a nested module instead of a peer module. This allows a new module to wrap or repackage one or more existing modules.

• "Script cmdlets" have been renamed to "advanced functions." The “cmdlet” keyword has been replaced with the “function” keyword.For script cmdlet functionality, use CmdletBinding attribute in the function’s param block. For more information, see about_functions_advanced.

• The Config-WSMan.ps1 script in the $pshome directory has been replaced by the Enable-PSRemoting function. To configure your system for WS-Management remoting, use the following command:

Enable-PSRemoting –force

Note: If you have upgraded from the Windows PowerShell V2 CTP2 release to the Windows PowerShell V2 CTP3 release, to configure your system for WS-Management remoting, type:

Unregister-PSSessionConfiguration * -force;

Register-PSSessionConfiguration Microsoft.PowerShell –force;

Enable-PSRemoting –force

• In the Out-GridView cmdlet, the drop-down list used to filter objects is now called “Query” instead of “Filter”.

• The following changes have been made to Windows PowerShell Integrated Scripting Environment (ISE):

• The name of the application has changed from “Graphical Windows PowerShell” to “Windows PowerShell Integrated Scripting Environment (ISE)”
• The executable name has changed from “gpowershell.exe” to “powershell_ise.exe”
• The profile name has changed from “\Users\<username>\Documents\WindowsPowerShell\Microsoft.GPowerShell_profile.ps1” to “\Users\<username>\Documents\WindowsPowerShell\Microsoft.PowerShellISE_profile.ps1”
• The term “runspace” has been replaced with “PowerShell tab”.

Get it from http://www.microsoft.com/downloads/details.aspx?FamilyID=c913aeab-d7b4-4bb1-a958-ee6d7fe307bc – piping hot!

This time around, I thought I’d show how to work with programmatically generated dynamic parameters, as opposed to the statically defined sets we saw the last time. The context here is a fairly silly Cmdlet, but it’s good enough to demonstrate the concept end to end. It’s a Cmdlet for removing a file. It takes one string parameter which is the path to the file. The dynamic parameter I’m going to add is a –Force parameter. The trick is, this parameter will only be added if the current user is an administrator (XP), or is elevated as one (Vista).

This first portion of the Cmdlet defines the usual stuff like a verb and noun. This time though, I’m using a regular class constructor. It’s not often you see constructors in simple Cmdlets because typically all one would usually do is override one or more of the three processing methods BeginProcessing, ProcessRecord and EndProcessing. In this case, I need to create a instance of a “RuntimeDefinedParameterDictionary,” which does exactly what it says on the tin. It’s a dictionary of parameters, the key being a string (the name of the parameter) and the value being a instance of a RuntimeDefinedParameter class. These classes are all members of the System.Management.Automation namespace.

In the constructor, I’m calling a generic method defined as AddDynamicParameter<T>(string name). This is only called if the current user is an admin. I’ve defined three generic helper methods which you can see a little further down below.

This is a simple piece of code who’s role is to remove the file specified by the user. I’ve omitted the actual code that would delete the file for brevity. I’m using another helper method to see if the –Force parameter has been added to the Cmdlet’s definition, and if so, was it specified by the invoker of the Cmdlet. The idea is here is that the Cmdlet will not remove the file if it’s marked Read-Only, but if –Force is specified it will remove the R/O attribute and continue as planned.

And the final piece is here. The first method GetDynamicParameters, belongs to the IDynamicParameters interface and tells PowerShell that the Cmdlet may return extra parameters not defined on the class itself. In this case, we are returning a RuntimeDefinedParameterDictionary instead of a statically defined parameters on a nested class.

Finally, the three helper methods are revealed. One is used for checking for dynamic SwitchParameters, the next is for ordinary parameters that return type T, the generic argument. The third method, TryGetDynamicParameter is used by the first two methods.

I hope this helps reveal some of the mystery behind dynamic parameters on Cmdlets. There is one more type of dynamic parameter that I will be examining in one of my next few posts, that is the scenario where a provider (like the FileSystemProvider or RegistryProvider) passes a dynamic parameter to a Cmdlet. In this particular case, the provider can only pass dynamic parameters to the built-in Cmdlets that operate on providers, e.g. Get-ChildItem, Get-Item, Get-ItemProperty etc.

Have fun!

The dynamic duo / masterminds of PowerShell will be cornered and fiercely grilled by none other than our very own master podcaster, Hal Rottenberg this Thursday.  From the mouth of the suffixed one himself:

Coming up on the PowerScripting Live show this Thursday will be Jeffrey Snover,
the architect for PowerShell as I’m sure you all know, and he’ll be accompanied
by none other than Bruce Payette, author of PowerShell in Action and a core
developer on the PowerShell team.

We’re excited and we hope you can make it this Thursday at 9pm EST!

The live stream address is http://www.ustream.tv/channel/powerscripting-podcast

So if you want to get the lowdown on CTP3 (maybe), join us, the unwashed masses as we clamour to be near our idols. A lock of their hair and a signed discarded printout of directions to building 18 could be yours!

I made that last bit up. Who cares! This is going to be cool! Join us!

Now this is cool. I’ve always wanted to try out TDD, but as I’m primarily a SharePoint developer, a lot of the time my code is written on my laptop running XP, so I can’t actually test anything since SharePoint won’t install there. The folks at Bamboo Solutions came up with some clever hacks to get WSS 3.0 and MOSS running on Vista, but it’s a bit of a heavyweight solution, especially when you consider this:

Typemock are offering their new product for unit testing SharePoint called Isolator For SharePoint, for a special introduction price. it is the only tool that allows you to unit test SharePoint without a SharePoint server. To learn more click here.

The first 50 bloggers who blog this text in their blog and tell us about it, will get a Full Isolator license, Free. for rules and info click here .

Unfortunately the competition is actually over, but it’s still worth a peek!

Normally parameters for a Cmdlet are defined directly as properties on the Cmdlet class itself. There are a few other ways for a Cmdlet to define parameters, and in this short series of three parts, I’ll cover the three variants you’ll likely to encounter as you become a more experienced PowerShell developer. First thing you need to do is to implement the System.Management.Automation.IDynamicParameters interface on your Cmdlet. This interface has one member, GetDynamicParameters. This interface can be implemented on either a Provider or a Cmdlet. In the former case, a provider is able to add new parameters at runtime to certain built-in Cmdlets like Get-ChildItem, Get-Item & Get-ItemProperty. It is typically used in a path context-aware manner – e.g. depending on whether the current argument is a folder or item, and what Type such a folder or item might be. We’re just to cover the Cmdlet variant in this post.

My example is just a simple Cmdlet named Get-OSVersion. It writes out Environment.OSVersion to the pipeline, and will dynamically add a parameter. It adds –EnsureElevated if you’re running Vista or higher, otherwise it will add –EnsureAdministrator. Statically defined dynamic parameter sets are defined by creating a simple class and decorating that class with parameter/properties you want to surface as if that class was the Cmdlet itself, then returning it from the GetDynamicProperties method at runtime. Simple!

Of course, adding Dynamic Parameters is no good if you don’t know how to read them back. In the code, you can see I’m using MyInvocation.BoundParameters to check if the Switches have been set.

It seems lots of people are catching the PowerShell bug these days. People who previously considered themselves as administrators have learned enough of the magic from using PowerShell from day to day over the last few months that they feel comfortable enough to tinker around with C#.

This is an example Cmdlet skeleton that is designed to work with Files and Directories. It looks after resolving wildcards, supports –WhatIf and –Confirm, accepting files and/or directories from the pipeline or accepting strings of paths from the pipeine. It also ensures that the only types of paths it can accept lie on the File System. Here’s an example of the invocation styles it supports:

Here’s the source code for this. It doesn’t really do a lot. It spits out two different types of custom objects: one for a file, and another for a directory. Feel free to do what you like with it; it’s yours. Have fun.

          
            using System; 
          
            using System.Collections.Generic; 
          
            using System.IO; 
          
          
          
            using System.Management.Automation; 
          
            using Microsoft.PowerShell.Commands; 
          
          
          
            namespace PSQuickStart 
          
{

          
    [Cmdlet(VerbsCommon.Get, Noun,

          
        DefaultParameterSetName = ParmamSetPath,

          
        SupportsShouldProcess = true) 
          
    ]

          
            public
            class GetFileMetadataCommand
: PSCmdlet 
          
    {

          
            private
            const
            string Noun
= "FileMetadata"; 
          
            private
            const
            string ParamSetLiteral
= "Literal"; 
          
            private
            const
            string ParmamSetPath
= "Path"; 
          
          
          
            private
            string[]
_paths; 
          
            private
            bool _shouldExpandWildcards; 
          
          
          
        [Parameter(

          
            Position = 0,

          
            Mandatory = true, 
          
            ValueFromPipeline = false, 
          
            ValueFromPipelineByPropertyName = true, 
          
            ParameterSetName = ParamSetLiteral)

          
        ]

          
        [Alias("PSPath")] 
          
        [ValidateNotNullOrEmpty]

          
            public
            string[]
LiteralPath 
          
        {

          
            get { return _paths;
} 
          
            set {
_paths = value; } 
          
        }

          
          
          
        [Parameter(

          
            Position = 0,

          
            Mandatory = true, 
          
            ValueFromPipeline = true, 
          
            ValueFromPipelineByPropertyName = true, 
          
            ParameterSetName = ParmamSetPath)

          
        ]

          
        [ValidateNotNullOrEmpty]

          
            public
            string[]
Path 
          
        {

          
            get { return _paths;
} 
          
            set
          
          
            {

          
                _shouldExpandWildcards = true; 
          
                _paths = value; 
          
            }

          
        }

          
          
          
            protected
            override
            void ProcessRecord() 
          
        {

          
            foreach (string path in _paths) 
          
            {

          
            //
This will hold information about the provider containing
          
          
            //
the items that this path string might resolve to. 
          
          
                ProviderInfo provider;

          
          
          
            //
This will be used by the method that processes literal paths
          
          
                PSDriveInfo drive;

          
          
          
            //
this contains the paths to process for this iteration of the
          
          
            //
loop to resolve and optionally expand wildcards.
          
          
                List<string>
filePaths = new List<string>(); 
          
          
          
            if (_shouldExpandWildcards) 
          
                {

          
            //
Turn *.txt into foo.txt,foo2.txt etc.
          
          
            //
if path is just "foo.txt," it will return unchanged.
          
          
                    filePaths.AddRange(this.GetResolvedProviderPathFromPSPath(path, out provider)); 
          
                }

          
            else
          
          
                {

          
            //
no wildcards, so don't try to expand any * or ? symbols. 
          
          
                    filePaths.Add(this.SessionState.Path.GetUnresolvedProviderPathFromPSPath( 
          
                        path, out provider, out drive)); 
          
                }

          
          
          
            //
ensure that this path (or set of paths after wildcard expansion)
          
          
            //
is on the filesystem. A wildcard can never expand to span multiple
          
          
            //
providers.
          
          
            if (IsFileSystemPath(provider,
path) == false) 
          
                {

          
            //
no, so skip to next path in _paths.
          
          
            continue; 
          
                }

          
          
          
            //
at this point, we have a list of paths on the filesystem.
          
          
            foreach (string filePath in filePaths) 
          
                {

          
                    PSObject custom;

          
          
          
            //
If -whatif was supplied, do not perform the actions
          
          
            //
inside this "if" statement; only show the message.
          
          
            //
          
          
            //
This block also supports the -confirm switch, where
          
          
            //
you will be asked if you want to perform the action
          
          
            //
"get metadata" on target: foo.txt
          
          
          
          
            if (ShouldProcess(filePath,
"Get Metadata")) 
          
                    {

          
            if (Directory.Exists(filePath)) 
          
                        {

          
                            custom = GetDirectoryCustomObject(new DirectoryInfo(filePath)); 
          
                        }

          
            else
          
          
                        {

          
                            custom = GetFileCustomObject(new FileInfo(filePath)); 
          
                        }

          
                        WriteObject(custom);

          
                    }

          
                }

          
            }

          
        }

          
          
          
            private PSObject
GetFileCustomObject(FileInfo file) 
          
        {

          
            //
this message will be shown if the -verbose switch is given
          
          
            WriteVerbose("GetFileCustomObject "
+ file); 
          
          
          
            //
create a custom object with a few properties
          
          
            PSObject custom = new PSObject(); 
          
          
          
            custom.Properties.Add(new PSNoteProperty("Size",
file.Length)); 
          
            custom.Properties.Add(new PSNoteProperty("Name",
file.Name)); 
          
            custom.Properties.Add(new PSNoteProperty("Extension",
file.Extension)); 
          
          
          
            return custom; 
          
        }

          
          
          
            private PSObject
GetDirectoryCustomObject(DirectoryInfo dir) 
          
        {

          
            //
this message will be shown if the -verbose switch is given
          
          
            WriteVerbose("GetDirectoryCustomObject "
+ dir); 
          
          
          
            //
create a custom object with a few properties
          
          
            PSObject custom = new PSObject(); 
          
          
          
            int files
= dir.GetFiles().Length; 
          
            int subdirs
= dir.GetDirectories().Length; 
          
          
          
            custom.Properties.Add(new PSNoteProperty("Files",
files)); 
          
            custom.Properties.Add(new PSNoteProperty("Subdirectories",
subdirs)); 
          
            custom.Properties.Add(new PSNoteProperty("Name",
dir.Name)); 
          
          
          
            return custom; 
          
        }

          
          
          
            private
            bool IsFileSystemPath(ProviderInfo
provider, string path) 
          
        {

          
            bool isFileSystem
= true; 
          
          
          
            //
check that this provider is the filesystem
          
          
            if (provider.ImplementingType
!= typeof(FileSystemProvider)) 
          
            {

          
            //
create a .NET exception wrapping our error text
          
          
                ArgumentException ex = new ArgumentException(path
+ 
          
                    " does
not resolve to a path on the FileSystem provider."); 
          
          
          
            //
wrap this in a powershell errorrecord
          
          
                ErrorRecord error = new ErrorRecord(ex,
"InvalidProvider", 
          
                    ErrorCategory.InvalidArgument, path);

          
          
          
            //
write a non-terminating error to pipeline
          
          
            this.WriteError(error); 
          
          
          
            //
tell our caller that the item was not on the filesystem
          
          
                isFileSystem = false; 
          
            }

          
          
          
            return isFileSystem; 
          
        }

          
    }

          
}

          
          
        

Here’s just a quick rundown of the changes in PowerShell 2.0 in comparison to the last public release, CTP2. This may be helpful to those of you who don’t have access to the Windows 7 PDC bits. Remember, things are still subject to change - it’s not in beta yet.

Unchanged cmdlets are not listed here.

* e.g. The *-Runspace Cmdlets have been renamed to *-PSSession

I’d say a lot of folks will be chomping at the bit for this. It’s the Tk to PowerShell’s Tcl and is really the final piece of the puzzle where the shell’s position as the de-facto Windows Shell stands anyway. Well, maybe Remoting support for XP and Windows Server 2003 is ahead there just a bit, but a forms designer must be a close second.

Check it out: http://blog.sapien.com/index.php/2008/11/03/free-primalforms-tool-for-powershell-released/

Congratulations guys on shipping such a fine tool, for FREE. All it costs you is an email address. Yah, sell your soul, it’ll be worth it.

I’ve been performing the “resolution” listed in this article since I first discovered the problem, but never ever did I think it was a “feature?” I was sure that I was just the unluckiest person alive and was always working with some dodgy permissions configuration of the 12 hive, but lo and behold, no. This is just the way it’s meant to be.

Anyone else think this is just pure madness? By default any forms you create in Visual Studio have a managed component. Hitting F5 to run deploy/debug won’t ever do the work for you either. Why isn’t this mentioned anywhere in any sort of official capacity? Anybody?

Managed code may not be executed if an InfoPath 2007 workflow form is deployed as a feature for a workflow

SYMPTOMS

Consider the following scenario. A Microsoft Office InfoPath 2007 workflow form contains managed code. The form is deployed as a feature for a workflow. In this scenario, the managed code may not be executed.

CAUSE

This issue occurs because a compiled DLL becomes part of the InfoPath form template (XSN) file when you create managed code behind an InfoPath form. Microsoft Office Forms Services does not extract a DLL by expanding the XSN file when the XSN file is installed by using the features functionality.

RESOLUTION

To resolve this issue, copy the compiled DLL to the same folder to which your feature XSN file was deployed.

http://support.microsoft.com/kb/930894/en-us

One thing I’ve noticed about the SharePoint callback-based Activities in Workflow is that they are extremely flakey if you try to reference the member variable reference for the owning Activity directly instead of casting the “sender” argument in the event handler itself. You have a SharePoint SetState Activity, for exmaple, along with the corresponding MethodInvoking hook and I don’t mean the State Machine transition Activity, but rather the SharePoint-specific Activity that lets you override the Workflow’s overall state string using the <ExtendedStatusColumnValues> metadata in Workflow.xml. In my case, I use the MySetState_MethodInvoking hook to set the state at runtime depending on several conditions. If I try to set properties on the workflow's MySetState member variable directly like this:

            private
            void MySetState_MethodInvoking(object sender,
EventArgs e) {

            this.MySetState.State = SPWorkflowStatus.Max
+ 2;

}

This just plainly doesn’t work reliably. It doesn’t throw any exceptions, in fact it looks to work just fine, except the state is not changed. The same seems to go for any other of the SharePoint interfaces that involve callbacks. In my experience, they just don’t work most of the time especially if the workflow dehydrates before the callback is invoked. This leads me to think that there are some quirky interactions going on internally that somehow cause the workflow to ignore your attempts to change anything, perhaps due to the workflow getting rehydrated after you have made the changes, or who knows. All I know is that if you want this stuff to work reliably, ALWAYS CAST THE SENDER to your target Activity before attempting to manipulate the owning Activity. Using the member variable is just flakey. If anyone has any information on this, let me know. This works reliably:

          private vid MySetState_MethodInvoking(object sender,
EventArgs e) { ((SetState)sender).State = SPWorkflowStatus.Max + 2; }

Anyway, have fun.

Fellow PowerShell MVP and developer all-round expert administrator Brandon Shell asked me how he could navigate to a Cmdlet’s implementation in Lutz Roeder’s Reflector -- which has now been acquired by Red-Gate Software btw. At first I was going to explain to him how snap-ins work and how to figure out where things are, and then a really simple trick hit me that uses some fairly secret command-line parameter that Reflector can accept, namely the /select parameter:

Just pipe the output of get-command to it, like: gcm dir | reflect-cmdlet and Reflector will open up with the class selected (it takes a few seconds).

Update: Doug pointed out in a comment that the gcm reflector.exe line could benefit from an erroraction to keep it silent on failure, so only the throw message shows. Thanks Doug!

The verbs list for naming your Cmdlets is pretty strict. You should definitely try to pick one of the known verbs. You can see them here:

function Get-Verb {
    [psobject].assembly.getexportedtypes() | `
        ? {$_.name -like "Verbs*"} | gm -static -membertype property | `
        sort Name | select Name
}

ps> Get-Verb

The noun end of the spectrum is pretty open-ended. Single nouns are better, and try to use the singular if you can. Cmdlets typically return one or more objects. so the singular form is the convention - better than trying to name your Cmdlet "Get-Noun(s)" which is just plain silly.

To prefix or not to prefix: this is a sticky one. The Religious Right, aka the Microsoft Powershell team, dictate that you should not prefix. The reality is more complicated and is under constant debate. If you pick a verb-noun pair that already exists and is currently loaded into powershell, you must disambiguate the command with the snapin name (snapinname\verb-noun) or it won't run. The snapin name is typically long and ugly. A noun prefix is typically short and sweet. The problem with the latter is that your commands are now harder to discover for someone who doesn't know they are there (and as such doesn't know your magic prefix). Ultimately though, people load your snapin explicitly and should know the prefix, so I tend to lean towards this although I feel a strong connection with the "One Noun Way."

(taken from one of my newgroup posts)

This is just a post containing all the issues I’ve run into over the last six months while working with MOSS Workflows, InfoPath and Visual Studio 2008/VSTO 3.0. I’ve been using these tools in this combination for a while now, but it’s only the last six months where I decided to take a note every time I ran into something. Don’t get me wrong though. This is more of a post aimed at helping others in their quest for abdominal hull-integrity while working with these tools, not attacking the toolset. Ultimately, the Office Suite and the corresponding tools are working together better than ever before, but unfortunately with large teams working relatively independently you’re just going to get these kind of problems. To be brutally honest, I think VSTO 3.0 is a saddle-sore on the otherwise supple and leathery hide of Visual Studio 2008 and the disparity in their respective product quality is way too pronounced to be ignored.

Anyway, I’m not going to make much attempt to explain each case for non-SharePoint people, but if you’re involved in this area, you’ll know where I’m coming from. The following list contains Glitches and Gotchas.

Glitches

First though, the Glitches, in no particular order. These are the lovingly hand-crafted defects and “product quality issues” that will first cause your stomach muscles to contract somewhat, then violently spasm so hard that that first loop of intestine will pop out to nestle amongst the fat cells and veins in the fleshy meadow of your lower-epidermis. Don’t say I didn’t warn you.

Publish an Installable Form Template (requires Visual Studio)

If you try to publish a form as "an installable template (requires visual studio)" from within Visual Studio 2008 (even with sp1), VSTO, in its infinite wisdom tries to use visual studio 2005 devenv.exe executable to do it! And it fails spectacularly 'cos it's not installed, or if it is installed it's part of some vs-shell install for some other office app like office macros IDE, or Internet Explorer’s “script debugger” shell for example.

Publishing a Form to an explicitly-included Managed Path

Trying to publish a form to a SiteCollection sitting on an explicitly-included managed path fails with "getting the site content type columns failed." Workaround? Don’t publish forms to Managed Paths. It’s b0rked.

“An exception occurred during loading of business logic” - Publishing XSNs with CodeBehind to SharePoint

If you perform a cursory search for the title, you’ll find lots of herniated VSTO users having issues with this. InfoPath Forms Services on MOSS Enterprise is a fickle beast; a beast that will have you tucking those intestinal loops back into your torso with a pencil before you can say “FileNotFoundException, whuh?”

XSN files are actually CAB files. When Forms Services loads them up to be rendered into Browser Forms, it has to load the embedded DLL into memory. It has an extremely hard time doing this sometimes. Particularly when you store your XSN files in a subdirectory under your workflow feature, say like one called Forms. It appears that the form loads ok, but Forms Services is looking for the DLL in the root of your feature. Even sometimes if you have the XSN in the root of your feature, it still won’t find and extract/load the embedded DLL. The only way to avoid this it appears is to manually extract the DLL and place it in the root of the feature yourself after you have deployed the workflow solution.

Some strange things I’ve observed about Forms Services on MOSS Enterprise:

• Uploading a codebehind-XSN  file via central admin automatically extracts dll/pdb into feature directory but...
• Deploying a codebehind-XSN with  workflow feature does not extract dll/pdb.
• Upgrading a codebehind-XSN with central admin creates new subdir in feature folder, modifies feature.xml to point to it but does not extract the form's codebehind dll/pdb into new subdir either.

These seem to be some rather serious looking issues to me.

VSTO Designer ToolPane Content Shrinks

Occasionally the Design ToolPane in VS2008/VSTO inexplicably changes size, with the contents of it being set at about 1cm wide.

Workflow Designer Screws Up Layout of Nested States

The workflow designer in VS 2008 (even sp1) will screw up the formatting of nested states in a state machine workflow - they get randomly offset to the left or right so they are half occluded by the containing state. Yay.

Views ToolPane Is Blank For a Form that has Views

Views created in infopath sometimes do not appear in vs2008 project built around that imported XSN. Weirdly, the toolpane is completely white/blank. A restart of Visual Studio or close/reopen of the project usually fixes this.

Manipulating Files In “InfoPath Form Template” Project Folder Is a Bad Idea

Deleting/modifying/renaming a file in the "infopath form template" meta-folder in Visual Studio 2008 does not fix the reference in the manifest.xsf file. The form is then impossible to open until you fix the references within the manifest by closing the form designer and opening the XSF with the XML handler through a right-click. Why does VSTO even let you modify embedded resources if it won’t update the manifest for you?

The magical secondary DataSource ItemMetadata.xml

The secondary DataSource (for receive data) ItemMetadata.xml has _two_ ways of being added as a resource - the second way (prompted at end of import). You can either add it as a resource when you initially point VSTO/InfoPath at it, or if you don’t do it then you get a second chance at the end of import to add it as a resource. This is confusing.

Converting an embedded DataSource to site-relative format and placing into a  Data Connection Library can leave the required field "Title" empty

This enforces the UDCX files to be permanently checked out - trying to update the title field by hand does not work - it remains blank at every attempt to change it when done directly or via bulk edit DataGrid view. It sometimes exclaims that the files are checked out to another user even though they are plainly checked out to me. Worst of all, only *I* can use the InfoPath form that uses this DataSource so it’s starts out a looking like “it works for me” issue.  Anyone else cannot use the form - DataSource loading fails - ULS log says "root element is missing" - after much debugging, it appears that anyone (apart from me the author) attempting to download the UDCX file gets a 0 length file - you can test this by getting the poor user to try to download the UDCX from the connection library. This is because only an author of a checked-out file can read it. 

Hacky Fix: Remove ReadOnly attribute from the list-level UDCX content type and mark the Title column as optional, then check-in the connections. Title be damned!

This all started when I enabled Versioning for the connection library before converting my data sources. Not sure if that’s relevant.

BDC randomly losing ServerContext while inside Event Receiver triggered from Workflow context

The TLS slot for the resource provider SqlSessionProvider sometimes ends up being null on the Event Receiver's thread. If you’re not following me, you probably don’t need to understand this any further.

Gotchas

These are not so much glitches are they are things that can trip you up and/or be considered “non-obvious” behavioural quirks. While they may give you an upset tummy, you are not going to be trussed up in a Spigelian torso-bangle any time soon.

A Workflow Continually Spawns New Instances of Itself

When you have a workflow added to a document library and the workflow updates the list item when it is running, a new workflow will spawn once the .Update() method is executed on the list item. To update the item without having a new worklfow started, use .SystemUpdate(). Duh.

"The database returns an error. Failed to enable constraints." When InfoPath DataBinds

Changing the query directly in a UDCX file inside a data connection library may cause "The database returns an error. Failed to enable constraints. One or more rows contain values violating non-null, unique, or foreign-key constraints" errors from live InfoPath forms because the data source schema in InfoPath no longer matches (especially if you increase the length of a returned field) - after you change the UDCX, you must go through the "manage data connections" and choose "modify" for that connection and go through the wizard without changing anything. This will cause InfoPath to re-sync the schema.

How The Hell Can I Render The Form Version On The Form Itself?

Tip: insert form version with the expression: substring-before( substring-after( /processing-instruction()[local-name(.) = "mso-infoPathSolution"], 'solutionVersion="'), '"')

I can’t remember where I got this, I didn’t write it myself. Thanks to the original author.

Why Can’t SharePoint Find My Forms for my Workflow?

The Form URN will change if you don't name your form exactly as you did (e.g. accept the default) in "file > form properties" when publishing it with the publishing wizard.

Why Can’t My Workflow Forms Find My Data Connections?

Site relative data connections stored in a data connection library work fine for InfoPath published forms bound to a content type in a site; also form security will stay at domain. But they can’t be found if these same forms are used in a workflow. Use “centrally managed” data connections instead.

Why Does Visual Studio Put Referenced DLLs Bound For the GAC Into My InfoPath XSN?

If you reference other feature projects in the same solution that deploy into GAC, be sure that they exist in the GAC before building the InfoPath project's XSN - if they are not in the GAC, they will be copied into the XSN by default. Duh.

How Do I Uninstall My Workflow I was Debugging In Visual Studio?

Workflow features deployed via vs2008 F5/start debugging have no obvious means of being "undeployed." you must use VSTO 1.0 PowerTools "Feature Sweeper" to remove it; this is a dependency for workflow forms registered in central admin.

Why Are The TaskProperties Hashtables So Weird?

ExtendedProperties Hashtables leaves root XML fields as keys, and nested xml as my:schema formatted XML for Hashtable values. Strangely, the Workflow API has a public XmlToHashtable method on a utility class, but not the inverse to pull it back out of ExtendedProperties. Duh.

Where The Hell Did The Form Publish Menu Disappear to?

You cannot publish the InfoPath form unless you have the designer open, even though you can only have one form per project and you might just have a single project in the solution. This is annoying when your forms are large and sluggish to open.

Why do some VS SharePoint Activities have a User (string) property and others a UserID (int) property?

I wish I knew. This is just another silly design (in)decision. All SPUsers in SharePoint have both a Login (string) and a PrincipalID (int). If you want to set the Logging Activity’s UserId (int) to the id of a person who performed a Workflow Modification User (string), you have to convert, persist and expose these properties yourselves before you can bind to an activity using the designer. Duh.

I use a method like this:

Why is Visual Studio 2008  SP1’s Workflow Designer Host still such a dog?

You and thousands of other people would love to know the answer. IMHO, it’s too complex to have been written in Managed Code (e.g. C#). It should have been native C++ from day one. All that synchronizing intellisense, XOML and the visual designer is just too much for it. God help you if you throw in any real-time refactoring tools on top of that.

Summary

Despite all this moaning, SharePoint in conjunction with Visual Studio 2008 is a powerful combination. Nothing to be sniffed at all; I actually love it (most of the time.)

Have fun.

Resharper (or R#) is an absolute gem of a tool. After using it for a year, I really don’t know how I got along without before. If you write code in .NET (C# or VB.NET), you owe it to yourself to try it out. Version 4.0 was the first to support C# 3.0:

ReSharper 4 Full Edition and C# Edition extend language support to C# 3.0, including LINQ, implicitly typed locals and arrays, extension methods, automatic properties, lambda expressions, object & collection initializers, anonymous types, expression trees, and partial methods. ReSharper not only analyzes the new constructs, but provides C# 3.0-related enhancements in a number of areas — specifically, warnings, suggestions, code completion options, refactorings, and templates.

The guys at Jetbrains just released versus 4.1. They offer a free thirty-day trial over at http://www.jetbrains.com/resharper/ – do it!

Are you sick and tired of switching the VMWare virtual network adapters from the “public” network profile to a “private” network profile each time you reboot or do something else that causes Vista/Win2008 to forget what you told it to do ten minutes ago? This is probably a familiar sigh (I’m using Workstation):

As you can see, the lower two connections are seen to be in a “Public network.” This has the net effect of making Windows believe the whole machine is exposed to a public network, and it will trigger the public profile for Windows Firewall. This is normally a good thing, but in this case it’s just an annoyance. These two network connections are not actually external gateways that can let in the bad guys. They are just dummy adapters for VMWare’s host bridging which allow the virtual machine to access the host machine’s network. Because they don’t identify themselves properly, they are flagged as an “unidentified network,” and your changes are never persisted.

So what do you do? The magic information is buried in MSDN:

Vista automatically identifies and monitors the networks to which a computer connects. If the NDIS_DEVICE_TYPE_ENDPOINT flag is set, the device is an endpoint device and is not a connection to a true external network. Consequently, Windows ignores the endpoint device when Windows identifies networks. The Network Awareness APIs indicate that the device does not connect the computer to a network. For end users in this situation, the Network and Sharing Center and the network icon in the notification area do not show the NDIS endpoint device as connected. However, the connection is shown in the Network Connections Folder. Also, if NDIS_DEVICE_TYPE_ENDPOINT is set, the Windows Firewall ignores the connection when Windows Firewall enforces public, private, or domain policies.

So I hacked together a PowerShell script that will scan your adapters for VMWare’s virtual NICs and make the necessary registry changes. It will also disable/enable cycle the adapters so that the changes take effect. After this is done, you will see them in your Network Connections page – albeit lacking a network category -- and the connections will no longer appear in the Network and Sharing Center nor will they affect your Windows Firewall policy no matter how many times you reboot!

Here’s the script source below. It requires that you run it in an elevated shell in order to write the registry changes and cycle the adapters’ enabled state.

Have fun.

The new eventing infrastructure in PowerShell 2.0 is pretty delicious. You couldn’t do the following in 1.0 without a 3rd party snap-in (like my PSEventing snapin), but now it’s all there at the touch of your fingers. Well, it demands a bit of a sniff around WMI too, but hey, it works well.  With this module, anytime you add or remove a removable device like an external harddrive or USB key, or map a new network drive in explorer, PowerShell will now automatically add or remove a corresponding PSDrive for you.

• Link to PoshCode Copy

This only works PowerShell v2.0 CTP2, and you’ll need to save it as AutoMount.psm1 in a directory under your documents folder like so (vista example):

%userprofile%\documents\windowspowershell\packages\automount\automount.psm1

You can then load it with the command:

ps> add-module automount

I have this in my profile.  You can temporarily disable automount with the function Disable-AutoMount and reenable it at anytime with Enable-AutoMount. The module also exposes four new events for you to consume yourself. You could, for example, hook your own script to run anytime a device is added and/or removed. This is what I do myself in the module. I hook a WMI event once then forward 1 of 4 possible new events depending on the type of WMI event that was raised.

NOTE: this particular flavour of WMI query only works in Vista and Windows 2003 it appears. I’m looking into getting it working with 2000/XP also.

Have fun!

It’s getting harder to post useful scripting tips for PowerShell these days as there aresomanytalentedhardcorescriptingbloggers around. My day to day is job is not system/network/server administrator; I’m a .NET developer, having started the C# habit about eight or nine years ago with the early CLR 1.0 beta. So, from here on in, I’ve decided that a better direction for me to take from now on is that of a PowerShell developer,  as opposed to a scripter. There are very few (if any?) dedicated PowerShell developer blogs around, and so I figured I should try to fill that gap as best I can. I have a not insignificant amount of experience writing providers, cmdlets and other widgety bits, so it’s a good time to share my experiences. Of course, my way is not “the” way, so please reply with your own experiences/advice/mocking/whatever. ;-)

That said, I am not eschewing scripting altogether – I have some stuff in the pipeline (har-har) concerning areas I’m interested in, like eventing and jobs/remoting.

Just a handy tip - you don't have to cast enum types in powershell usually. It will do that for you if that's the only constructor (or method) overload that makes sense:

$accessrule = New-Object system.security.AccessControl.FileSystemAccessRule $userName, `
     "Modify",  "ContainerInherit,ObjectInherit", "None", "Allow"

So when I say "only overload that makes sense," what do I mean by that? Take this method for example which has two overloads (meaning it has two different sets of parameters you could use):

void MyMethod(string a, string b, string c)

void MyMethod(string a, enum b, string c)

If you try to call that method with $o.MyMethod("foo", "foo", "foo"), it will pick the first version that takes three strings. In that case, you would have to cast/convert the enum to its native type so that powershell will pick the right method.

In the latest PowerShellCX changeset, archive read and extract support is finally available. Sorry there are no binary builds yet. Use the Extract-Archive cmdlet as a stand-alone to extract all files. Use Read-Archive to generate ArchiveEntry objects which can be piped through Where-Object for filtering and eventual consumption by Extract-Archive (which can accept ArchiveEntry as well as FileInfo pipeline input). I’ve got progress reporting working too for extract. I’ve added support for reading/extracting SevenZip, Arj, BZip2, Cab, Chm, Cpio, Deb, GZip, Iso, Lzh, Lzma, Nsis, Rar, Rpm, Tar, Wim, Z & Zip.  Yes, you did see ISO support in that list ;-) Write support is only zip, bzip2, tar and gzip still.

There are more features coming, including encrypted archive support.

I just hacked this one up a few minutes ago to let me get an Oracle, Access, Excel/CSV or SQL Server database connection quickly without fiddling with provider strings and other things that just fall out of my head as fast as they get put in. It uses an old trick of creating a zero-length file with an UDL extension and then executing it. The function returns an operable OleDbConnection object, albeit a closed one unless you specifiy –Open as a switch.

You’ll notice I said OleDbConnection. This means you should pick an OLEDB provider on the provider page for best (read: working) results. Cancelling returns nothing.

Ah, how I love the little blue box of typographical terrific-ness.

Why do such a thing? Well, if you’ve created your own aliases for commands and you try to give someone your ps1 script file, it will not run because they have not got the same aliases defined as you. Also, scripts that use fully-resolved names like “Get-ChildItem” are more readable for a newcomer to PowerShell than one that is using the unix-like “ls" alias for example. "Get-ChildItem" leads quite directly to the MSDN documentation, but "ls" might lead you anywhere. Before you publish a script online somewhere for the world to use, it’s important that you try to remove any aliases and replace them with the native command names.

Doing this kind of thing has been talked about before but it was always a very difficult thing to do with PowerShell v1.0, what with the lack of BNF documentation describing the grammar etc. Thankfully, it's a lot easier to do with PowerShell v2.0 (currently at release CTP2) because the team has exposed the Tokenizer for use in scripts. There's been suprisingly little use of it so far, so I figured I'd start the ball rolling with a series of articles based around it. So, let's look at an example script that uses aliases and put it through the meat grinder:

As you can see, it spits out the expanded script to the output stream. The informational messages are written to the host, so they won't interfere if you redirect the output to a file like: .\resolve-aliases.ps1 in.ps1 > out.ps1

Here's the Resolve-Aliases.ps1 script itself:

Of course, this requires PowerShell v2.0 CTP2. Next in the series, I'll give you a script to check your ps1 scripts for backwards compatibility against PowerShell 1.0. That should be handy for those naughty admins out there who despite all the warnings have installed v2 in production. ;-)

Someone on a private mailing list I'm on lamented the problem with powershell's '>' redirection operator defaulting inflexibly to use unicode for encoding the output file. This is not very compatible for NT's ancient console subsystem which works best with ASCII data. Fortunately, there's an easy workaround to fix this:

Due to the magic of command discovery and the fact that > really does use out-file, you can "fix" this by placing the following in your $profile:

function out-file($FilePath, $Encoding, [switch]$Append) {
$input | microsoft.powershell.utility\out-file $filepath -encoding ascii `
     -append:$append
}

From now on, > will be forced to use ASCII encoding. This works because functions have higher precedence than built-in commands in powershell's command discovery search.

UPDATE: Rather annoyingly, I'm informed that this particular workaround doesn't work on v1.0 of PowerShell. I tested the above on v2.0CTP2 only. Doh.

Just a quick one for the frustrated searchers out there. If you've recently installed the SP1 beta for Visual Studio 2008 (or just the 3.5 sp1 beta alone), and you find that you have serious difficulty using SharePoint Designer 2007 against a remote instance of SharePoint running in a VM (or a physical machine) that doesn't have the SP1 Beta bits, you know what to do. My SPD would refuse to load the master page from my virtualized SharePoint instance until I had installed .NET 3.5 SP1 Beta onto the virtual machine also. Just so you know!