Windows PowerShell MVP Jeff Hicks wrote a neat PowerShell module that gives us a head start on managing VirtualBox virtual machines (VMs) programmatically. Jeff clearly put a lot of work into that project (the commands even include comment-based help!), but as we’ll get into later, there are some gaps that we in the PowerShell community may want to fill. Let’s begin.
Latest posts by Timothy Warner (see all)

Getting started

Download Jeff’s PSVirtualBox module and place the extracted folder into your PSModulePath:

C:\Program Files\WindowsPowerShell\Modules

Now we’ll invoke Get-Command to see what functionality Jeff added to his module:

Get-Command -Module PSVirtualBox | Select-Object -Property CommandType, Name
CommandType Name
----------- ----
   Function Get-VBoxMachine
   Function Get-VBoxProcess
   Function Get-VirtualBox
   Function Start-VBoxMachine
   Function Stop-VBoxMachine
   Function Suspend-VBoxMachine

I know Jeff. He is not, by his own admission, a .NET programmer. Therefore, Jeff wrote advanced functions to give us the functionality. That fact doesn’t affect us as end users, however, because PowerShell advanced functions behave the same way as C# or VB cmdlets do.

What’s great about Jeff’s use of advanced functions is that he makes the project source code available to us, as shown in the following screen capture:

We can modify the PSVirtualBox source code

We can modify the PSVirtualBox source code.

NOTE: Be sure to provide proper attribution if you modify and re-release Jeff’s PSVirtualBox project. Jeff told me a few months ago that he set up a GitHub repository for this project.

Interacting with virtual machines

The Get-VirtualBox command simply echoes a bunch of metadata concerning the VirtualBox COM object. If you’re a developer, then I’m sure your hackles rose a bit at my mention of Component Object Model (COM).

Believe it or not, VirtualBox doesn’t have a .NET Framework–based entry point. Instead, it uses the antiquated COM interface. That fact severely limits the degree to which we can interact with VirtualBox VMs.

Anyway, let’s enumerate our VirtualBox VMs:

Get-VBoxMachine -All
ID          : b41cc962-ab89-4018-8a71-54dee6ec9ebb
Name        : devbox
Description :
MemoryMB    : 2048
State       : Stopped
OS          : Windows81_64

Now we’ll start up my devbox Windows 8.1 VM:

Start-VBoxMachine -Name devbox -Verbose

Start-VBoxMachine -Name devbox -Verbose
	VERBOSE: Starting Start-VBoxMachine
	VERBOSE: Creating a session object
	VERBOSE: Ending Start-VBoxMachine

So far, so good! As you can see below, my VM started right up and I’m ready to roll.

Starting a VM with Windows PowerShell

Starting a VM with Windows PowerShell

Jeff also added a -Headless switch parameter to Start-VBoxMachine if you don’t need the GUI.

We can take advantage of the PowerShell pipeline to suspend our virtual machine:

Get-VBoxMachine -Name devbox | Suspend-VBoxMachine

Now we see that our VM displays in a Saved state:

Get-VBoxMachine -All
ID          : b41cc962-ab89-4018-8a71-54dee6ec9ebb
Name        : devbox
Description :
MemoryMB    : 2048
State       : Saved
OS          : Windows81_64

To bring this full circle, we’ll resume the saved VM:

Start-VBoxMachine -name devbox

Resuming our virtual machine

Resuming our virtual machine

NOTE: VM names are case sensitive.

Stopping the VM programmatically involves the (surprise, surprise!) Stop-VBoxMachine command:

Stop-VBoxMachine -Name devbox

In keeping with Windows PowerShell development best practices, Jeff documented all the module commands, including examples. So, for instance:

Get-Help -Name Get-VBoxMachine -ShowWindow

You can learn a lot by reading PowerShell documentation

You can learn a lot by reading PowerShell documentation.

Next steps

Jeff’s PSVirtualBox module is a fantastic head start, but in my opinion it needs much more work before we can consider it a fully functional project. Here’s what I think we need:

Add more robust VM metadata. I’d like to see all VM properties and settings from PowerShell instead of just the name, OS, and RAM.

Create new VMs. This is perhaps the most obvious omission from the module. Once we can deploy new VirtualBox VMs from PowerShell, we’re really cooking with gas.

Verify networking. As you probably know, hypervisors have software-defined networking (SDN) that can involve Internet access, VM-to-host access, and VM-to-VM access. It would be awesome to do SDN testing from within PowerShell.

The way you can get involved in the PSVirtualBox improvement project is to fork Jeff’s PSVirtualBox repository at GitHub. By doing this, you’ll accomplish the following goals:

  • You make valuable contributions to the Windows PowerShell community.
  • You get some experience with Git code repositories and GitHub hosting.
  • You hone your skills with PowerShell advanced functions.
1 Comment
  1. Avatar
    Ron 8 years ago

    First thank you so much. Great work.
    I have windows 8.1 .Net 4.5
    I have about 6 virtual box machines.
    Running Get-VBoxMachine -All reports them all but very often reports machines that are running as stopped. Is there anything i can do?
    Thanks you

Leave a reply

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2023


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account