Overview of Devolutions PowerShell

Devolutions products fully integrate Microsoft PowerShell, offering powerful scripting and automation capabilities. You can control Devolutions products themselves and, through Remote Desktop Manager, run PowerShell scripts across your environment. With that in mind, here is how PowerShell is used across the Devolutions platform.

Integration	Purpose	Reference
Devolutions.PowerShell module	This PowerShell module is used to interact directly with Devolutions products.	PowerShell Gallery
Remote Desktop Manager actions	You may define a PowerShell script to run as a batch action against one or more hosts.	Custom PowerShell commands Batch edit with PowerShell Modifying a synchronizer source
Remote Desktop Manager reports	This entry type supports running a PowerShell script to generate a report.	Custom PowerShell report
Remote Desktop Manager entry types	Both the PowerShell local and PowerShell remote entry types support running scripts.
Privileged access management (PAM) providers and password propagation	Within Devolutions Server and Devolutions Cloud, PowerShell powers custom PAM providers and password propagation scripts.	Devolutions Server custom PAM provider Devolutions Server PAM password propagation scripts

Getting started with the Devolutions.PowerShell module

The Devolutions.PowerShell module requires PowerShell 7.4 or later, and is supported on Windows, macOS, and Linux operating systems.

Windows PowerShell or earlier versions of PowerShell 7 are not supported because the module is built from the same core as Remote Desktop Manager, and therefore requires a version of PowerShell using a compatible version of the .NET runtime (.NET 9).

PowerShell Gallery (recommended)

The Devolutions.PowerShell module is available in the PowerShell Gallery and it is the recommended default installation method:

Install-Module Devolutions.PowerShell -Force

Since the PowerShell Gallery is usually a repository marked as untrusted (packages are not curated or reviewed), using -Force is required to avoid the confirmation prompt.

Cloudsmith

As an alternative to the PowerShell Gallery, we offer a Devolutions PowerShell repository hosted by Cloudsmith.

1. Register the Devolutions PowerShell repository, which can be marked as trusted:

   Register-PSRepository -Name 'Devolutions' -SourceLocation 'https://nuget.cloudsmith.io/devolutions/powershell/v2/' -InstallationPolicy Trusted

2. Uninstall previous versions of the Devolutions.PowerShell module installed from the PowerShell Gallery:

   Uninstall-Module Devolutions.PowerShell -AllVersions

3. Install the Devolutions.PowerShell module explicitly from the "Devolutions" repository:

   Install-Module Devolutions.PowerShell -Repository Devolutions

4. Confirm that the installation source repository for the Devolutions.PowerShell module is "Devolutions" and not "PSGallery":

   Get-InstalledModule Devolutions.PowerShell | Select-Object -Property Name, Repository
   
   Name                   Repository
   ----                   ----------
   Devolutions.PowerShell Devolutions

Since the Devolutions.PowerShell module is available in more than one registered repository, the -Repository parameter becomes mandatory. However, if you've marked the "Devolutions" repository as trusted, -Force is unnecessary to avoid the confirmation prompt.

Offline

If you need to install the Devolutions.PowerShell module on a system with limited or no Internet access, you can do so by following these steps:

1. Create a new PowerShell repository called "local" in your chosen directory; the example below uses C:\PSRepo.

   $RepoPath = "C:\PSRepo"
   New-Item -Path $RepoPath -ItemType 'Directory' -Force | Out-Null
   Register-PSRepository -Name 'local' -SourceLocation $RepoPath -PublishLocation $RepoPath -InstallationPolicy Trusted

2. Download the .nupkg file for the Devolutions.PowerShell module using the Download the raw nupkg file button under Manual Download in the PowerShell Gallery. Copy the .nupkg file to the previously created, local PowerShell repository directory.
3. Uninstall previous versions of the Devolutions.PowerShell module installed from other sources.

   Uninstall-Module Devolutions.PowerShell -AllVersions

4. Install the Devolutions.PowerShell module explicitly from the local repository.

   Install-Module Devolutions.PowerShell -Repository local

5. Confirm that the installation source for the Devolutions.PowerShell module is local.

   Get-InstalledModule Devolutions.PowerShell | Select-Object -Property Name, Repository
   
   Name                   Repository
   ----                   ----------
   Devolutions.PowerShell local

Alternatively, a directory on a network share can be used instead of a local directory, making it easier to distribute the PowerShell module on a local network.

Examples

To quickly get started with some common Devolutions.PowerShell module examples, read on below.

Remote Desktop Manager

# [Import module]
Import-Module Devolutions.PowerShell

# [Load workspace] Example for a local workspace (SQLite) or SQL Server
$DatasourceLocal = Get-RDMDataSource -Name "Local workspace"; Set-RDMCurrentDataSource $DatasourceLocal

$DatasourceSQL = Get-RDMDataSource -Name "SQL Server"; Set-RDMCurrentDataSource $DatasourceSQL

# [Create vault] Only the SQL Server workspace supports vaults (as do Devolutions Server and Devolutions Cloud)
$Vault = New-RDMRepository -Name 'MyVault' -Description 'My vault description' -SetRepository | Set-RDMCurrentRepository | Update-RDMUI

# [Retrieve vault]
Get-RDMRepository -Name 'MyVault'

# [Create entry] Example to create an RDP and Credential entry
$Entry = New-RDMSession -Host 'MyHost' -Type RDPConfigured -Name 'MyHost'; Set-RDMSession -Session $Entry -Refresh; Update-RDMUI

$Entry = New-RDMSession -Name 'MyCredential' -Type Credential; $Entry.Credentials.Username = 'Administrator'; Set-RDMSession $Entry -Refresh; Set-RDMSessionPassword -ID $Entry.ID -Password (ConvertTo-SecureString 'Test123$' -AsPlainText -Force)

# [Retrieve entries]
Get-RDMSession -GroupName 'MyFolder' -Name 'MyHost'

# [Update entry]
$Entry = Get-RDMSession -Name 'MyHost'; $Entry.Name = 'MyUpdatedHost'; Set-RDMSEssion $Entry | Update-RDMUI

# [Export entries]
$Entries = Get-RDMSession; $Entries | Select-Object * | Export-CSV 'C:\Export\FileName.csv' -NoTypeInformation

# [Remove entry]
Get-RDMSession -Name 'MyUpdatedHost' | Remove-RDMSession; Update-RDMUI

Devolutions Server

# [Import module]
Import-Module Devolutions.PowerShell

# [Load workspace]
New-DSSession -Credential (Get-Credential) -BaseURI 'https://MyServer/devolutions-server/'

# [Create vault]
$Vault = New-DSVault -Name 'MyVault' -Description 'My vault description'

# [Retrieve vault]
Get-DSVault -All | Where-Object DisplayName -EQ 'MyVault'

# [Create entry]
New-DSRDPEntry -Name 'MyHost' -HostName 'MyHost' -Username 'Administrator' -Password 'Test123$' -Domain 'MyDomain' -VaultID 'VaultGUID'

New-DSCredentialEntry -Name 'MyCredential' -Username 'Administrator' -Password 'Test123$' -Domain 'MyDomain' -VaultID 'VaultGUID'

# [Retrieve entries]
Get-DSEntry -FilterBy 'Name' -FilterMatch 'StartsWith' -FilterValue 'MyHost' -SearchAllVaults

# [Update entry]
$Entry = Get-DSEntry -EntryId 'EntryGUID'; $Entry.Name = 'MyUpdatedHost'; Update-DSEntryBase -JsonBody (ConvertTo-JSON -InputObject $Entry -Depth 10)

# [Export entries]
$Entries = Get-DSEntry -SearchAllVaults; $Entries | Select-Object * | Export-CSV 'C:\Export\FileName.csv' -NoTypeInformation

# [Remove entry]
Remove-DSEntry -EntryID 'EntryGUID'

Devolutions Cloud

# [Import module]
Import-Module Devolutions.PowerShell

# [Load workspace]
Connect-HubAccount -Url 'https://mycloud.devolutions.app' -ApplicationKey 'ApplicationKey' -ApplicationSecret 'ApplicationSecret'

# [Create vault]
$Vault = New-HubVault -VaultName 'MyVault' -VaultDescription 'My vault description'

# [Retrieve vault]
Get-HubVault

# [Create entry]
$Entry = [Devolutions.Hub.PowerShell.Entities.Hub.PSDecryptedEntry]@{
    PsMetadata = [Devolutions.Hub.PowerShell.Entities.Hub.PSEntryMetadata]@{
        Name = 'MyHost'
        ConnectionType = [Devolutions.RemoteDesktopManager.ConnectionType]::Credential
    }
    Connection = [Devolutions.RemoteDesktopManager.Business.Connection]@{
        Credentials = [Devolutions.RemoteDesktopManager.Business.CredentialsConnection]@{
            CredentialType = [Devolutions.RemoteDesktopManager.CredentialResolverConnectionType]::Default
            UserName = 'Administrator'
            Password = 'Test123$'
        }
    }
}

New-HubEntry -VaultId 'VaultGUID' -PSDecryptedEntry $Entry

# [Retrieve entries]
Get-HubEntry -VaultId 'VaultGUID' | Where-Object { $PSItem.PSMetaData.Name -EQ 'MyHost' }

# [Update entry]
$Entry = Get-HubEntry -VaultId 'VaultGUID' -EntryId 'EntryGUID'; $Entry.PsMetadata.Name = 'MyUpdatedHost'; Set-HubEntry -VaultId 'VaultGUID' -EntryId $Entry.Entry.ID.Guid -PSDecryptedEntry $Entry

# [Export entries]
$Entries = Get-HubEntry -VaultId 'VaultGUID'; $Entries | Select-Object * | Export-CSV 'C:\Export\FileName.csv' -NoTypeInformation

# [Remove entry]
Remove-HubEntry -VaultId 'VaultGUID' -EntryId 'EntryGUID'

Uninstalling the Devolutions.PowerShell module

Uninstall all versions of the Devolutions.PowerShell module:

Uninstall-Module Devolutions.PowerShell -AllVersions

If the module is installed via Cloudsmith, you may unregister the "Devolutions" repository like so:

Unregister-PSRepository Devolutions

Finally, if you have installed the module offline, you may unregister the "local" file-based repository and delete the associated directory (your directory name may be different):

Unregister-PSRepository local
Remove-Item "C:\PSRepo" -Recurse -ErrorAction SilentlyContinue