see changelog for v0.4.0

Author: jdhitsolutions

PSRemoteOperations.psd1

@@ -1,18 +1,14 @@
 #
 # Module manifest for module 'PSRemoteOperations'
 #
-# Generated by: Jeff Hicks
-#
-# Generated on: 9/17/2018
-#
 
 @{
 
 # Script module or binary module file associated with this manifest.
 RootModule = 'PSRemoteOperations.psm1'
 
 # Version number of this module.
-ModuleVersion = '0.3.6'
+ModuleVersion = '0.4.0'
 
 # Supported PSEditions
 CompatiblePSEditions = @("Desktop")
@@ -24,7 +20,7 @@ GUID = '62bc09fe-38bf-426d-aa3c-e6c2cf6bb528'
 Author = 'Jeff Hicks'
 
 # Company or vendor of this module
-CompanyName = 'JDH IT Solutions, Inc.'
+CompanyName = 'JDH Information Technology Solutions, Inc.'
 
 # Copyright statement for this module
 Copyright = '(c) 2018 Jeff Hicks. All rights reserved.'
@@ -51,7 +47,7 @@ PowerShellVersion = '5.1'
 # ProcessorArchitecture = ''
 
 # Modules that must be imported into the global environment prior to importing this module
-# RequiredModules = @()
+RequiredModules = @('PSScheduledJob')
 
 # Assemblies that must be loaded prior to importing this module
 # RequiredAssemblies = @()
@@ -73,7 +69,7 @@ FunctionsToExport = 'New-PSRemoteOperation','Invoke-PSRemoteOperation','Get-PSRe
 'Register-PSRemoteOperationWatcher'
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
-CmdletsToExport = '*'
+CmdletsToExport = ''
 
 # Variables to export from this module
 VariablesToExport = ''
@@ -96,13 +92,13 @@ PrivateData = @{
     PSData = @{
 
         # Tags applied to this module. These help with module discovery in online galleries.
-        # Tags = @()
+        Tags = @("Remoting","ScheduledJob")
 
         # A URL to the license for this module.
-        # LicenseUri = ''
+         LicenseUri = 'https://github.com/jdhitsolutions/PSRemoteOperations/blob/master/license.txt'
 
         # A URL to the main website for this project.
-        # ProjectUri = ''
+        ProjectUri = 'https://github.com/jdhitsolutions/PSRemoteOperations'
 
         # A URL to an icon representing this module.
         # IconUri = ''

PSRemoteOperations.psm1

@@ -1,9 +1,6 @@
 #requires -version 5.1
 
-#TODO : About topic help
-#TODO : add help
 #TODO : Update Readme
-#TODO : what options are there for initialization section or including profiles?
 
 #region main code
 
@@ -35,8 +32,12 @@ Function New-PSRemoteOperation {
         [ValidateNotNullorEmpty()]
         [string]$ScriptPath,
 
+        [Parameter(HelpMessage = "An array of objects to pass as arguments. Values are positional to your script or scriptblock.")]
         [Object[]]$ArgumentList,
 
+        [Parameter(HelpMessage = "A script block of commands to run prior to executing your script or scriptblock.")]
+        [scriptblock]$Initialization,
+
         [ValidateScript( {Test-Path -Path $_})]
         [Parameter(HelpMessage = "The folder where the remote operation file will be created.")]
         [string]$Path = $global:PSRemoteOpPath,
@@ -71,6 +72,10 @@ Computername = '$Computername'
         $out += "`n"
     }
 
+    if ($Initialization) {
+        $out += "Initialization = '$Initialization'"
+        $out += "`n"
+    }
     $out += "}"
 
     $out | Write-Verbose
@@ -100,12 +105,12 @@ Function Invoke-PSRemoteOperation {
             ValueFromPipelineByPropertyName
         )]
         [ValidatePattern("\.psd1$")]
-        [ValidateScript( {Test-Path -Path $_})]
+        [ValidateScript({Test-Path -Path $_})]
         [Alias("pspath")]
         [string]$Path,
 
         [Parameter(HelpMessage = "Enter the path for the archived .psd1 file")]
-        [ValidateScript( {Test-Path -Path $_})]
+        [ValidateScript({Test-Path -Path $_})]
         [string]$ArchivePath = $global:PSRemoteOpArchive
     )
 
@@ -123,7 +128,7 @@ Function Invoke-PSRemoteOperation {
         Write-Verbose "Comparing $parent to $ArchivePath"
         #The archive path and path for data file must be different
         if ($parent -eq $ArchivePath) {
-            Write-warning "The archive path must be different from the path to the psd1 file."
+            Write-Warning "The archive path must be different from the path to the psd1 file."
             #bail out
             Return
         }
@@ -147,12 +152,32 @@ Function Invoke-PSRemoteOperation {
         #run the command
         Try {
             if ($PSCmdlet.ShouldProcess($cPath)) {
-                Invoke-Command @in -ConnectionUri http://localhost:5985/WSman -ErrorAction stop
+                #create a session
+                Write-Verbose "Creating a temporary local session"
+                $tmpSession = New-PSSession -ConnectionUri http://localhost:5985/WSman -ErrorAction stop
+
+                if ($in.Initialization) {
+                    Write-Verbose "Initializing"
+                    $init = [scriptblock]::Create($in.Initialization)
+                    Invoke-Command -ScriptBlock $init -session $tmpSession
+                    $in.Remove("Initialization")
+                }
+
+                $in.Add("ErrorAction","Stop")
+                $in.Add("Session",$tmpSession)
+                #invoke the command
+                Write-Verbose "Invoking Command"
+                Write-Verbose ($in | Out-String)
+                Invoke-Command @in
+
+                Write-Verbose "Removing temporary session"
+                $tmpSession | Remove-PSSession
             }
+            $errormsg = "''"
             $Completed = $True
         }
         Catch {
-            $errormsg = $_.exception.message
+            $errormsg = """$($_.exception.message)"""
             $Completed = $False
         }
         Finally {
@@ -163,10 +188,10 @@ Function Invoke-PSRemoteOperation {
 
 "@
             #append the result data to the data file.
-            (Get-content -Path $cPath | Select-object -skip 1 | Select-Object -SkipLast 1 ).Foreach( {$resultData += "$_`n"})
+            (Get-Content -Path $cPath | Select-Object -skip 1 | Select-Object -SkipLast 1 ).Foreach( {$resultData += "$_`n"})
 
             $resultData += "Completed = '$completed'`n"
-            $resultData += "Error = '$errormsg'`n"
+            $resultData += "Error = $errormsg`n"
             $resultdata += "Date = '$((Get-Date).toUniversalTime()) UTC'`n"
 
             $resultData += "}"
@@ -258,9 +283,9 @@ Function Register-PSRemoteOperationWatcher {
         [ValidateScript({Test-Path $_})]
         [string]$ArchivePath = $global:PSRemoteOpArchive,
 
-        [Parameter(Mandatory, HelpMessage = "Enter your username and credentials")]
+        [Parameter(HelpMessage = "Enter your username and credentials")]
         [ValidateNotNullOrEmpty()]
-        [PSCredential]$Credential,
+        [PSCredential]$Credential = "$env:USERDOMAIN\$env:USERNAME",
 
         [Alias("Option")]
         [Microsoft.PowerShell.ScheduledJob.ScheduledJobOptions]$ScheduledJobOption
@@ -277,8 +302,8 @@ Function Register-PSRemoteOperationWatcher {
         #guid regex
         $guidrx = "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}"
 
-        get-childitem $in\*.psd1 |
-            where-object {$_.name -match "^$($env:computername)_$guidrx" } |
+        Get-Childitem $in\*.psd1 |
+            Where-Object {$_.name -match "^$($env:computername)_$guidrx" } |
             Invoke-PSRemoteOperation -ArchivePath $out
     }
     Write-Verbose "Using data path: $path"
@@ -291,12 +316,13 @@ Function Register-PSRemoteOperationWatcher {
         MaxResultCount = 1
         ArgumentList = @($Path,$ArchivePath)
         Credential = $Credential
-        InitializationScript = { Import-Module c:\scripts\PSRemoteOperations }
+        InitializationScript = { Import-Module PSRemoteOperations }
     }
 
     if ($ScheduledJobOption) {
         $jobParams.add("ScheduledJobOption",$ScheduledJobOption)
     }
+
     Register-ScheduledJob @jobParams
 
     Write-Verbose "Ending $($myinvocation.MyCommand)"

changelog.md

@@ -1,5 +1,14 @@
 # Changelog for PSRemoteOperations
 
+## v0.4.0
+
++ Added initialization script option to RemoteJob definition and execution
++ Added `New-PSRemoteProfileScript` function
++ Added `PSScheduledJob` as a required module
++ Set default name for `-Credential` parameter of `Register-PSRemoteOperationWatcher` to `$env:username`
++ Added help documentation
++ Created Pester tests for the module
+
 ## v0.3.0
 
 + Renamed function nouns to include a PSPrefix

docs/Get-PSRemoteOperationResult.md

@@ -0,0 +1,116 @@
+---
+external help file: PSRemoteOperations-help.xml
+Module Name: PSRemoteOperations
+online version:
+schema: 2.0.0
+---
+
+# Get-PSRemoteOperationResult
+
+## SYNOPSIS
+
+Parse the contents of a PSRemoteOperation archive file.
+
+## SYNTAX
+
+```yaml
+Get-PSRemoteOperationResult [[-ArchivePath] <String>] [-Computername <String>] [-Newest <Int32>]
+ [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+This command will parse the archived PSRemoteOperation file. It will default to the archive path specified by $PSRemoteOpArchive if it has been defined. The default behavior is to process all files but you can limit the search by computername.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+PS C:\> Get-PSOperationResult -computername Think51
+
+Computername  : think51
+Date          : 09/18/2018 17:19:35 UTC
+Scriptblock   :
+Filepath      : C:\scripts\SystemReport.ps1
+ArgumentsList :
+Completed     : True
+Error         :
+```
+
+Get the result for computer THINK51 using the user-defined $PSRemoteOpArchive variable as the path.
+
+## PARAMETERS
+
+### -ArchivePath
+
+Enter the path to the archive folder. This will default to the global variable PSRemoteOPArchive if it has been defined.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: path
+
+Required: False
+Position: 0
+Default value: $PSRemoteOpArchive
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Computername
+
+Enter a computername to filter on.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Newest
+
+Select the newest X number of results.
+
+```yaml
+Type: Int32
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.
+For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+## OUTPUTS
+
+### RemoteOpResult
+
+## NOTES
+
+Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/
+
+## RELATED LINKS
+
+[about_PSRemoteOperations]()
+
+[Invoke-PSRemoteOperation]()
+
+[New-PSRemoteOperation]()