v3.3.0

Author: jdhitsolutions

.vscode/settings.json

@@ -14,11 +14,13 @@
         "nrof",
         "operations",
         "ps",
+        "psremoteoperations",
         "recipient",
         "remote",
         "scriptpath"
     ],
     "cSpell.ignoreWords": [
+        "dropbox",
         "runspace"
     ]
 }

PSRemoteOperations.psd1

@@ -8,7 +8,7 @@
 RootModule = ""
 
 # Version number of this module.
-ModuleVersion = '3.2.1'
+ModuleVersion = '3.3.0'
 
 # Supported PSEditions
 CompatiblePSEditions = @("Desktop","Core")
@@ -72,12 +72,13 @@ 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 = if ($PSEdition -eq 'Core') {
         'New-PSRemoteOperation', 'Invoke-PSRemoteOperation', 'Get-PSRemoteOperationResult', 'Wait-PSRemoteOperation',
-        'Get-PSRemoteOperation'
+        'Get-PSRemoteOperation','Register-PSRemoteOpPath','Import-PSRemoteOpPath'
     }
     else {
         #Windows PowerShell gets everything
         'New-PSRemoteOperation', 'Invoke-PSRemoteOperation', 'Get-PSRemoteOperationResult', 'Register-PSRemoteOperationWatcher',
-        'Wait-PSRemoteOperation', 'New-PSRemoteOperationForm', 'Get-PSRemoteOperation'
+        'Wait-PSRemoteOperation', 'New-PSRemoteOperationForm', 'Get-PSRemoteOperation','Register-PSRemoteOpPath',
+        'Import-PSRemoteOpPath'
     }
 
 # 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.
@@ -106,25 +107,26 @@ else {
 # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
 PrivateData = @{
 
-    PSData = @{
+        PSData = @{
 
-        # Tags applied to this module. These help with module discovery in online galleries.
-        Tags = @("Remoting","ScheduledJob")
+            # Tags applied to this module. These help with module discovery in online galleries.
+            Tags         = @("Remoting", "ScheduledJob")
 
-        # A URL to the license for this module.
-         LicenseUri = 'https://github.com/jdhitsolutions/PSRemoteOperations/blob/master/license.txt'
+            # A URL to the license for this module.
+            LicenseUri   = 'https://github.com/jdhitsolutions/PSRemoteOperations/blob/master/license.txt'
 
-        # A URL to the main website for this project.
-        ProjectUri = 'https://github.com/jdhitsolutions/PSRemoteOperations'
+            # A URL to the main website for this project.
+            ProjectUri   = 'https://github.com/jdhitsolutions/PSRemoteOperations'
 
-        # A URL to an icon representing this module.
-        # IconUri = ''
+            # A URL to an icon representing this module.
+            # IconUri = ''
 
-        # ReleaseNotes of this module
-        # ReleaseNotes = ''
-        # ExternalModuleDependencies = "PSScheduledJob"
+            # ReleaseNotes of this module
+            ReleaseNotes = 'http://bit.ly/2KsYbu2'
 
-    } # End of PSData hashtable
+            # ExternalModuleDependencies = "PSScheduledJob"
+
+        } # End of PSData hashtable
 
 } # End of PrivateData hashtable
 

README.md

@@ -1,5 +1,8 @@
 # PSRemoteOperations
 
+[![PSGallery Version](https://img.shields.io/powershellgallery/v/PSRemoteOperations.png?style=for-the-badge&logo=powershell&label=PowerShell%20Gallery)](https://www.powershellgallery.com/packages/PSRemoteOperations/) [![PSGallery Downloads](https://img.shields.io/powershellgallery/dt/PSRemoteOperations.png?style=for-the-badge&label=Downloads)](https://www.powershellgallery.com/packages/PSRemoteOperations/)
+
+
 This PowerShell module is designed to run commands on remote computers but _without_ using PowerShell remoting. It takes advantage of cloud services like Dropbox and OneDrive. The central concept is that you create a file with instructions about a command to run on a remote or target computer. The file includes the target computer name. The remote computer is monitoring a shared folder and when a matching file is detected the operation is invoked. The shared or common folder is managed by whatever cloud or other service of your choice.
 
 You can install the latest version from the PowerShell Gallery:
@@ -19,6 +22,8 @@ Or check out the individual commands:
 + [Register-PSRemoteOperationWatcher](docs/Register-PSRemoteOperationWatcher.md)
 + [Wait-PSRemoteOperation](docs/Wait-PSRemoteOperation.md)
 + [New-PSRemoteOperationForm](docs/New-PSRemoteOperationForm.md)
++ [Register-PSRemoteOpPath](docs/Register-PSRemoteOpPath.md)
++ [Import-PSRemoteOpPath](docs/Import-PSRemoteOpPath.md)
 
 ## Graphical Interface
 
@@ -36,4 +41,4 @@ This should work fine for simple script blocks. For anything more complicated, i
 
 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-08-10 17:03:11Z UTC
+Last updated 2019-08-20 13:13:32Z UTC

autocompleters.ps1

@@ -15,7 +15,7 @@ Register-ArgumentCompleter -CommandName Get-PSRemoteOperationResult, New-PSRemot
     }
 }
 
-Register-ArgumentCompleter -CommandName Wait-PSRemoteOperation,Get-PSRemoteOperation -ParameterName Computername -ScriptBlock {
+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
@@ -35,7 +35,30 @@ Register-ArgumentCompleter -CommandName New-PSRemoteOperation -ParameterName To
     param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
 
     (Get-ChildItem -Path Cert:\CurrentUser\my -DocumentEncryptionCert).Subject |
-    ForEach-Object {
+        ForEach-Object {
         [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
     }
+}
+
+<#
+Test for the json file with remote op path settings and prompt the user to run Register-PSRemoteOpPath if not found
+#>
+
+$json = Join-Path -path $PSScriptRoot -ChildPath psremoteoppath.json
+
+if (Test-Path $json) {
+    Import-PSRemoteOpPath -path $json
+}
+else {
+    $msg = @"
+No PSRemoteOpPath settings file was found to import. The module will be easier to use
+if you set global variables for `$PSRemoteOpPath and `$PSRemoteOpArchive. Run the
+commmand Register-PSRemoteOpPath. If you've recently updated the module through the
+PowerShell Gallery, you'll need to re-register the paths.
+
+If you prefer to set the values in your profile script you can ignore this
+warning.
+"
+"@
+    Write-Warning $msg
 }

changelog.md

@@ -1,5 +1,13 @@
 # Change Log for PSRemoteOperations
 
+## v3.3.0
+
++ Added commands `Register-PSRemoteOpPath` and `Import-PSRemoteOpPath` to store path variables with the module. (Issue #13)
++ Added better error handling to `Get-PSRemoteOperation` and `Get-PSRemoteOperationResult` when unprotecting a CMS message. (Issue #14)
++ Updated about help
++ Updated `README.md`
++ Updated Pester tests
+
 ## v3.2.1
 
 + Replaced online help links to markdown documents with bitly links

docs/Import-PSRemoteOpPath.md

@@ -0,0 +1,104 @@
+---
+external help file: PSRemoteOperations-help.xml
+Module Name: PSRemoteOperations
+online version:
+schema: 2.0.0
+---
+
+# Import-PSRemoteOpPath
+
+## SYNOPSIS
+
+Import path settings for the PSRemoteOperations module
+
+## SYNTAX
+
+```yaml
+Import-PSRemoteOpPath [[-Path] <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+This command will import the PSRemoteOPPath.json file in the module directory, and define the $PSRemoteOpPath and $PSRemoteOpArchive global variables. This settings file should be created with Register-PSRemoteOpPath. Normally, you should not need to run this command as settings are imported and defined when the module is imported.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+PS C:\> Register-PSRemoteOpPath
+```
+
+Manually import the settings.
+
+## PARAMETERS
+
+### -Confirm
+
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: cf
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Path
+
+Enter the path to the remote op path json file. You should normally use the default but you can specify an alternate path for testing purposes.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: 0
+Default value: $PSScriptRoot\psremoteoppath.json
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -WhatIf
+
+Shows what would happen if the cmdlet runs.
+The cmdlet is not run.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: wi
+
+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
+
+### System.Object
+
+## NOTES
+
+Learn more about PowerShell:
+http://jdhitsolutions.com/blog/essential-powershell-resources/
+
+## RELATED LINKS
+
+[Register-PSRemoteOpPath](./Register-PSRemoteOpPath.md)

docs/Register-PSRemoteOpPath.md

@@ -0,0 +1,127 @@
+---
+external help file: PSRemoteOperations-help.xml
+Module Name: PSRemoteOperations
+online version:
+schema: 2.0.0
+---
+
+# Register-PSRemoteOpPath
+
+## SYNOPSIS
+
+Register remote operations path
+
+## SYNTAX
+
+```yaml
+Register-PSRemoteOpPath [-PSRemoteOpPath] <String> [-PSRemoteOpArchive] <String> [-WhatIf] [-Confirm]
+ [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Many of the commands in this module rely on global variables to know where to store the pending remote operations file, $PSRemoteOpPath, and the archive folder, $PSRemoteOpArchive. Module commands that have a Path parameter default to these variables. In earlier versions of this module you could define these variables in PowerShell profile to avoid constantly having to enter them.
+
+This command will store your settings in a json file located in the module directory. When importing the module, the settings will also be imported and the global variables defined. If you don't have the settings file, you will see a warning message upon import.
+
+It is assumed the locations are shared or synchronized by some method or external application like Dropbox or OneDrive.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+
+PS C:\> Register-PSRemoteOpPath -PSRemoteOpPath $env:userprofile\dropbox\psremoteop -PSRemoteOpArchive $env:userprofile\dropbox\psremoteop\archive
+```
+
+Register the locations. Be aware that the paths will be converted to complete filesystem paths. Registration will also import the values.
+
+## PARAMETERS
+
+### -Confirm
+
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: cf
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -PSRemoteOpArchive
+
+Enter a filesystem path for the Remote Operations Archive path. It must already exist. This will be used to define $PSRemoteOpArchive.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -PSRemoteOpPath
+
+Enter a filesystem path for the Remote Operations path. It must already exist and should be shared folder that is managed by some other process or application such as Dropbox or OneDrive. This will be used to define $PSRemoteOpPath.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -WhatIf
+
+Shows what would happen if the cmdlet runs.
+The cmdlet is not run.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: wi
+
+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
+
+### None
+
+## NOTES
+
+Learn more about PowerShell:
+http://jdhitsolutions.com/blog/essential-powershell-resources/
+
+## RELATED LINKS
+
+[Import-PSRemoteOpPath](./Import-PSRemoteOpPath.md)
+