It was a bit of fun, since I got to work with eventing for the first time in V2.

First, I downloaded the Sync Framework Software Development Kit.  That provided me with the Sync Framework runtime as well as some documentation.

The easiest way for me to get started was to take one of the samples and convert that to PowerShell.

I’m going to walk along the MSDN Sample and provide the equivalent PowerShell, as well as any changes I made to make it feel more PowerShell-y.

Setting Synchronization Options

We are working with the File Sync Provider First up is setting the FileSyncOptions.  FileSyncOptions are an enumeration (a limited list defined in code that maps to certain values) whose values are controlled by setting the appropriate bits to indicate the presence or absence of a flag.  Mark Schill has a great post about how to set bitwise operations.

$options = [Microsoft.Synchronization.Files.FileSyncOptions]::ExplicitDetectChanges
$options = $options -bor [Microsoft.Synchronization.Files.FileSyncOptions]::RecycleDeletedFiles
$options = $options -bor [Microsoft.Synchronization.Files.FileSyncOptions]::RecyclePreviousFileOnUpdates
$options = $options -bor [Microsoft.Synchronization.Files.FileSyncOptions]::RecycleConflictLoserFiles

Specifying a Static Filter

With the File System provider, we can provide filters to include or exclude files and directories.

$FileNameFilter and $SubdirectoryNameFilter are parameters that take strings or string arrays.

$filter = New-Object Microsoft.Synchronization.Files.FileSyncScopeFilter
if ($FileNameFilter.count -gt 0)
{
   $FileNameFilter | ForEach-Object { $filter.FileNameExcludes.Add($_) }
}
if ($SubdirectoryNameFilter.count -gt 0)
{
   $SubdirectoryNameFilter | ForEach-Object { $filter.SubdirectoryExcludes.Add($_) }
}

Performing Change Detection

After configuring the filter, we examine the folders and files located at the paths specified.  If there has not been any previous synchronization, a metadata file will be created in each location to track any changes, updates, and deletes for later synchronization.

function Get-FileSystemChange()
{
    param ($path, $filter, $options)
    try
    {
        $provider = new-object Microsoft.Synchronization.Files.FileSyncProvider -ArgumentList $path, $filter, $options
        $provider.DetectChanges()
    }
    finally
    {
        if ($provider -ne $null)
        {
            $provider.Dispose()
        }
    }
}

Get-FileSystemChange $SourcePath $filter $options
Get-FileSystemChange $DestinationPath $filter $options

Handling Conflicts

Conflict resolution in the Sync Framework happens at the at the event level.  An event is merely something that happens that can trigger other actions.  Using Register-ObjectEvent, we can associate one or more scriptblocks with an event.

First, I defined scriptblocks to handle the conflicts.  There is an enumeration, the ConflictResolutionAction enumeration, that provides some options for dealing with conflicts.  For this example, we are going to pick the source object as the winner for any conflicts.

You will also notice another type of conflict defined, and that is a Constraint conflict.  That can occur when an object of the same name is added on both sides in between synchronizations.  The resolution options for these conflicts can be found in the ConstraintConflictResolutionAction enumeration.

$ItemConflictAction =   {
    $event.SourceEventArgs.SetResolutionAction([Microsoft.Synchronization.ConflictResolutionAction]::SourceWins)
    [string[]]$global:FileSyncReport.Conflicted += $event.SourceEventArgs.DestinationChange.ItemId
}
$ItemConstraintAction = {
     $event.SourceEventArgs.SetResolutionAction([Microsoft.Synchronization.ConstraintConflictResolutionAction]::SourceWins)
     [string[]]$global:FileSyncReport.Constrained += $event.SourceEventArgs.DestinationChange.ItemId
}            

# Configure the events for conflicts or constraints for the source and destination providers
$destinationCallbacks = $destinationProvider.DestinationCallbacks
Register-ObjectEvent -InputObject $destinationCallbacks -EventName ItemConflicting -Action $ItemConflictAction | Out-Null
Register-ObjectEvent -InputObject $destinationCallbacks -EventName ItemConstraint -Action $ItemConstraintAction | Out-Null            

$sourceCallbacks = $SourceProvider.DestinationCallbacks
Register-ObjectEvent -InputObject $sourceCallbacks -EventName ItemConflicting -Action $ItemConflictAction | Out-Null
Register-ObjectEvent -InputObject $sourceCallbacks -EventName ItemConstraint -Action $ItemConstraintAction | Out-Null

We also see for the first time in the script blocks a variable called $event.  This is an automatic variable exposed by the event and provides us information that we can use in our action.

Finally, I’m updating a variable in the global scope.  There probably is a better way to handle this, but scriptblocks executed in response to events only have access to the global scope and any of the automatic variable exposed to it.  Therefore, I use a variable in the global scope to gather my reporting information.

Synchronizing Two Replicas

To start to synchronize the two sides, first we set up the synchronization via a SyncOrchestrator and assign it the local and remote providers, as well as defining the direction of the synchronization.  In this example (sticking with the format from MSDN, we will do an Upload, which is in the SyncDirectionOrder enumeration (other options are Download, DownloadAndUpload, and UploadAndDownload). 

# Create the agent that will perform the file sync
$agent = New-Object  Microsoft.Synchronization.SyncOrchestrator
$agent.LocalProvider = $sourceProvider
$agent.RemoteProvider = $destinationProvider            

# Upload changes from the source to the destination.
$agent.Direction = [Microsoft.Synchronization.SyncDirectionOrder]::Upload            

Write-Host "Synchronizing changes from $($sourceProvider.RootDirectoryPath) to replica: $($destinationProvider.RootDirectoryPath)"
$agent.Synchronize();

To achieve two way synchronization, we will do the upload twice, reversing the order of the providers.

Invoke-OneWayFileSync -SourcePath $SourcePath -DestinationPath $DestinationPath -Filter $null -Options $options
Invoke-OneWayFileSync -SourcePath $DestinationPath -DestinationPath $SourcePath -Filter $null -Options $options

Full Example

I modified the example to write out a custom object (and the logging is in the variable in the global scope as noted in the Handling Conflicts section) with the results of the synchronization (rather than logging it to the console).

In all, my translation is pretty similar to the example code, but there are some differences. 

# Requires -Version 2
# Also depends on having the Microsoft Sync Framework 2.0 SDK or Runtime
# --SDK--
# http://www.microsoft.com/downloads/details.aspx?FamilyID=89adbb1e-53ff-41b5-ba17-8e43a2e66254&displaylang=en
# --Runtime--
# http://www.microsoft.com/downloads/details.aspx?FamilyId=109DB36E-CDD0-4514-9FB5-B77D9CEA37F6&displaylang=en
#
#            

[CmdletBinding(SupportsShouldProcess=$true)]
param (
    [Parameter(Position=1, Mandatory=$true, ValueFromPipelineByPropertyName=$true)]
    [Alias('FullName', 'Path')]
    [string]$SourcePath
    , [Parameter(Position=2, Mandatory=$true)]
    [string]$DestinationPath
    , [Parameter(Position=3)]
    [string[]]$FileNameFilter
    , [Parameter(Position=4)]
    [string[]]$SubdirectoryNameFilter
)
<#
    .Synopsis
        Synchronizes to directory trees
    .Description
        Examines two directory structures (SourcePath and DestinationPath) and uses the Microsoft Sync Framework
        File System Provider to synchronize them.
    .Example
        An example of using the command
#>
begin
{
    [reflection.assembly]::LoadWithPartialName('Microsoft.Synchronization') | Out-Null
    [reflection.assembly]::LoadWithPartialName('Microsoft.Synchronization.Files') | Out-Null            

    function Get-FileSystemChange()
    {
        param ($path, $filter, $options)
        try
        {
            $provider = new-object Microsoft.Synchronization.Files.FileSyncProvider -ArgumentList $path, $filter, $options
            $provider.DetectChanges()
        }
        finally
        {
            if ($provider -ne $null)
            {
                $provider.Dispose()
            }
        }
    }            

    function Invoke-OneWayFileSync()
    {
        param ($SourcePath, $DestinationPath,
                    $Filter, $Options)
        $ApplyChangeJobs = @()
        $AppliedChangeJobs = @()
        try
        {
            # Scriptblocks to handle the events raised during synchronization
            $AppliedChangeAction = {
                $argument = $event.SourceEventArgs
                switch ($argument.ChangeType)
                {
                    { $argument.ChangeType -eq [Microsoft.Synchronization.Files.ChangeType]::Create } {[string[]]$global:FileSyncReport.Created += $argument.NewFilePath}
                    { $argument.ChangeType -eq [Microsoft.Synchronization.Files.ChangeType]::Delete } {[string[]]$global:FileSyncReport.Deleted += $argument.OldFilePath}
                    { $argument.ChangeType -eq [Microsoft.Synchronization.Files.ChangeType]::Update } {[string[]]$global:FileSyncReport.Updated += $argument.OldFilePath}
                    { $argument.ChangeType -eq [Microsoft.Synchronization.Files.ChangeType]::Rename } {[string[]]$global:FileSyncReport.Renamed += $argument.OldFilePath}
                }
            }            

            $SkippedChangeAction = {
                [string[]]$global:FileSyncReport.Skipped += $event.SourceEventArgs.CurrentFilePath            

                if ($event.SourceEventArgs.Exception -ne $null)
                {
                    Write-Error '[' + "$($event.SourceEventArgs.Exception.Message)" +']'
                }
            }            

            # Create source provider and register change events for it            

            $sourceProvider = New-Object Microsoft.Synchronization.Files.FileSyncProvider -ArgumentList $SourcePath, $filter, $options
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $SourceProvider -EventName AppliedChange -Action $AppliedChangeAction
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $SourceProvider -EventName SkippedChange -Action $SkippedChangeAction             

            $ApplyChangeJobs += $SourceApplyChangeJob            

            # Create destination provider and register change events for it
            $destinationProvider = New-Object Microsoft.Synchronization.Files.FileSyncProvider -ArgumentList $DestinationPath, $filter, $options
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $destinationProvider -EventName AppliedChange -Action $AppliedChangeAction
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $destinationProvider -EventName SkippedChange -Action $SkippedChangeAction            

            $ApplyChangeJobs += $DestApplyChangeJob            

            # Use scriptblocks for the SyncCallbacks for conflicting items.
            $ItemConflictAction =   {
                $event.SourceEventArgs.SetResolutionAction([Microsoft.Synchronization.ConflictResolutionAction]::SourceWins)
                [string[]]$global:FileSyncReport.Conflicted += $event.SourceEventArgs.DestinationChange.ItemId
            }
            $ItemConstraintAction = {
                $event.SourceEventArgs.SetResolutionAction([Microsoft.Synchronization.ConstraintConflictResolutionAction]::SourceWins)
                [string[]]$global:FileSyncReport.Constrained += $event.SourceEventArgs.DestinationChange.ItemId
            }            

            #Configure the events for conflicts or constraints for the source and destination providers
            $destinationCallbacks = $destinationProvider.DestinationCallbacks
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $destinationCallbacks -EventName ItemConflicting -Action $ItemConflictAction
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $destinationCallbacks -EventName ItemConstraint -Action $ItemConstraintAction             

            $sourceCallbacks = $SourceProvider.DestinationCallbacks
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $sourceCallbacks -EventName ItemConflicting -Action $ItemConflictAction
            $AppliedChangeJobs += Register-ObjectEvent -InputObject $sourceCallbacks -EventName ItemConstraint -Action $ItemConstraintAction             

            # Create the agent that will perform the file sync
            $agent = New-Object  Microsoft.Synchronization.SyncOrchestrator
            $agent.LocalProvider = $sourceProvider
            $agent.RemoteProvider = $destinationProvider            

            # Upload changes from the source to the destination.
            $agent.Direction = [Microsoft.Synchronization.SyncDirectionOrder]::Upload            

            Write-Host "Synchronizing changes from $($sourceProvider.RootDirectoryPath) to replica: $($destinationProvider.RootDirectoryPath)"
            $agent.Synchronize();
        }
        finally
        {
            # Release resources.
            if ($sourceProvider -ne $null) {$sourceProvider.Dispose()}
            if ($destinationProvider -ne $null) {$destinationProvider.Dispose()}
        }
    }            

    # Set options for the synchronization session. In this case, options specify
    # that the application will explicitly call FileSyncProvider.DetectChanges, and
    # that items should be moved to the Recycle Bin instead of being permanently deleted.            

    $options = [Microsoft.Synchronization.Files.FileSyncOptions]::ExplicitDetectChanges
    $options = $options -bor [Microsoft.Synchronization.Files.FileSyncOptions]::RecycleDeletedFiles
    $options = $options -bor [Microsoft.Synchronization.Files.FileSyncOptions]::RecyclePreviousFileOnUpdates
    $options = $options -bor [Microsoft.Synchronization.Files.FileSyncOptions]::RecycleConflictLoserFiles
}
process
{
    $filter = New-Object Microsoft.Synchronization.Files.FileSyncScopeFilter
    if ($FileNameFilter.count -gt 0)
    {
       $FileNameFilter | ForEach-Object { $filter.FileNameExcludes.Add($_) }
    }
    if ($SubdirectoryNameFilter.count -gt 0)
    {
       $SubdirectoryNameFilter | ForEach-Object { $filter.SubdirectoryExcludes.Add($_) }
    }            

    # Perform the detect changes operation on the two file locations
    Get-FileSystemChange $SourcePath $filter $options
    Get-FileSystemChange $DestinationPath $filter $options            

    # Reporting Object - using the global scope so that it can be updated by the event scriptblocks.
    $global:FileSyncReport = New-Object PSObject |
        Select-Object SourceStats, DestinationStats, Created, Deleted, Overwritten, Renamed, Skipped, Conflicted, Constrained            

    # We don't need to pass any filters here, since we are using the file detection that was previously completed.
    # this will only 
    $global:FileSyncReport.SourceStats = Invoke-OneWayFileSync -SourcePath $SourcePath -DestinationPath $DestinationPath -Filter $null -Options $options
    $global:FileSyncReport.DestinationStats = Invoke-OneWayFileSync -SourcePath $DestinationPath -DestinationPath $SourcePath -Filter $null -Options $options            

    # Write result to pipeline
    Write-Output $global:FileSyncReport
}

Download Invoke-SyncFrameworkSample.zip

PowerShell has two kinds of errors – terminating errors and non-terminating errors.

Terminating errors are the errors that can stop command execution cold.  Non-terminating errors provided an additional challenge, as you need to be notified of failed operations and continue with pipeline operations.  To deal with this issue and to provide additional output options, PowerShell employs the concept of streams.  There are three additional streams (other than the primary pipeline stream) available in PowerShell – Verbose, Warning, and Error (and .  We’ll be concerning ourselves with the output from the Error stream.

There are some automatic variables in the shell that deal with errors as well.  $ErrorActionPreference is a variable that describes how PowerShell will treat non-terminating errors.  $ErrorActionPreference has four options: “Continue” (the default), “SilentlyContinue”, “Inquire”, and “Stop”.  $error is an array of all the errors that have occurred in the current session up to the number specified in $MaximumErrorCount.  $? is a boolean value that is $true if the previous operation succeeded and $false if it did not.

PowerShell does have some built in flexibility to turn non-terminating errors into terminating errors.  Based on our setting of $ErrorActionPreference, PowerShell will treat a non-terminating error differently.  If $ErrorActionPreference is set to ‘”Stop”, PowerShell will treat the errors from that scope and all sub scopes (unless explicitly overridden) as terminating errors.  If “Inquire” is chosen as the $ErrorActionPreference, then PowerShell will prompt the user at the console upon each error to ask whether it should continue (treat as non-terminating) or halt (treat as terminating), as well as providing an option to drop into a nested prompt.

$ErrorActionPreference is a global preference that can be set, but the PowerShell runtime also allows more granular control by providing common parameters for -ErrorAction and -ErrorVariable (shorthand -EA and –EV) which allow you to determine per cmdlet (and in V2 per advanced function) how errors should be handled.  The –ErrorAction parameter takes the same options as $ErrorActionPreference.

So what happens when you encounter an error?

If you hit a terminating error, your script, function, or command will stop.  The error will be logged to the $error variable and written to the error stream.  The $? will be set to false.  You can use the trap construct (or the try/catch/finally construct in V2) to deal with terminating errors and we’ll cover that further in the fourth post in this series.

If you hit a non-terminating error, the result will depend on the $ErrorActionPreference in the scope or the –ErrorAction parameter.  If the $ErrorActionPreference or –ErrorAction parameter is set to ‘Continue’, the error will be written to the error stream, added to the $error array, and the $? will be set to $false.  ‘SilentlyContinue’ will not write an error to the Error stream, but $error and $? are updated.  Finally, ‘Inquire’ provides you an option at each error as to whether to treat it as terminating or non-terminating.  If treated as a non-terminating error, the error will be treated like the $ErrorActionPreference or –ErrorAction parameter is ‘Continue’.

Now, I’ve mentioned that some terminating and non-terminating errors both write to the Error stream, so where does that actually get reported back to the user?  If an error has been written to the error stream, it will be written to the output stream (which may surface differently based on the PowerShell host) separately from the pipeline output unless it is redirected.  This means that the exception objects, which are how the errors are represented, are not saved to a variable if you are assigning the pipeline output to a variable.

For example:

$results = Get-WMIObject Win32_Bios –ComputerName localhost, ComputerThatDoesNotExist
Get-WmiObject : The RPC server is unavailable. (Exception from HRESULT: 0x800706BA)
At line:1 char:22
+ $results = Get-WmiObject  <<<< Win32_Bios -ComputerName localhost, ComputerThatDoesNotExist

creates this output to the screen, but $results will only hold the results of the successful WMI query.  This is where the –ErrorVariable comes in.  You can specify a variable to hold the exceptions generated by a particular cmdlet (or in V2 advanced function).  Specifying a variable does not remove an item from being written to the error stream and displayed as output.

In a console session, you can redirect the error stream with the redirection operators ( 2> or 2>>) or you can merge the error stream with the output stream (2>&1) and write the output to a file, the pipeline, or assign it to a variable.

Up next:

• Error Objects
• Tracing Errors
• Trapping Errors
• Reporting Errors

Other great PowerShell Error Handling posts:

• http://huddledmasses.org/trap-exception-in-powershell/
• http://blogs.msdn.com/powershell/archive/2006/11/03/erroraction-and-errorvariable.aspx
• http://tfl09.blogspot.com/2009/01/error-handling-with-powershell.html
• http://weblogs.asp.net/adweigert/archive/2007/10/10/powershell-try-catch-finally-comes-to-life.aspx
• http://powershell.com/cs/blogs/ebook/archive/2009/03/30/chapter-11-finding-and-avoiding-errors.aspx

1. Identify objects that won’t be used
2. Delete them from memory
3. Compact the space to make room for new objects

The first step is the critical point for PowerShell users.  You may have noticed how the memory used in a PowerShell session can steadily climb (or suddenly climb if you’re dealing with a large number of objects).  I talked about that in this tip.  The .NET garbage collector looks for objects that are still in use or could possibly be in use in the near future (this is a gross oversimplification – if you are really interested in a detailed explanation of how garbage collection works in the .NET Framework, check out this article.)

What this means to scripters who are running into memory pressure issues is that the garbage collector will not reclaim any objects you have actively referenced (meaning that you’ve assigned them to a variable) in your current or higher scope. 

Since this can sound a bit convoluted let’s look at an example. 

I read a large file to parse it and leave the contents of the original stored in a variable

PS> $MyLargeFile =  Get-Content MyLargeFile.txt
PS> Foreach ($line in $MyLargeFile) {
DoSomething $line | Out-File NewUpdatedLargeFile.txt
}

One of the problems with the above pattern is that the original file remains saved in memory and doesn’t get released unless you explicitly remove the reference, either by using Remove-Variable or Remove-Item or by changing what $MyLargeFile points to by assigning another value to it. 

This isn’t VBScript where you have to set values to “Nothing”, but you should be aware of what larger object sets you are retaining in memory. 

In the Base Class Libraries, the root namespace is the System namespace.  The System namespace defines a large amount of the base types, like Object (which all classes derive from), String, DateTime, Boolean, and numerous others.  When you specify types, PowerShell can infer the “System” part.

Example:

PS C:\scripts\PowerShell> $random = New-Object –TypeName Random

is the same as

PS C:\scripts\PowerShell> $random = New-Object –TypeName System.Random

Namespaces are hierarchical, except in naming convention. The representation of a file in PowerShell is a great example.  A file object is represented in PowerShell as a System.IO.FileInfo object.  The FileInfo class lives in the System.IO namespace, which is a separate namespace than the System namespace.  There is a hierarchical impression implied, but that is solely through naming convention.

The CLR (Common Language Runtime) does not care about namespaces, only the fully qualified name of the class, so why use namespaces at all?

Namespaces are a convenience for developers, as languages like C# and VB.NET have language constructs that allow the developer to not have to use the fully qualified type name every time that is needed to be referenced.  C# provides the “using” syntax and VB.NET has the “imports” syntax.

How does this apply to PowerShell?

PowerShell does not currently have a “using” or “imports” syntax or language feature, but there are a couple of workarounds.  You can use variables holding the namespace and string concatenation to save some typing

PS C:\scripts\PowerShell> $netinfo = ‘System.Net.NetworkInformation’
PS C:\scripts\PowerShell> $ping = New-Object “$netinfo.ping”
PS C:\scripts\PowerShell> $ping.gettype()
IsPublic IsSerial Name           BaseType
——– ——– —-                ——–
True     False    Ping            System.ComponentModel.Component

This doesn’t work with type accelerators though (at least in V1)..  V2 CTP3 has some other options and Oisin Grehan has a great discussion on how to find the type accelerators and add your own.

Another option would be to create a function to wrap the creation of objects for particular namespaces.

Use-Namespace is a function I came up with to create a function to wrap New-Object for specific namespaces.

The useage of Use-Namespace is
PS C:\scripts\PowerShell>Use-Namespace System.IO, System.Net
PS C:\scripts\PowerShell>$memorystream = New-System.IOObject MemoryStream
PS C:\scripts\PowerShell>$memorystream.GetType()
PS C:\scripts\PowerShell> $memorystream.gettype()
IsPublic IsSerial  Name                    BaseType
——– ——–   —-                         ——–
True     True     MemoryStream      System.IO.Stream

And the function is here..

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

function Use-Namespace()
{
  param ([string[]]$Namespace)
  BEGIN
  {
    if ($Namespace.length -gt 0)
    {
      $Namespace | Use-Namespace
    }
  }
  PROCESS
  {
    if ($_ -ne $null)
    {
      $NS = $_
      $NSObject = "$NS" + "Object"
      $function = @"
param (`$Class, [string[]]`$ArgumentList)
if (`$ArgumentList.length -gt 0)
{
return New-Object -TypeName "$NS.`$Class" -ArgumentList `$ArgumentList
}
else
{
return New-Object -TypeName "$NS.`$Class"
}
"@
    Set-Item -Path "function:global:New-$NSObject" -Value $function -force
    Write-Debug "Created function:global:New-$NSObject "
    }
  }
}

PSMDTAG:FAQ CLR
PSMDTAG:FAQ Namespace
PSMDTAG:FAQ .NET Framework

• Windows Development and Frameworks
• Windows Mobile Development
• Office and SharePoint Development
• Developer Tools, Languages & Practices
• Web Development & User Experience

PowerShell Community’s own Marco Shaw (MVP) will be presenting the ONLY PowerShell session:

WIN300 Scripting the Microsoft .NET Framework Using Windows PowerShell
Now that PowerShell is part of the Microsoft Common Engineering Criteria, expect to see more and more PowerShell in Microsoft server products. This session looks at how PowerShell can be used to directly access the .NET Framework. Some simple examples are demonstrated, but also more advanced examples of using Windows Presentation Foundation (.NET 3.0) and LINQ (.NET 3.5) are discussed.

You can find more information about this event here or on Marco’s blog. 

I’m looking forward to seeing this presentation.  Hope to “see” you there!  Register now..

If I don’t clear out the variables that reference objects I’m done with, the amount of memory used by my PowerShell session increases dramatically, which impacts some other applications that I run.  (I know, memory is cheap.. buy more memory.  I’ve got a limited budget and I have to prioritize.)

So I’ve written a couple of functions that can help me clear out the extraneous variables and free up some of that memory being used by PowerShell.

The first function (and I’m open to suggestions on the naming here..), Set-SessionVariableList, reads in all the variable names in the global scope and saves them to the AppDomain (so I don’t lose them when I clear out variables).  I recommend running this shortly after starting PowerShell or running it from your profile.

Later, when I’m feeling some memory pressure, I can run the second function Remove-NewVariable, which calls Remove-Variable for all variables whose names I did not save in the AppDomain.  This removes the references to the objects they represented. 

Info Overload: Notice that I said that it removed the references to those objects.  Those objects still exist in memory and remain there until the CLR “garbage collects” them, releasing that memory.  The CLR has a process to reclaim that “used” memory when there is a need to reuse it or when it is impacting other performance.

Even if you skipped the previous bold section (which is perfectly acceptable), you might have noticed that when you clear out a variable, your memory usage for PowerShell might remain high for a while.  My function speeds up the natural “garbage collection” process by calling [System.GC]::Collect(), forcing the CLR to reclaim that memory.

There are a couple of “helper” functions included, Get-SessionVariableList, which will list out the variable names saved, in case you wanted to see which variables were going to be left and Add-SessionVariable, which adds more values to the current list. 

Feedback and improvements are always welcome!

PSMDTAG:FAQ Memory

One feature that the AppDomain has is to store globally accessible name/value pairs.  Normally, variables in PowerShell should handle most of your “in-process” storage needs, but for the times that they don’t, you have your AppDomain.

To access the AppDomain object, you can use the static property CurrentDomain on the System.AppDomain class.

(NOTE: Though I usually refer use the fully qualified namespace, PowerShell does allow you to skip the “System” portion of the namespace.  I’m using the full namespace for clarity on the blog, but when typing on the command line, it is easier to skip that.)

PS C:\> [system.appdomain]::CurrentDomain

To save a name/value pair to your AppDomain, you can use the SetData method.

PS C:\> [system.appdomain]::CurrentDomain.SetData(‘ThisIsMyNameOrKey’, (‘This’,'Can’,'Be’,'Any’,'Object’,'Or’,'Collection’) )

Any object or collection can be saved in the AppDomain, and you are not limited to just one.

Accessing those values is just as easy, using the GetData method.

PS C:\> [system.appdomain]::CurrentDomain.GetData(‘ThisIsMyNameOrKey’)
This
Can
Be
Any
Object
Or
Collection

And there we have our collection back.

PSMDTAG:.Net AppDomain

Many classes provide static members supply functionality where it doesn’t make sense to need an object. 

The System.Math class contains a couple of static properties, PI and E. 

PS C:\scripts\PowerShell> [math]::E
2.71828182845905
PS C:\scripts\PowerShell> [math]::PI
3.14159265358979

Constant values are not the only type of property that you’ll find.  The System.AppDomain class has a static property, CurrentDomain, which is an AppDomain instance referring to the current application domain.

PS C:\scripts\PowerShell> [AppDomain]::CurrentDomain.gettype()

IsPublic  IsSerial Name         BaseType
——–    ——–    —-            ——–
True     False    AppDomain System.MarshalByRefObject

System.Math also contains a number of static methods that provide a great deal of basic mathematical function.

PS C:\scripts\PowerShell>[Math] | get-member –static –membertype method | select name

Name
—-
Abs
Acos
Asin
Atan
Atan2
BigMul
Ceiling
Cos
Cosh
DivRem
Equals
Exp
Floor
IEEERemainder
Log
Log10
Max
Min
Pow
ReferenceEquals
Round
Sign
Sin
Sinh
Sqrt
Tan
Tanh
Truncate

I wrote a little helper function to get the static method definitions (Get-StaticMethodDefinition), which you can grab from PoshCode.org.

(V2 CTP3 – We can use the trick of using the method name without parenthesis following to get additional information on each of the methods that we are interested in.)

One type of static method that I would like to highlight is the factory method.  A factory method is a common way of controlling object creation.  At its most basic level, a factory pattern is a method that creates objects of a specified type. 

An example of this is the System.Net.WebRequest’s Create method.

PS C:\scripts\PowerShell> $web = [net.webrequest]::create(‘http://www.google.com‘)
PS C:\scripts\PowerShell> $web.gettype()

IsPublic IsSerial Name                                     BaseType
——– ——– —-                                     ——–
True     True     HttpWebRequest                           System.Net.WebReq…

The factory method Create used the argument (‘http://www.google.com’) to determine the type of WebRequest object to create.  In this case, it created an HttpWebRequest object, which is a more specialized version of the WebRequest for HTTP requests. 

Let’s see how it would respond if we passed the Create method a URI with FTP.

PS C:\scripts\PowerShell> $web = [net.webrequest]::create(‘ftp://ftp.google.com’)
PS C:\scripts\PowerShell> $web.gettype()

IsPublic IsSerial Name                                     BaseType
——– ——– —-                                     ——–
True     False    FtpWebRequest                            System.Net.WebReq…

As we can see, the WebRequest class created an FtpWebRequest object.

Factory methods provide developers a way to more flexibly support different operations by allowing the static method to determine which object to return.

UPDATE:  Joel “Jaykul” Bennet added a V2 advanced function to convert static methods to functions to PoShCode.org  and pointed out Oisin Grehan’s blog post about creating functions from static methods (V1 compatible).

I’ve been really happy to receive some of the feedback (positive and constructive criticism) on this series.  There is a lot of the .NET Framework to cover, and I’m open to suggestions as to what you would like to know.  Please post a comment on the blog or email me at Steve at UsePowerShell.Com.

To send an email from PowerShell using the .NET Framework, you can use the System.Net.Mail.SMTPClient class.

First, you need to create your MailMessage

PS C:\scripts\PowerShell> $message = New-Object System.Net.Mail.MailMessage –ArgumentList steve@usepowershell.com, nobody@adomain.com, ‘This is a test’, ‘I’m going to send an email via PowerShell’

If you need to add an attachment, you can add one with the System.Net.Mail.Attachment class.

To create the attachment, we’ll create an use an overload of the Attachment class that allows us to specify a filename and a MIME type (the MIME types are available in several enumerations:  System.Net.Mime.MediaTypeNames.Application, System.Net.Mime.MediaTypeNames.Image, and System.Net.Mime.MediaTypeNames.Text – I’ve had a bit of trouble accessing those enumerations via PowerShell, but you can specify the name of the enumeration value in a string).

PS C:\scripts\PowerShell> $attachment = New-Object System.Net.Mail.Attachment –ArgumentList ‘c:\docs\test.xls’, ‘Application/Octet’

PS C:\scripts\PowerShell> $message.Attachments.Add($attachment)

After we have our email and optional attachment, we’ll create the SMTP client and have it configured to use the SMTP server of our choice.

The constructor of the SMTPClient class that we will use is

SmtpClient(
        String host,
)

PS C:\scripts\PowerShell> $smtp = New-Object System.Net.Mail.SMTPClient –ArgumentList 10.10.10.15

All that is left is sending our email..

PS C:\scripts\PowerShell> $smtp.Send($message)

Have fun!

NOTE:

There is a shortcut to creating the MailMessage object like we did.. there is an overload of Send where you can pass in four strings (from, to, subject, and message).  The SMTPClient handles the creation of the MailMessage in the background.

A faster method would be

PS C:\scripts\PowerShell> $smtp = New-Object System.Net.Mail.SMTPClient –ArgumentList 10.10.10.15

PS C:\scripts\PowerShell> $smtp.Send(‘steve@usepowershell.com’, ‘nobody@adomain.com’, ‘This is a test’, ‘I’m going to send an email via PowerShell’)

A constructor is a method whose job is to create the object that you want to work with.  When I created the Ping object

PS C:\scripts\PowerShell> $ping = New-Object System.Net.NetworkInformation.Ping

the New-Object cmdlet calls the constructor for Ping.

Like other methods, constructors can require parameters and can have multiple overloads. 

Let’s look at System.Net.Mail.MailMessage, which is a object that represents an email message.

The MailMessage constructor contains several overloads.  The first method listed is MailMessage(), which is the default constructor.  This method does not require any arguments and returns an empty MailMessage object.  In PowerShell, we would call this method via New-Object, just like with Ping class.

MailMessage()

PS C:\scripts\PowerShell> $message = New-Object System.Net.Mail.MailMessage

The first overload requires two MailAddress objects, the first of which is the “from” address and the second is the “to” address. 

MailMessage(
        MailAddress from,
        MailAddress to,
)

Creating an object in PowerShell from a constructor that requires parameters can be done in two ways.  The first is to use the method call notation.

PS C:\scripts\PowerShell> $message = New-Object System.Net.Mail.MailMessage($MailFrom, $MailTo)

The second is to use the ArgumentList parameter.

PS C:\scripts\PowerShell> $message = New-Object System.Net.Mail.MailMessage –ArgumentList $MailFrom, $MailTo

If you happen to have MailAddress objects floating around, this might work for you.  A more common scenario would be to use the next overload, which takes two strings.

MailMessage(
        String from,
        String to,
)

This overload requires two strings, one for the “to” and one for the “from” address. 

The final overload for MailMessage is

MailMessage(
        String from,
        String to,
        String subject,
        String body,
)

This overload allows you to pass in four strings and get back basic MailMessage object that is ready to be sent.

Wouldn’t it be great to have a function, where we could provide a type name and get a listing of all the constructors, right from the command line (not needing to go to the MSDN documentation every time).  Jeffrey Snover has beaten me to the punch and provided a function to find the constructors, appropriately called Get-Constructor.  Add that function to the your toolbox, and exploring the .NET Framework becomes a lot easier.

Next up, we’ll look at static methods.  Static methods are methods that can be called without having to create a instance of an object.

One particular type of static method that we’ll dig in to is the factory method, which is another way to create instances of objects.

PS C:\> $encoder = new-object System.Text.ASCIIEncoding

PS C:\> $bytes = $encoder.Getbytes(‘Hello From Steve’)

PS C:\> $response = $ping.Send(‘google.com’, 100, $bytes)

Let’s take a look at the response we get back.

PS C:\> $response | Get-Member

   TypeName: System.Net.NetworkInformation.PingReply

Name                  MemberType     Definition
—-                       ———-     ———-
Equals                  Method         System.Boolean Equals(Object obj)
GetHashCode        Method         System.Int32 GetHashCode()
GetType               Method         System.Type GetType()
get_Address          Method         System.Net.IPAddress get_Address()
get_Buffer            Method         System.Byte[] get_Buffer()
get_Options          Method         System.Net.NetworkInformation.PingOptions…
get_RoundtripTime Method         System.Int64 get_RoundtripTime()
get_Status            Method         System.Net.NetworkInformation.IPStatus ge…
ToString               Method         System.String ToString()
Address                Property       System.Net.IPAddress Address {get;}
Buffer                  Property       System.Byte[] Buffer {get;}
Options                Property       System.Net.NetworkInformation.PingOptions…
RoundtripTime       Property       System.Int64 RoundtripTime {get;}
Status                  Property       System.Net.NetworkInformation.IPStatus St…
BufferSize             ScriptProperty System.Object BufferSize {get=$this.Buffe…
OptionsString        ScriptProperty System.Object OptionsString {get=’TTL={0}…

Get-Member shows us that this is a PingReply object in the System.Net.NetworkInformation namespace.

Looking at the PingReply object that was returned, we have several methods that look strangely similar to the properties, but with a “get_” prefixed to it.  When you see a method that matches a Property, but has “get_” or “set_”, that is a method exposed by the .NET Framework that provides the functionality for the properties.  When you access the Buffer property, you are actually calling the get_Buffer method.  Properties are, for the most part, easier to work with and you can effectively ignore those methods.  Properties also contain a clue in their description, if you look at the end of the Buffer property’s description, you see “{get;}” which indicates that there is a way to retrieve that property.  Properties can also show “{set;}” which indicates that you can update that property.

In PowerShell V2 CTP3 those “getters” and “setters” (as those methods are commonly called) are hidden by default.  If you are running CTP3 and want to see the “getters” and “setters”, you can call Get-Member with the Force parameter.

PS C:\> $response | Get-Member –Force

Back to the properties of our return object.  The properties names are pretty self-explanatory, but to confirm we got back the “special” packet we crafted, let’s take a look at the Buffer property and convert that back to text.

PS C:\> $encoder.GetString($response.buffer)
Hello From Steve

Now for the meat of the response, the RoundtripTime and Status.  I commonly use the Roundtrip time to watch for latency on my network, and since it is exposed so nicely, it is easy to log.

PS C:\> $response.RoundtripTime
74

And of course, we are interested in the Status.

PS C:\> $response.Status
Success

Now, we can see from the Get-Member return above, that Status is not just a string that says, “Success”, it is a IPStatus enumeration (more on enumerations coming up, but long story short, there are a number of predefined values that an IPStatus object can hold)(also found in the System.Net.NetworkInformation namespace). 

I’m normally checking the IPStatus for a Success value like

PS C:\> $success = [System.Net.NetworkInformation.IPStatus]::Success

PS C:\> $response.status -eq $success
True

I could compare the string results, but then I’m stepping back to parsing text results.  By using the IPStatus enumeration values, I can get be reasonably sure that my value are correct and I don’t have any text matching issues.

In the next post in this series, we’ll take a look at a special type of method, the constructor.

(It has been bugging me and I can’t really concentrate on my other tasks, so I need to get this out of the way.)

One suggestion I had was to create a type extension that had the property he was adding, but he was more interested in tagging specific functions, not all of them.

So, I’ve written a couple of little ScriptProperties to save and restore NoteProperties which have been added to FunctionInfo objects.  I’ve added these to a PS1XML.

   1: <?xml version="1.0" encoding="utf-8" ?> 

   2: <Types> 

   3:     <Type> 

   4:         <Name>System.Management.Automation.FunctionInfo</Name> 

   5:         <Members> 

   6:             <ScriptMethod> 

   7:                 <Name>SaveMetadata</Name> 

   8:                 <Script> 

   9: $DefaultProperties = 'PSPath', 'PSDrive', 'PSProvider', 'PSIsContainer'

  10: $SaveDirectory = Split-Path $profile

  11: $File = Join-Path $SaveDirectory "$($this.Name).xml"

  12: $this.PSObject.Properties | Where-Object {$DefaultProperties -notcontains $_.Name -and $_.MemberType -like 'NoteProperty'} | Export-Clixml -Path $file

  13:                 </Script> 

  14:             </ScriptMethod>

  15:             <ScriptMethod> 

  16:                 <Name>LoadMetadata</Name> 

  17:                 <Script> 

  18: $SaveDirectory = split-path $profile

  19: $PathToCustomProp = Join-Path $SaveDirectory "$($this.name).xml"

  20: if (Test-Path $PathToCustomProp)

  21: {

  22:     foreach ($Property in Import-Clixml -Path $PathToCustomProp)

  23:     {

  24:         Add-Member -InputObject $this -MemberType NoteProperty -Name $Property.Name -Value $Property.Value

  25:     }

  26: }

  27:                 </Script> 

  28:             </ScriptMethod> 

  29:         </Members> 

  30:     </Type> 

  31: </Types> 

After saving this file as a PS1XML file, you can call Update-TypeData –Prepend path\to\thefile.ps1xml, and every FunctionInfo object will have two script properties – SaveMetadata and LoadMetadata.  As I’ve configured it, the data will be saved to the user’s profile directory and under a filename that matches the function name.  So, you can add NoteProperties to your heart’s desire and save and recall them as needed. 

I don’t have a direct application for this, and it can probably be cleaned up or done more efficiently, but I had to work through the problem.  I’d love to hear your feedback!

Now, let’s take a look at how some of these terms surface themselves in PowerShell.

One of the most common tasks you might encounter is needing to ping a computer.  There is ping.exe, which works and has been a common guest in my console sessions for years.  You can also get ping information via WMI which provides you with some interesting information.

PS C:\scripts\PowerShell> Get-WmiObject Win32_PingStatus -filter “Address=’google.com’”

My preference is to use a class from the .NET Framework called Ping.  Ping lives in the System.Net.NetworkInformation namespace.

To access this in PowerShell, I’ll create an instance of the class and refer to it with a variable, $ping.

PS C:\scripts\PowerShell> $ping = New-Object System.Net.NetworkInformation.Ping

By typing the method name without the parenthesis immediately after it, PowerShell will give us information about the method.

PS C:\scripts\PowerShell> $ping.send

MemberType          : Method
OverloadDefinitions : {System.Net.NetworkInformation.PingReply Send(String ho
                      stNameOrAddress), System.Net.NetworkInformation.PingRep
                      ly Send(String hostNameOrAddress, Int32 timeout), Syste
                      m.Net.NetworkInformation.PingReply Send(IPAddress addre
                      ss), System.Net.NetworkInformation.PingReply Send(IPAdd
                      ress address, Int32 timeout)…}
TypeNameOfValue     : System.Management.Automation.PSMethod
Value               : System.Net.NetworkInformation.PingReply Send(String hos
                      tNameOrAddress), System.Net.NetworkInformation.PingRepl
                      y Send(String hostNameOrAddress, Int32 timeout), System
                      .Net.NetworkInformation.PingReply Send(IPAddress addres
                      s), System.Net.NetworkInformation.PingReply Send(IPAddr
                      ess address, Int32 timeout), System.Net.NetworkInformat
                      ion.PingReply Send(String hostNameOrAddress, Int32 time
                      out, Byte[] buffer), System.Net.NetworkInformation.Ping
                      Reply Send(IPAddress address, Int32 timeout, Byte[] buf
                      fer), System.Net.NetworkInformation.PingReply Send(Stri
                      ng hostNameOrAddress, Int32 timeout, Byte[] buffer, Pin
                      gOptions options), System.Net.NetworkInformation.PingRe
                      ply Send(IPAddress address, Int32 timeout, Byte[] buffe
                      r, PingOptions options)
Name                : Send
IsInstance          : True

What I am most interested in is the Overload Definitions, which is the explanation of how I can use this method.

PS C:\scripts\PowerShell> $ping.send.overloaddefinitions

System.Net.NetworkInformation.PingReply Send(String hostNameOrAddress)
System.Net.NetworkInformation.PingReply Send(String hostNameOrAddress, Int32 timeout)
System.Net.NetworkInformation.PingReply Send(IPAddress address)
System.Net.NetworkInformation.PingReply Send(IPAddress address, Int32 timeout)
System.Net.NetworkInformation.PingReply Send(String hostNameOrAddress, Int32 timeout, Byte[] buffer)
System.Net.NetworkInformation.PingReply Send(IPAddress address, Int32 timeout, Byte[] buffer)
System.Net.NetworkInformation.PingReply Send(String hostNameOrAddress, Int32 timeout, Byte[] buffer, PingOptions options)
System.Net.NetworkInformation.PingReply Send(IPAddress address, Int32 timeout, Byte[] buffer, PingOptions options)

As we can see from the above output $ping.Send has several different ways that we can call it and it also shows the object that we will get in return, an object of the type System.Net.NetworkInformation.PingReply.

The first overload for $ping.Send is to supply it an object of the type String (remember, in PowerShell, even text is an object) which represents the hostname or IP address of the host we wish to ping.

PS C:\scripts\PowerShell> $ping.send(‘google.com’)

Status        : Success
Address       : 74.125.45.100
RoundtripTime : 29 ms
BufferSize    : 32
Options       : TTL=243, DontFragment=False

Here, we called $ping.Send with a argument of the String ‘google.com’ and received back an object of the type PingReply.  We can see the textual representation of it’s properties.  In my next post, we’ll dig into the return object a bit more and see how we can use its properties to our advantage.

We still have a number of other ways that we can call $ping.Send.  Our second option is to provide a String describing the hostname or IP address (as before), but also allows us to specify a timeout by providing an Int32.  (Just a quick note, if you specify a really low timeout value, the reply still may be received.  It is more of an option to provide a longer than normal, five seconds, timeout period.)

We also see overloads that take an object of the IPAddress type to describe the target of the Ping.

Now, things get a bit more interesting.  The next argument we see is of the type Byte[], which means an Array of Byte objects.  The quick explanation of an Array is a collection of objects (not 100 percent accurate, but sufficient for right now).  This allows us to specify exactly what data will be sent with the ICMP echo message.

The final argument is to supply an object of the PingOptions type.  This allows us to specify an Int32 as the TTL (Time To Live) and a Boolean as Don’t Fragment option.

I’m starting to run a bit long here, so I’m going to continue walking through this example in my next post.  We’ll create an object of type Ping with some custom options and then dig in to the object that is returned.

One of the first hurdles that many IT Pro’s come across when trying to see where the .NET Framework fits into their workflow is the terminology. 

Before we start digging into the guts of the .NET Framework, let’s cover some definitions:

• .NET Framework – The .NET Framework is a software framework that contains the Common Language Runtime and  Base Class Libraries that provide much of the functionality.  There are several versions of the .NET Framework.  PowerShell is compatible with versions 2.0, 3.0, and 3.5. 
• Common Language Runtime (CLR) – The Common Language Runtime is the execution environment for .NET applications.  The CLR provides memory management, exception handling, thread management, and security infrastructure.  The CLR is the engine that runs .NET applications.
• Base Class Libraries (BCL) – The Base Class Libraries are sets of common functions accessible by any .NET language, including PowerShell.  The BCL is organized into namespaces based on functionality.  For example, the Webclient class is in the System.Net namespace.  The BCL includes functions for working with files, networking, database interaction, graphics, and much more.
• Namespace – A namespace allows CLR functions to be organized and distinguished.  Using a namespace helps prevent naming conflicts without having to have extra long names.  For example, the class System.Net.NetworkInformation.Ping is in the System.Net.NetworkInformation namespace.
• Class – A class is an abstract definition of some functionality.  The class is the definition that the CLR uses when objects are created.  Classes are also referred to as Types.  Classes can also have static methods, which are functions that can be used without having to create an instance of the class.
• Object – An object is the instance of a class.  An object is a distinct creation in memory that follows the blueprint described in the class.  For example, System.Net.WebClient is a class.  To create an instance of that class in PowerShell, I would: $webclient = New-Object System.Net.WebClient.  The result would be an object of the type System.Net.Webclient which is pointed to by the variable $webclient.
• Property – A property is data that is associated with an object or class.  Properties themselves are objects.  In our example, the System.Net.Webclient object referred to by $webclient has a property Credentials, which is an object of the type System.Net.NetworkCredentials.
• Method – Methods are actions that the object (or type in the case of static methods) can perform.  Methods can have a return type and can require different sets of parameters, allowing you different ways to call them.
• Event – Events are notices that an object can expose, allowing others to run code in response to a change of state of some sort.
• Exception – Exceptions are the error handling mechanism in the CLR.  Exceptions are strongly typed, so you can handle expected errors in your code differently depending on the problem.

Now that we’ve got some definitions covered, we’ll start using PowerShell to expose the capabilities that the framework provides us and dig further into these definitions.