#requires -version 2.0

#Jeffery Hicks
#http://jdhitsolutions.com/blog
#follow at http://twitter.com/JeffHicks

#Now Available: Windows PowerShell 2.0: TFM (SAPIEN Press 2010)

Function New-FileShortcut {
#requires -version 2.0

<#
.Synopsis
    Create a file link shortcut.
.Description
    This function will create a file shortcut link, a .lnk file. This can be useful when
    moving files to another location and you want to leave a shortcut behind in place
    of the orginal file. You must specify a shortcut name ending in .lnk and the target
    file must already be in place.
    
    This function fully supports -verbose, -confirm and -whatif.

.Parameter Name
    The full filename and path of the shortcut file. It must end in .lnk. You
    should specify the complete path.
.Parameter Target
    The full filename and path of the target file. It must exist as it will be
    verified during the validation process.
.Parameter Passthru
    By default nothing is written to the pipeline. Use -Passthru to write the shortcut
    file object to the pipeline.
.Example
    PS C:\> New-FileShortcut \\file01\files\MyData.lnk \\file02\Archive\MyData.doc
    
    This will create a shortcut file for MyData on FILE01 that points to the actual
    file on FILE02. 
.Example
    PS C:\>  dir H:\Files\*.csv | foreach {
    $dest="\\File02\Archive\files"
      Move-Item $_ -destination $dest
      New-FileShortcut -name (Join-Path $_.Directory "$($_.basename).lnk" -target (Join-path $dest $_.name) -Passthru
      }
     
    This example will move all CSV files from H:\Files to the Archive folder on FILE02. After each file is moved
    a new shortcut link is left in its place.  Join-Path is used to construct valid file paths and names.
        
.Inputs
    None
.Outputs
    File object if you use -Passthru

.Link
   Get-Item
      
.Notes
 NAME:      New-FileShortcut
 VERSION:   1.1
 AUTHOR:    Jeffery Hicks 
 LASTEDIT:  3/17/2010
 
#>

[cmdletBinding(SupportsShouldProcess=$True,ConfirmImpact="Low")]

Param (
    [Parameter(Mandatory=$True, ValueFromPipeline=$False,Position=0,
    HelpMessage="Enter the name of the file shortcut. It must end in .lnk")]
    [ValidateScript({$_.EndsWith(".lnk")})]
    [string]$Name,
    
    [Parameter(Mandatory=$True, ValueFromPipeline=$False,Position=1,
    HelpMessage="Enter the full path to the target file shortcut. The file must already exist.")]
    [ValidateScript({Test-Path $_})]
    [string]$Target,
      
    [Switch]$PassThru

) #end Parameter definition

Begin {
    write-verbose "Starting function"
    write-verbose "Creating the shell COM Object"
    $wshell=New-Object -ComObject "Wscript.Shell"
} #end Begin scriptblock

Process {
    write-verbose "Creating a shortcut for $target as $name"
    #shortcut will be saved in System32 folder unless a full path
    #is specified. If the user just puts in a filename, assume
    #they want the file in the current directory.
    
    if (split-path $name -Parent) {
        $linkpath=$name
    }
    else {
        $linkpath=Join-path (get-location) $name
        write-verbose "Adjusting link file to $linkpath"
    }

    $shortcut=$wshell.CreateShortcut($linkpath)
    $shortcut.TargetPath=$target
    
    if ($pscmdlet.ShouldProcess($Target)) {
        write-verbose "Saving shortcut"
        $shortcut.Save()
    
        if ($passthru) {
            write-verbose "Passing shortcut file object to the pipeline"
            #write the new shortcut file object to the pipeline if -Passthru
            Get-item $shortcut.fullname
        }
    }
      
 } #end Process scriptblock
 
 End {
    write-verbose "Removing the shell object"
    Remove-variable wshell -confirm:$false
    write-verbose "Ending function"
 } #end End scriptblock

} #end Function