Powershell

This module provides a way to run the most commonly used PowerShell commands for Windows.

Note

It’s required to install rdp from Optional dependencies section.

class aiviro.modules.powershell.ShellCommands(rdp_robot: RDPRobot, timeout: int | None = None, as_admin: bool | None = None, use_likely_area: bool | None = None, sleep_time: int | None = None)

Class contains the most commonly used powershell Windows commands. Every command is called using start_process() method.

Parameters:

  • rdp_robot – Instance of RDPRobot

  • timeout – Timeout for finding the Windows “Run” window.

  • as_admin – If True, commands are executed as an admin.

  • use_likely_area – If True, the area more likely to find the “Run” window is used (bottom left side of the screen).

  • sleep_time – Implicit sleep between sub-commands execution

execute()

Executes the constructed commands.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).remove_file("C:/user/Documents/*").stop_process("notepad").execute()
open_explorer(*path: str | PureWindowsPath) → ShellCommands

Opens Windows Explorer at the specified path.

Warning

When specifying a drive, include the suffix :/. Otherwise, it is treated as a folder. If only : is specified, the path points to the current working directory of the drive. Always use X:/ for the root location of drive X.

Parameters:

path – Path to a folder

Example:

>>> import pathlib
>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> shell_cmd = ShellCommands(rdp_robot=r)
>>> # Here are some examples how to specify the path
>>> shell_cmd.open_explorer("c:/", "Users", "your_account").execute()
>>> shell_cmd.open_explorer(pathlib.PureWindowsPath("c:/") / "Users" / "your_account").execute()
>>> shell_cmd.open_explorer("c:/", pathlib.PureWindowsPath("Users", "your_account")).execute()
remove_file(*path: str | PureWindowsPath, recursive: bool = False) → ShellCommands

Removes file or all files in a folder.

Parameters:

  • path – Path to a file or folder.

  • recursive – If True, sub-folders are also removed.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).remove_file("C:/Users/me/Documents/*").execute()
stop_process(*process_name: str, force: bool = True, restart_explorer: bool = False) → ShellCommands

Closes the specified application.

Parameters:

  • process_name – Name of the process (e.g., “notepad”, “your_application.exe”).

  • force – If True, applications are force-closed; otherwise, they are gracefully closed.

  • restart_explorer – If True, Explorer is also restarted.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r, as_admin=True).stop_process("notepad", "your_application.exe").execute()
close_all_open_windows(force: bool = True) → ShellCommands

Closes all open windows.

Parameters:

force – If True, applications are force-closed; otherwise, they are gracefully closed.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).close_all_open_windows().execute()
create_directory(*path: str | PureWindowsPath, open: bool = False) → ShellCommands

Creates a new directory.

Parameters:

  • path – Path to the new directory.

  • open – If True, the newly created directory is opened.

Example:

>>> import pathlib
>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> shell_cmd = ShellCommands(rdp_robot=r)
>>> # Here are some examples how to specify the path
>>> shell_cmd.create_directory("c:/", "Users", "your_account").execute()
>>> shell_cmd.create_directory(pathlib.PureWindowsPath("c:/") / "Users" / "your_account").execute()
>>> shell_cmd.create_directory("c:/", pathlib.PureWindowsPath("Users", "your_account"), open=True).execute()
move_file(source_path: str | PureWindowsPath, destination_path: str | PureWindowsPath, create_output_directory: bool = False, force: bool = False) → ShellCommands

Moves a file from the source path to the destination path.

Parameters:

  • source_path – Source path of the file.

  • destination_path – Destination path of the file.

  • create_output_directory – If True, the output directory is created.

  • force – If True, the command runs without asking for user confirmation.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).move_file(
...     "c:/path/file.pdf",
...     "c:/path/folder/file.pdf",
...     create_output_directory=True
... ).execute()
copy_file(source_path: str | PureWindowsPath, destination_path: str | PureWindowsPath, recursive: bool = False, force: bool = False) → ShellCommands

Copies a file from the source path to the destination path.

Parameters:

  • source_path – Source path of the file.

  • destination_path – Destination path of the file.

  • recursive – If True, performs a recursive copy.

  • force – If True, copies items that cannot otherwise be changed, such as copying over a read-only file.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).copy_file(
...     "c:/path/file.pdf",
...     "c:/path/folder/file.pdf",
... ).execute()
copy_file_into_clipboard(file_path: str | PureWindowsPath) → ShellCommands

Copies a file into the remote (guest’s) clipboard. This command can be combined with transfer_files_from_guests_clipboard().

Note

The file is copied from the remote machine into the clipboard of the remote machine, not the host machine.

Parameters:

file_path – Path to a file.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).copy_file_into_clipboard("c:/path/file.pdf").execute()
>>> r.transfer_files_from_guests_clipboard("some/local/dir/")
["some/local/dir/file.pdf"]
paste_file_from_clipboard(destination_dir: str | PureWindowsPath, create_destination_directory: bool = False) → ShellCommands

Pastes a file from the clipboard into the destination folder.

Note

The file is pasted into the remote machine from the clipboard of the remote machine, not the host machine.

Parameters:

  • destination_dir – Folder where the file will be pasted.

  • create_destination_directory – If True, the destination directory is created.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).paste_file_from_clipboard("c:/destination/dir/").execute()
create_and_copy_powershell_script(script_content: str, script_name: str) → ShellCommands

Creates a PowerShell script file and copies it to the remote machine via a shared folder. Use this method in case you need to execute a complex and long script on the remote machine.

Warning

The shared folder must be set in a RDPRobot for this functionality to work. See create_rdp_robot() for more information.

Parameters:

  • script_content – Content of the powershell script.

  • script_name – Name of the script, should contain “.ps1” file extension.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot(shared_folder="folder-name")
>>> windows_folder = "C:/users/me/Documents"
>>> ShellCommands(r).create_and_copy_powershell_script(rf"dir {windows_folder}").execute()