pre-release 3.2.0

.vscode/settings.json

@@ -9,10 +9,15 @@
         "dropbox",
         "filepath",
         "message",
+        "mkdir",
+        "nrof",
         "operations",
         "ps",
         "recipient",
         "remote",
-        "mkdir"
+        "scriptpath"
+    ],
+    "cSpell.ignoreWords": [
+        "runspace"
     ]
 }

PSRemoteOperations.psd1

@@ -8,7 +8,7 @@
 RootModule = ""
 
 # Version number of this module.
-ModuleVersion = '3.1.0'
+ModuleVersion = '3.2.0'
 
 # Supported PSEditions
 CompatiblePSEditions = @("Desktop","Core")
@@ -26,7 +26,7 @@ CompanyName = 'JDH Information Technology Solutions, Inc.'
 Copyright = '(c) 2018-2019 JDH Information Technology Solutions, Inc. All rights reserved.'
 
 # Description of the functionality provided by this module
-Description = 'A PowerShell module for executing commands remotely in a non-remoting environment.'
+Description = 'A PowerShell module for executing commands remotely in a non-remoting environment using a shared folder structure such as Dropbox.'
 
 # Minimum version of the Windows PowerShell engine required by this module
 PowerShellVersion = '5.1'
@@ -70,17 +70,29 @@ else {
 }
 
 # Functions 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 functions to export.
-    FunctionsToExport = @('New-PSRemoteOperation', 'Invoke-PSRemoteOperation', 'Get-PSRemoteOperationResult', 'Register-PSRemoteOperationWatcher',
-'Wait-PSRemoteOperation')
+    FunctionsToExport = if ($PSEdition -eq 'Core') {
+        'New-PSRemoteOperation', 'Invoke-PSRemoteOperation', 'Get-PSRemoteOperationResult', 'Wait-PSRemoteOperation',
+        'Get-PSRemoteOperation'
+    }
+    else {
+        #Windows PowerShell gets everything
+        'New-PSRemoteOperation', 'Invoke-PSRemoteOperation', 'Get-PSRemoteOperationResult', 'Register-PSRemoteOperationWatcher',
+        'Wait-PSRemoteOperation', 'New-PSRemoteOperationForm', 'Get-PSRemoteOperation'
+    }
 
 # 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 = ''
+VariablesToExport = @()
 
 # Aliases 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 aliases to export.
-AliasesToExport = 'nro','iro','row','gro'
+AliasesToExport = if ($PSEdition -eq 'core') {
+    'nro', 'iro', 'gro', 'wro','grop'
+}
+else {
+    'nro', 'iro', 'row', 'gro', 'nrof', 'wro','grop'
+}
 
 # DSC resources to export from this module
 # DscResourcesToExport = @()
@@ -125,3 +137,4 @@ PrivateData = @{
 }
 
 
+

README.md

@@ -8,18 +8,32 @@ You can install the latest version from the PowerShell Gallery:
 Install-Module PSRemoteOperations
 ```
 
-See [About_PSRemoteOperations](docs/about_PSRemoteOperations.md) for more detail.
+See [About_PSRemoteOperations](docs/about_PSRemoteOperations.md) for more detail. Pay close attention to the details on defining values for `$PSRemoteOpPath` and `$PSRemoteOpArchive`.
 
 Or check out the individual commands:
 
++ [Get-PSRemoteOperationResult](docs/Get-PSRemoteOperation.md)
 + [Get-PSRemoteOperationResult](docs/Get-PSRemoteOperationResult.md)
 + [Invoke-PSRemoteOperation](docs/Invoke-PSRemoteOperation.md)
 + [New-PSRemoteOperation](docs/New-PSRemoteOperation.md)
 + [Register-PSRemoteOperationWatcher](docs/Register-PSRemoteOperationWatcher.md)
 + [Wait-PSRemoteOperation](docs/Wait-PSRemoteOperation.md)
++ [New-PSRemoteOperationForm](docs/New-PSRemoteOperationForm.md)
+
+## Graphical Interface
+
+The module includes a command called `[New-PSRemoteOperationForm](docs/New-PSRemoteOperationForm.md)`. This is intended to provide an easy way to setup a new remote operation file. You launch the form from the PowerShell prompt.
+
+```powershell
+PS C:\> New-PSRemoteOperationForm
+```
+
+![RemoteOperationForm](assets/new-remoteop-form.png)
+
+This should work fine for simple script blocks. For anything more complicated, it is recommended that you use a shared script file.
 
 ## Cross-Platform and PowerShell Core
 
 The long-term goal is to ensure that this module will work cross-platform and in PowerShell Core. Basic functionality should exist running this module on PowerShell Core, both in Windows and non-Windows environments. Support for CMS messages is limited to Windows platforms through the use of dynamic parameters. `Register-PSRemoteOperationWatcher` requires a Windows platform but should work under PowerShell Core. For non-Windows systems, you will have to come up with your own tooling for monitoring and execution using `Invoke-PSRemoteOperation`.
 
-Last updated 2019-07-31 17:39:11Z UTC
+Last updated 2019-08-10 17:03:11Z UTC

autocompleters.ps1

@@ -2,7 +2,23 @@
 Register-ArgumentCompleter -CommandName Get-PSRemoteOperationResult, New-PSRemoteOperation -ParameterName Computername -ScriptBlock {
     param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
 
-    $names = (Get-ChildItem -Path $PSRemoteOpArchive | Split-Path -leaf).foreach( { $_.split("_")[0].toUpper() }) | Get-Unique
+    $names = (Get-ChildItem -Path $PSRemoteOpArchive | Split-Path -leaf).foreach( {$_.split("_")[0].toUpper() }) | Get-Unique
+
+    if ($wordToComplete) {
+        $fill = $names | Where-Object { $_ -match "$wordToComplete" }
+    }
+    else {
+        $fill = $names
+    }
+    $fill | ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+}
+
+Register-ArgumentCompleter -CommandName Wait-PSRemoteOperation,Get-PSRemoteOperation -ParameterName Computername -ScriptBlock {
+    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
+
+    $names = (Get-ChildItem -Path $PSRemoteOpPath -file | Split-Path -leaf).foreach( {$_.split("_")[0].toUpper() }) | Get-Unique
 
     if ($wordToComplete) {
         $fill = $names | Where-Object { $_ -match "$wordToComplete" }

changelog.md

@@ -1,13 +1,28 @@
 # Change Log for PSRemoteOperations
 
+## v3.2.0
+
++ Modified `Get-PSRemoteOperationResult` to include an option to display the raw contents of the result file
++ Added `New-PSRemoteOperationForm` with an alias of `nrof` for Windows platforms to display a GUI.
++ Added argument completer for `-Computername` in `Wait-PSRemoteOperation` to use names in `$PSRemoteOpPath`
++ Added the `wro` alias for `Wait-PSRemoteOperation`
++ Added the `sb` alias to the `-Scriptblock` parameter on `New-PSRemoteOperation`
++ Added the `sp` alias to the `-Scriptpath` parameter on `New-PSRemoteOperation`
++ Added `Get-PSRemoteOperation` with an alias of `grop` to get pending operations.
++ Updated auto-completers
++ Updated documentation
++ Updated `README.md`
++ Updated Windows Pester tests
++ Minor module reorganization
+
 ## v3.1.0
 
 + Fixed bug using CMS messages with a dynamic parameter
 + Fixed pester tests to accommodate sub-modules
 + Modified code to use `[void]` in place of `Out-Null`
 + All `-Computername` parameters now support an alias of `-cn`
 + Added `Wait-PSRemoteOperation` (Issue #10)
-+ Updated help documentation. Online links now point to markdown files in the Github repository.
++ Updated help documentation. Online links now point to markdown files in the GitHub repository
 + Updated `README.md`
 
 ## v3.0.0
@@ -19,9 +34,9 @@
 + Added SupportsShouldProcess to `New-PSRemoteOperation`
 + Modified metadata construction in `New-PSRemoteOperation` to accommodate Linux. (Issue #7)
 + Modified Pester test file to suppress PSScriptAnalyzer rules
-+ Modified `Invoke-PSRemoteOperation` to use a PowerShell runspace and not `Invoke-Command` to make it more cross-platform friendly.
-+ Modified `New-PSRemoteOperation` to pass argument as a scriptblock.
-+ Fixed mistake in default property names for RemoteOpResult.
++ Modified `Invoke-PSRemoteOperation` to use a PowerShell runspace and not `Invoke-Command` to make it more cross-platform friendly
++ Modified `New-PSRemoteOperation` to pass argument as a scriptblock
++ Fixed mistake in default property names for RemoteOpResult
 + moved functions to separate files
 + Updated help
 + Major version number change due to the number of potentially breaking changes.
@@ -38,7 +53,7 @@
 
 ## v0.6.1
 
-+ Fixed a bug with error messages when they include a variable name with the $ symbol.
++ Fixed a bug with error messages when they include a variable name with the $ symbol
 
 ## v0.6.0
 
@@ -78,4 +93,4 @@
 
 ## v0.1.0
 
-+ initial file and module layout
++ initial file and module layout

core/PSRemoteOperations.psm1

@@ -3,10 +3,6 @@
 . $PSScriptRoot\..\functions.ps1
 . $PSScriptRoot\..\private.ps1
 
-#if running Windows on Powershell Core, include another command
-if ($isWindows) {
-    . $PSScriptRoot\..\windows\Register-PSRemoteOperationWatcher.ps1
-}
 #endregion
 
 #add default properties for the custom result object

docs/Get-PSRemoteOperation.md

@@ -0,0 +1,101 @@
+---
+external help file: PSRemoteOperations-help.xml
+Module Name: PSRemoteOperations
+online version:
+schema: 2.0.0
+---
+
+# Get-PSRemoteOperation
+
+## SYNOPSIS
+
+Get pending PS Remote Operations
+
+## SYNTAX
+
+```yaml
+Get-PSRemoteOperation [[-Computername] <String>] [[-Path] <String>] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+When you create a PS Remote operation, a psd1 file is created in the $PSRemoteOpPath. Instead of doing a simple directory listing of files waiting to be processed, this command will analyze the directory and create an object that reflects each pending operation. The default is to process every file but you can filter by computername.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+PS C:\> Get-PSRemoteOperation
+
+CreatedBy    : DESK01\jeff
+Path         : C:\Users\Jeff Hicks\dropbox\remoteop\REMOTE320_23b9ed7c-9b2c-463d-9ea8-e121cf6d8da4.psd1
+CreatedAt    : 08/10/2019 16:40:14 UTC
+Computername : REMOTE320
+Scriptblock  : get-scheduledtask | where state -eq running | out-file $env:userprofile\dropbox\work\running.txt
+CreatedOn    : DESK01
+
+CreatedBy    : DESK01\jeff
+Path         : C:\Users\Jeff Hicks\dropbox\remoteop\REMOTE320_eae4d5b3-2700-4c98-9253-3d361df16863.psd1
+CreatedAt    : 08/10/2019 15:40:01 UTC
+Computername : REMOTE320
+Scriptblock  :  restart-computer -force
+CreatedOn    : DESK01
+```
+
+## PARAMETERS
+
+### -Computername
+
+Enter a computername to filter on.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: cn
+
+Required: False
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Path
+
+Enter the path to the operations folder.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: 1
+Default value: $PSRemoteOpPath
+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
+
+### RemoteOp
+
+## NOTES
+
+Learn more about PowerShell:
+http://jdhitsolutions.com/blog/essential-powershell-resources/
+
+## RELATED LINKS
+
+[New-PSRemoteOperation](./New-PSRemoteOperation.md)
+
+[Get-PSRemoteOperationResult](./Get-PSRemoteOperationResult.md)

docs/Get-PSRemoteOperationResult.md

@@ -13,15 +13,26 @@ Parse the contents of a PSRemoteOperation archive file.
 
 ## SYNTAX
 
+### result (Default)
+
 ```yaml
 Get-PSRemoteOperationResult [-Computername <String>] [[-ArchivePath] <String>] [-Newest <Int32>]
  [<CommonParameters>]
 ```
 
+### raw
+
+```yaml
+Get-PSRemoteOperationResult [-Computername <String>] [[-ArchivePath] <String>] [-Newest <Int32>] [-Raw]
+ [<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 computer name.
 
+Use the -Raw parameter to display the contents of the psd1 file. This is especially useful when you get an error that the file can't be parsed as a PowerShell data file.
+
 ## EXAMPLES
 
 ### Example 1
@@ -40,6 +51,34 @@ Error         :
 
 Get the result for computer THINK51 using the user-defined $PSRemoteOpArchive variable as the path.
 
+### Example 2
+
+```powershell
+PS C:\> Get-PSRemoteOperation -newest 1 -raw
+
+@{
+CreatedOn = 'Bovine320'
+CreatedBy = 'bovine320\jeff'
+CreatedAt = '08/06/2019 14:02:59 UTC'
+Computername = 'SRV2'
+ArgumentList = @{
+    verbose = '$true'
+    Name = 'bits'
+}
+
+Scriptblock = 'param([string]$Name)
+
+get-service $name | export-clixml "c:\scripts\$name.xml"
+'
+Completed = 'True'
+Error = ""
+Date = '08/06/2019 14:04:04 UTC'
+}
+
+```
+
+Display the contents of the data file for the last operation.
+
 ## PARAMETERS
 
 ### -ArchivePath
@@ -90,9 +129,23 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### CommonParameters
+### -Raw
+Display the raw contents of the result file. This can be useful when you get an error parsing the data file.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: raw
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
 
-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).
+### 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