MS SQL server doesn’t support arrays or other collection data types, so we can’t directly send in these types as parameters to stored procedures from client applications. But fortunately, SQL does allow us to send in DataTable objects in MS SQL Server 2008 and later. The solution here is to simply convert our collection types into a DataTable object and then pass the DataTable into the stored procedure. This should work for any type that you can restructure into a table format.

Have an array of string or int? This can be converted into a table with one column with one row for each item in the array. Have a dictionary or other key-value pair collection? This becomes a table with two columns. Have a collection of class objects with multiple properties? Make a column for each class property and a row for each collection item.

Using table valued parameters makes it possible to send in a collection of items from your client application to the SQL server in a single roundtrip, without using XML or string parsing. This is helpful in several scenarios. For example, it is easier to delete a large number of records via stored procedure if you can call the delete procedure one time with a collection of record IDs instead of the same stored procedure over and over (one ID at a time). It also makes processing easier when you have other collections, such as key-value pairs that need to be passed into a stored procedure.

Note: At the time of this writing, table valued parameters are not supported for use in Linq to SQL. Hopefully this support is added in the future.

Step 1: Business objects

The first task is to address the business objects in the client. In the sample application I have defined a very simple class with two properties.

// code sample 1
/// <summary>
/// Defines a single item object.
/// </summary>
class Item
{
    /// <summary>
    /// Gets or sets the ID of the item.
    /// </summary>
    public Guid ID { get; set; }

    /// <summary>
    /// Gets or sets the Name of the item.
    /// </summary>
    public string Name { get; set; }
}

If we add conversion methods to the collection type, we can easily construct the required DataTable objects on demand. The first example extension returns a DataTable with the ID and Name properties of the business objects. The second example extension returns a DataTable with the ID of the each business object.

// code sample 2
/// <summary>
/// Defines a collection of item objects.
/// </summary>
class Items : List<Item>
{
    /// <summary>
    /// Returns the items as a DataTable.
    /// </summary>
    /// <returns><c>DataTable</c></returns>
    public DataTable GetItemsAsDataTable()
    {
        // construct the empty DataTable object with columns.
        DataTable table = new DataTable();
        table.Columns.Add("ID", typeof(Guid));
        table.Columns.Add("Name", typeof(string));

        // add a single row for each item in the collection.
        foreach (var item in this)
        {
            table.Rows.Add(item.ID, item.Name);
        }

        return table;
    }

    /// <summary>
    /// Returns only the item IDs as a DataTable.
    /// </summary>
    /// <returns><c>DataTable</c></returns>
    public DataTable GetItemIDsAsDataTable()
    {
        // construct the empty DataTable object with columns.
        DataTable table = new DataTable();
        table.Columns.Add("ID", typeof(Guid));

        // add a single row for each item in the collection.
        foreach (var item in this)
        {
            table.Rows.Add(item.ID);
        }

        return table;
    }
}

Step 2: SQL database prep

On the SQL server side we need to prepare the database to accept our table-valued parameters by defining them ahead of time. We then need to ensure that new or existing stored procedures are in place to accept these new table parameters.

For demo purposes I’m assuming that we need to create a database from scratch. Sample 3 (below) creates the following required objects:

• A new table to store our business object (Item)
• A user defined Table type to store Guids (IDs)
• A user defined Table type to store Guids (IDs) and Strings (Names)
• A stored procedure to remove items, using the table valued parameter.
• A stored procedure to add items, using the table valued parameter.

Note: that when a stored procedure uses a table-valued parameter, it must be passed as read-only. It cannot be modified inside the stored procedure. If it needs to be modified, then insert the rows into another table variable.

-- code sample 3
create table dbo.ItemsTable
(
	[ID]	uniqueidentifier primary key not null,
	[Name]	nvarchar(255) not null
)

create type dbo.IDsAndNamesTable as table
(
	[ID]	uniqueidentifier,
	[Name]	nvarchar(255)
)

create type dbo.IDsTable as table
(
	[ID]	uniqueidentifier
)
go

create procedure dbo.AddItems
(
	@Items	[IDsAndNamesTable] readonly
)
as
begin

	insert into dbo.ItemsTable ( [ID], [Name] )
	select [ID], [Name] from @Items 

end
go

create procedure dbo.RemoveItems
(
	@IDs	[IDsTable] readonly
)
as
begin

	delete from dbo.ItemsTable
	where [ID] in ( select [ID] from @IDs )

end
go

Step 3: Stored procedure execution

Once the business objects and the database are prepared, we can add client side code to call the stored procedures. To demonstrate calling the stored procedures and passing in the DataTables, I have added the following code to the sample application.

Note: The SqlDbType on the parameter is SqlDbType.Structured to indicate a user defined table type.

Also, at this location we convert the client collection type into a DataTable via the methods written earlier.

// code sample 4
/// <summary>
/// Adds items to the database.
/// </summary>
/// <param name="items">Collection of items to add.</param>
static void AddItemsToDatabase(Items items)
{
    // construct sql connection and sql command objects.
    using (SqlConnection sqlcon = new SqlConnection("<insert connection string here>"))
    {
        using (SqlCommand cmd = new SqlCommand("AddItems", sqlcon))
        {
            // add the table-valued-parameter. 
            cmd.CommandType = CommandType.StoredProcedure;
            cmd.Parameters.Add("@Items", SqlDbType.Structured).Value = items.GetItemsAsDataTable();

            // execute
            sqlcon.Open();
            cmd.ExecuteNonQuery();
        }
    }
}

/// <summary>
/// Removes items from the database.
/// </summary>
/// <param name="items">Collection of items to remove.</param>
static void RemoveItemsFromDatabase(Items items)
{
    // construct sql connection and sql command objects.
    using (SqlConnection sqlcon = new SqlConnection("<insert connection string here>"))
    {
        using (SqlCommand cmd = new SqlCommand("RemoveItems", sqlcon))
        {
            // add the table-valued-parameter. 
            cmd.CommandType = CommandType.StoredProcedure;
            cmd.Parameters.Add("@IDs", SqlDbType.Structured).Value = items.GetItemIDsAsDataTable();

            // execute
            sqlcon.Open();
            cmd.ExecuteNonQuery();
        }
    }
}

Now it’s time for a test run. In the main method I have decided to call the AddItems stored procedure just by passing in a collection:

// code sample 5
static void Main(string[] args)
{
    // add these new items

    Items items = new Items();
    items.Add(new Item() { ID = new Guid("EE612E96-1577-4C43-978D-1ACF6BE8A22D"), Name = "Orange" });
    items.Add(new Item() { ID = new Guid("55D000B9-51E7-43FD-9540-D24ACA711231"), Name = "Yellow" });
    items.Add(new Item() { ID = new Guid("89DAB4DD-35D2-4BFA-8735-9C6DCFC4110E"), Name = "Green" });
    items.Add(new Item() { ID = new Guid("F4E0965E-8501-4FFB-A1B7-1D08B6EF3DBC"), Name = "Red" });
    items.Add(new Item() { ID = new Guid("40F3DFAA-65CD-45EC-814F-3E59E46C95E2"), Name = "Blue" });
    items.Add(new Item() { ID = new Guid("A453B8C3-E9AF-447E-B847-FC7FA6D822AD"), Name = "Grey" });

    AddItemsToDatabase(items);
}

As expected, it inserted all the items:

I slightly re-arranged the main method to remove some of the existing items:

// code sample 6
static void Main(string[] args)
{
    // remove these existing items

    Items items = new Items();
    items.Add(new Item() { ID = new Guid("F4E0965E-8501-4FFB-A1B7-1D08B6EF3DBC"), Name = "Red" });
    items.Add(new Item() { ID = new Guid("40F3DFAA-65CD-45EC-814F-3E59E46C95E2"), Name = "Blue" });
    items.Add(new Item() { ID = new Guid("A453B8C3-E9AF-447E-B847-FC7FA6D822AD"), Name = "Grey" });

    RemoveItemsFromDatabase(items);
}

After execution we can see our items were removed correctly:

Conclusion

Table valued parameters allow you to pass tables full of data directly to a stored procedure. Using methods like the ones defined in code sample 2 will allow you to easily generate DataTables on demand from your client application. Since the custom DataTables can be defined according to your own specifications, there is no technical requirement to limit them to just one or two columns like the samples above. You can leverage them to fit whatever objects or columns that need to be passed in.

Hyper-V virtual machines regularly need to communicate bits of information back to the Hyper-V hosts. Items like the current IP address, Operating System version, guest integration components version, etc. Sometimes the Hyper-V host also needs to send messages to the VM Guest OS (like issuing a Shutdown command).

Hyper-V has built in a communication channel to send these commands back and forth, and fortunately we can leverage this system to send our own messages. This communication channel occurs over the KVP (key-value-pair) Data Exchange. The channel is accessed on the Hyper-V Host side via WMI, and is accessed on the Hyper-V guest OS side via the Windows Registry. Detailed access via C# is discussed in sections 2 and 3 of this post. If you want PowerShell code for that, a quick web search should find some samples.

This blog post covers the message send process through Hyper-V. It does not cover how to design your own messages, or the how to build a sender/listener service on either side. Those parts should be fairly straightforward once you understand how the sending process works.

How can I use this?

Sending messages to VMs via the Hyper-V KVP is a great way to command and control VMs you own that may not be on the same Network or Domain as the Hyper-V hosts or the rest of your infrastructure. Or for VMs that simply have no networking configured at all, but still need to communicate back to a central application.

What would a message look like?

The general idea is that you can format a message however you want (for example serialized XML), break it into chunks over KVP items, and write the message KVP items into the KVP store. You would write code for the other side that then reads the message chunks and deserializes it.

What are the limitations?

Sending messages certainly has limitations. I have never seen a documented message size limit for an individual message, but Hyper-V, WMI, and the Registry all have their own limitations for storing data in these locations that may vary by OS.

An individual KVP item has a key name, and a key value. In my own crude testing procedures, I was able to write a few hundred KVP items into the store. I observed that exceeding too many KVP items in the store, or too many characters in a key value would both lead to the Hyper-V integration services complaining. If this occurs, the VM may fall into a failed state which can be fixed by removing the message items. I recommend keeping message key values under 1024 characters.

Another requirement is that the data exchange service must be enabled on the Hyper-V VM for this to work. This is enabled by default in Hyper-V, but some environments may have it shut off for security reasons.

Part 2: Inside the Hyper-V Host Server

Part 2A: Prerequisites

The sample code below uses WMI. Add a project reference to System.Management.dll, and then add a using statement for it. All of the sample code below uses the WMI root\virtualization\v2 namespace. This namespace was introduced in Windows 8 / Server 2012. If you are using Windows 7 / Server 2008 R2, you will need to use the root\virtualization namespace instead. For more information, read this.

Part 2B: Sending messages to VMs

To send a message from the Host to the VM Guest, you need to add KVP items to the store via the AddKvpItems method on the Msvm_VirtualSystemManagementService WMI class.
Unfortunately the sample code on MSDN for this method is for adding a single KVP item. Sending large messages usually involves sending multiple KVP items at once, so here is a modified sample that sends in a collection of Key-Value pairs.

/// <summary>
/// Adds KVP Exchange Data items
/// </summary>
/// <param name="HyperVServerName">The Hyper-V Server hostname</param>
/// <param name="VirtualMachineName">Virtual Machine name as shown in Hyper-V manager</param>
/// <param name="VirtualMachineID">Virtual Machine unique ID as known by Hyper-V</param>
/// <param name="ItemsToAdd">Collection of key-value pair items to add</param>
public void AddKVPItems(string HyperVServerName, string VirtualMachineName, Guid VirtualMachineID, Dictionary<string, string> ItemsToAdd)
{
    // check all required parameters

    if (string.IsNullOrEmpty(HyperVServerName))
        throw new ArgumentNullException("HyperVServerName");

    if (string.IsNullOrEmpty(VirtualMachineName))
        throw new ArgumentNullException("VirtualMachineName");

    if (VirtualMachineID == Guid.Empty)
        throw new ArgumentException("VirtualMachineID cannot be empty");

    if (ItemsToAdd == null || ItemsToAdd.Count == 0)
        throw new ArgumentException("ItemsToAdd cannot be null or empty");

    // AddKvpItems() WMI Method does not allow more than 128 items in a single call. 
    // Very large messages will need to be broken down into message groups of 128 or less.

    if (ItemsToAdd.Count > 128)
        throw new ArgumentException("ItemsToAdd cannot contain more than 128 items");

    // create new scope object for the remote Hyper-V Host

    ManagementScope scope = new ManagementScope(string.Format(@"\\{0}\root\virtualization\v2", HyperVServerName));

    // find the Hyper-V Host Management object instance in the remote WMI

    ManagementPath wmiPath = new ManagementPath("Msvm_VirtualSystemManagementService");
    ManagementClass serviceClass = new ManagementClass(scope, wmiPath, null);
    ManagementObject hostInstance = null;
    foreach (ManagementObject item in serviceClass.GetInstances())
    {
        hostInstance = item;
    }

    if (hostInstance == null)
        throw new Exception(string.Format("Hyper-V Host ({0}) Management Object Instance was not found in WMI.", HyperVServerName));

    // find the Hyper-V Machine object instance in the remote WMI
    // it must match both the display name and the ID

    SelectQuery vmQuery = new SelectQuery(string.Format("SELECT * FROM Msvm_ComputerSystem WHERE ElementName = '{0}' AND Name = '{1}'", 
						VirtualMachineName, VirtualMachineID));
    ManagementObjectSearcher vmSearcher = new ManagementObjectSearcher(scope, vmQuery);
    ManagementObject vmInstance = null;
    foreach (ManagementObject item in vmSearcher.Get())
    {
        vmInstance = item;
    }

    if (vmInstance == null)
        throw new Exception(string.Format("Virtual Machine ({0}, {1}) WMI instance was not found on the Hyper-V Host {2}.", 
					VirtualMachineID, VirtualMachineName, HyperVServerName));

    // prepare objects for method execution.
    // get the method parameters for AddKvpItems()
    // populate the kvpItems array with new instances of Msvm_KvpExchangeDataItem

    ManagementClass kvpClass = new ManagementClass(scope, new ManagementPath("Msvm_KvpExchangeDataItem"), null);
    ManagementBaseObject kvpParams = hostInstance.GetMethodParameters("AddKvpItems");
    string[] kvpItems = new string[ItemsToAdd.Count];

    int arrayCounter = 0;
    foreach (KeyValuePair<string, string> kvpItem in ItemsToAdd)
    {
        // create a new instance of a KVP Exchange data item
        // for each item that needs to be added

        ManagementObject kvpInstance = kvpClass.CreateInstance();
        kvpInstance.Properties["Name"].Value = kvpItem.Key;
        kvpInstance.Properties["Data"].Value = kvpItem.Value;
        kvpInstance.Properties["Source"].Value = 0;

        // save this new instance back to the items array
        // text must be formatted first

        kvpItems[arrayCounter] = kvpInstance.GetText(TextFormat.CimDtd20);
        arrayCounter++;
    }

    // finalize parameters and invoke the WMI method

    kvpParams["TargetSystem"] = vmInstance.Path.Path;
    kvpParams["DataItems"] = kvpItems;
    ManagementBaseObject outParams = hostInstance.InvokeMethod("AddKvpItems", kvpParams, null);

    if ((UInt32)outParams["ReturnValue"] == WMIReturnCode.Started)
    {
        // the Job has started, but not finished yet.
        // grab an instance of the WMI Job object and wait until the Job is completed or failed.

        ManagementObject Job = new ManagementObject(scope, new ManagementPath((string)outParams["Job"]), null);

        if (Job == null)
            throw new Exception("WMI Job has successfully started, but we were unable to locate the WMI Job object instance.");

        if (JobCompleted(Job) == false)
        {
            throw new Exception(string.Format("WMI Job failed with error: {0}, {1}", Job["ErrorCode"], Job["ErrorDescription"]));
        }
    }
    else if ((UInt32)outParams["ReturnValue"] == WMIReturnCode.Completed)
    {
        // Job has completed successfully.
    }
    else
    {
        throw new Exception(string.Format("WMI Job failed to start with error: {0}", outParams["ReturnValue"]));
    }

    if (kvpParams != null)
    {
        kvpParams.Dispose();
    }

    if (outParams != null)
    {
        outParams.Dispose();
    }
}

Part 2C: Reading messages written by VMs

To read a message written by a VM, we grab the instance of the Virtual Machine WMI object (Msvm_ComputerSystem), and then use a related object query to pull the KVP items in the GuestInstrinsicExchangeItems property on Msvm_KvpExchangeComponent.

/// <summary>
/// Gets KVP Exchange Data items that were added from inside a VM
/// </summary>
/// <param name="HyperVServerName">The Hyper-V Server hostname</param>
/// <param name="VirtualMachineName">Virtual Machine name as shown in Hyper-V manager</param>
/// <param name="VirtualMachineID">Virtual Machine unique ID as known by Hyper-V</param>
/// <returns>Collection of KVP Exchange data items</returns>
public Dictionary<string, string> GetVMAddedKVPItems(string HyperVServerName, string VirtualMachineName, Guid VirtualMachineID)
{
    // check all required parameters

    if (string.IsNullOrEmpty(HyperVServerName))
        throw new ArgumentNullException("HyperVServerName");

    if (string.IsNullOrEmpty(VirtualMachineName))
        throw new ArgumentNullException("VirtualMachineName");

    if (VirtualMachineID == Guid.Empty)
        throw new ArgumentException("VirtualMachineID cannot be empty");

    // create new scope object for the remote Hyper-V Host

    ManagementScope scope = new ManagementScope(string.Format(@"\\{0}\root\virtualization\v2", HyperVServerName));

    // find the Hyper-V Machine object instance in the remote WMI
    // it must match both the display name and the ID

    SelectQuery vmQuery = new SelectQuery(string.Format("SELECT * FROM Msvm_ComputerSystem WHERE ElementName = '{0}' AND Name = '{1}'", 
						VirtualMachineName, VirtualMachineID));
    ManagementObjectSearcher vmSearcher = new ManagementObjectSearcher(scope, vmQuery);
    ManagementObject vmInstance = null;
    foreach (ManagementObject item in vmSearcher.Get())
    {
        vmInstance = item;
    }

    if (vmInstance == null)
        throw new Exception(string.Format("Virtual Machine ({0}, {1}) WMI instance was not found on the Hyper-V Host {2}.", 
					VirtualMachineID, VirtualMachineName, HyperVServerName));

    // kvp exchange data items are found via the related object query

    RelatedObjectQuery kvpQuery = new RelatedObjectQuery("Associators of {" + vmInstance.ToString() + 
					"} Where AssocClass=Msvm_SystemDevice ResultClass=Msvm_KvpExchangeComponent");
    ManagementObjectSearcher kvpSearcher = new ManagementObjectSearcher(scope, kvpQuery);
    ManagementObject kvpCollectionInstance = null;
    foreach (ManagementObject item in kvpSearcher.Get())
    {
        kvpCollectionInstance = item;
    }

    if (kvpCollectionInstance == null)
        throw new Exception(string.Format("Virtual Machine ({0}, {1}) KVPExchangeComponent items were not found.", 
					VirtualMachineID, VirtualMachineName));

    // translate the raw KVP Items into a results collection and return
    string[] kvp = kvpCollectionInstance.Properties["GuestIntrinsicExchangeItems"].Value as string[];
    return TranslateKVPDataItems(kvp);
}

Part 2D: Reading messages written by Host

To read a message written by the Hyper-V Host, we grab the instance of the Virtual Machine WMI object (Msvm_ComputerSystem), and then use a related object query to pull the KVP items in the HostExchangeItems property on Msvm_KvpExchangeComponentSettingData. Note this is not the same class as used in step 2C.

/// <summary>
/// Gets KVP Exchange Data items that were added from the Hyper-V Host
/// </summary>
/// <param name="HyperVServerName">The Hyper-V Server hostname</param>
/// <param name="VirtualMachineName">Virtual Machine name as shown in Hyper-V manager</param>
/// <param name="VirtualMachineID">Virtual Machine unique ID as known by Hyper-V</param>
/// <returns>Collection of KVP Exchange data items</returns>
public Dictionary<string, string> GetHostAddedKVPItems(string HyperVServerName, string VirtualMachineName, Guid VirtualMachineID)
{
    // check all required parameters

    if (string.IsNullOrEmpty(HyperVServerName))
        throw new ArgumentNullException("HyperVServerName");

    if (string.IsNullOrEmpty(VirtualMachineName))
        throw new ArgumentNullException("VirtualMachineName");

    if (VirtualMachineID == Guid.Empty)
        throw new ArgumentException("VirtualMachineID cannot be empty");

    // create new scope object for the remote Hyper-V Host

    ManagementScope scope = new ManagementScope(string.Format(@"\\{0}\root\virtualization\v2", HyperVServerName));

    // find the Hyper-V Machine object instance in the remote WMI
    // it must match both the display name and the ID

    SelectQuery vmQuery = new SelectQuery(string.Format("SELECT * FROM Msvm_ComputerSystem WHERE ElementName = '{0}' AND Name = '{1}'", 
						VirtualMachineName, VirtualMachineID));
    ManagementObjectSearcher vmSearcher = new ManagementObjectSearcher(scope, vmQuery);
    ManagementObject vmInstance = null;
    foreach (ManagementObject item in vmSearcher.Get())
    {
        vmInstance = item;
    }

    if (vmInstance == null)
        throw new Exception(string.Format("Virtual Machine ({0}, {1}) WMI instance was not found on the Hyper-V Host {2}.", 
					VirtualMachineID, VirtualMachineName, HyperVServerName));

    // find the related KVP Component

    ManagementObject kvpExchangeComponent = null;
    foreach (ManagementObject item in vmInstance.GetRelated("Msvm_KvpExchangeComponent"))
    {
        kvpExchangeComponent = item;
        break; // grab the first item and break
    }

    if (kvpExchangeComponent == null)
        throw new Exception(string.Format("Virtual Machine ({0}, {1}) KVPExchangeComponent Host item was not found.", 
				VirtualMachineID, VirtualMachineName));

    ManagementObject kvpExchangeComponentSettingData = null;
    foreach (ManagementObject item in kvpExchangeComponent.GetRelated("Msvm_KvpExchangeComponentSettingData"))
    {
        kvpExchangeComponentSettingData = item;
        break; // grab the first item and break
    }

    if (kvpExchangeComponentSettingData == null)
        throw new Exception(string.Format("Virtual Machine ({0}, {1}) KVPExchangeComponentSettingData Host item was not found.", 
					VirtualMachineID, VirtualMachineName));

    // translate the raw KVP Items into a results collection and return

    string[] xmlItems = kvpExchangeComponentSettingData.Properties["HostExchangeItems"].Value as string[];
    return TranslateKVPDataItems(xmlItems);
}

Part 2E: Removing messages

To remove messages from the KVP Store via WMI on the Host, we need to call the RemoveKvpItems method on the Msvm_VirtualSystemManagementService WMI class.
Just like AddKvpItems, the sample code on MSDN is only for removing a single KVP item. The following is a modified example for removing a group of items.

/// <summary>
/// Removes KVP Exchange Data items
/// </summary>
/// <param name="HyperVServerName">The Hyper-V Server hostname</param>
/// <param name="VirtualMachineName">Virtual Machine name as shown in Hyper-V manager</param>
/// <param name="VirtualMachineID">Virtual Machine unique ID as known by Hyper-V</param>
/// <param name="ItemsToRemove">Array of item key names to remove</param>
public void RemoveKVPItems(string HyperVServerName, string VirtualMachineName, Guid VirtualMachineID, string[] ItemsToRemove)
{
    // check all required parameters

    if (string.IsNullOrEmpty(HyperVServerName))
        throw new ArgumentNullException("HyperVServerName");

    if (string.IsNullOrEmpty(VirtualMachineName))
        throw new ArgumentNullException("VirtualMachineName");

    if (VirtualMachineID == Guid.Empty)
        throw new ArgumentException("VirtualMachineID cannot be empty");

    if (ItemsToRemove == null || ItemsToRemove.Length == 0)
        throw new ArgumentException("ItemsToRemove cannot be null or empty");

    // RemoveKvpItems() WMI Method does not allow more than 128 items in a single call. 
    // Very large messages will need to be broken down into message groups of 128 or less.

    if (ItemsToRemove.Length > 128)
        throw new ArgumentException("ItemsToRemove cannot contain more than 128 items");

    // create new scope object for the remote Hyper-V Host

    ManagementScope scope = new ManagementScope(string.Format(@"\\{0}\root\virtualization\v2", HyperVServerName));

    // find the Hyper-V Host Management object instance in the remote WMI

    ManagementPath wmiPath = new ManagementPath("Msvm_VirtualSystemManagementService");
    ManagementClass serviceClass = new ManagementClass(scope, wmiPath, null);
    ManagementObject hostInstance = null;
    foreach (ManagementObject item in serviceClass.GetInstances())
    {
        hostInstance = item;
    }

    if (hostInstance == null)
        throw new Exception(string.Format("Hyper-V Host ({0}) Management Object Instance was not found in WMI.", HyperVServerName));

    // find the Hyper-V Machine object instance in the remote WMI
    // it must match both the display name and the ID

    SelectQuery vmQuery = new SelectQuery(string.Format("SELECT * FROM Msvm_ComputerSystem WHERE ElementName = '{0}' AND Name = '{1}'", 
						VirtualMachineName, VirtualMachineID));
    ManagementObjectSearcher vmSearcher = new ManagementObjectSearcher(scope, vmQuery);
    ManagementObject vmInstance = null;
    foreach (ManagementObject item in vmSearcher.Get())
    {
        vmInstance = item;
    }

    if (vmInstance == null)
        throw new Exception(string.Format("Virtual Machine ({0}, {1}) WMI instance was not found on the Hyper-V Host {2}.", 
				VirtualMachineID, VirtualMachineName, HyperVServerName));

    // prepare objects for method execution
    // get the method parameters for RemoveKvpItems()
    // populate the kvpItems array with new instances of Msvm_KvpExchangeDataItem

    ManagementClass kvpClass = new ManagementClass(scope, new ManagementPath("Msvm_KvpExchangeDataItem"), null);
    ManagementBaseObject kvpParams = hostInstance.GetMethodParameters("RemoveKvpItems");
    string[] kvpItems = new string[ItemsToRemove.Length];

    for (int i = 0; i < ItemsToRemove.Length; i++)
    {
        // create a new instance of a KVP Exchange data item
        // for each item that needs to be removed

        ManagementObject kvpInstance = kvpClass.CreateInstance();
        kvpInstance.Properties["Name"].Value = ItemsToRemove[i];
        kvpInstance.Properties["Data"].Value = string.Empty; // pass string empty, since only the Item Name needs to match
        kvpInstance.Properties["Source"].Value = 0;

        // save this new instance back to the items array
        // text must be formatted first

        kvpItems[i] = kvpInstance.GetText(TextFormat.CimDtd20);
    }

    // finalize parameters and invoke the WMI method

    kvpParams["TargetSystem"] = vmInstance.Path.Path;
    kvpParams["DataItems"] = kvpItems;
    ManagementBaseObject outParams = hostInstance.InvokeMethod("RemoveKvpItems", kvpParams, null);

    if ((UInt32)outParams["ReturnValue"] == WMIReturnCode.Started)
    {
        // the Job has started, but not finished yet.
        // grab an instance of the WMI Job object and wait until the Job is completed or failed.

        ManagementObject Job = new ManagementObject(scope, new ManagementPath((string)outParams["Job"]), null);

        if (Job == null)
            throw new Exception("WMI Job has successfully started, but we were unable to locate the WMI Job object instance.");

        if (JobCompleted(Job) == false)
        {
            throw new Exception(string.Format("WMI Job failed with error: {0}, {1}", Job["ErrorCode"], Job["ErrorDescription"]));
        }
    }
    else if ((UInt32)outParams["ReturnValue"] == WMIReturnCode.Completed)
    {
        // Job has completed successfully.
    }
    else
    {
        throw new Exception(string.Format("WMI Job failed to start with error: {0}", outParams["ReturnValue"]));
    }

    if (kvpParams != null)
    {
        kvpParams.Dispose();
    }
 
    if (outParams != null)
    {
        outParams.Dispose();
    }
}

Part 2F: Helper classes

The code samples above use the following helper classes.

/// <summary>
/// Translates raw KVP Exchange Data item XML nodes into a results collection
/// </summary>
/// <remarks>
/// The kvp data items returned from WMI are a blob of XML that can be translated into a collection of usable key-value pairs.
/// </remarks>
/// <param name="kvpXmlNodes">Array of KVP Exchange Data items</param>
/// <returns>Collection of key-value pair items</returns>
private Dictionary<string, string> TranslateKVPDataItems(string[] kvpXmlNodes)
{
    if (kvpXmlNodes == null)
        throw new ArgumentNullException("kvpXmlNodes");

    Dictionary<string, string> KVPItems = new Dictionary<string, string>();

    foreach (string xmlString in kvpXmlNodes)
    {
        // each string contains an XML document with XmlElements
        // load the XML string into a Document object for processing

        XmlDocument d = new XmlDocument();
        d.LoadXml(xmlString);

        string Name = null;
        string Value = null;

        foreach (XmlElement property in d.SelectNodes("/INSTANCE/PROPERTY"))
        {
            if (string.IsNullOrEmpty(property.InnerText) == false)
            {
                // this element has data in it (InnerText not null)
                // look at the attributes for this element to find out if this is the Name or the Value portion of the KVP item

                foreach (XmlAttribute attrib in property.Attributes)
                {
                    if (attrib.Value == "Name")
                    {
                        Name = property.InnerText;
                    }
                    if (attrib.Value == "Data")
                    {
                        Value = property.InnerText;
                    }
                }
            }
        }

        if (string.IsNullOrEmpty(Name) == false && string.IsNullOrEmpty(Value) == false && KVPItems.ContainsKey(Name) == false)
        {
            // Found a KVP item that has Name and Value fields populated
            // Also it does not already exist in the results collection

            KVPItems.Add(Name, Value);
        }
    }

    return KVPItems;
}

/// <summary>
/// Waits until a WMI Job is completed
/// </summary>
/// <param name="Job">WMI Job object</param>
/// <returns>True if Job success, False if Job failure</returns>
private bool JobCompleted(ManagementObject Job)
{
    // Capture latest Job status
    Job.Get();

    // Is the job still in progress or starting?
    // If yes, then sleep and check job status again until completed.
    while ((UInt16)Job["JobState"] == WMIJobState.Starting || (UInt16)Job["JobState"] == WMIJobState.Running)
    {
        System.Threading.Thread.Sleep(500);
        Job.Get();
    }

    // return the success/failure of the job
    UInt16 jobState = (UInt16)Job["JobState"];
    if (jobState != WMIJobState.Completed)
    {
        return false;
    }
    else
    {
        return true;
    }
}

/// <summary>
/// WMI Job State class enumeration
/// </summary>
public static class WMIJobState
{
    public const UInt16 New = 2;
    public const UInt16 Starting = 3;
    public const UInt16 Running = 4;
    public const UInt16 Suspended = 5;
    public const UInt16 ShuttingDown = 6;
    public const UInt16 Completed = 7;
    public const UInt16 Terminated = 8;
    public const UInt16 Killed = 9;
    public const UInt16 Exception = 10;
    public const UInt16 Service = 11;
}

/// <summary>
/// WMI Method Invoke return code class enumeration
/// </summary>
public static class WMIReturnCode
{
    public const UInt32 Completed = 0;
    public const UInt32 Started = 4096;
    public const UInt32 Failed = 32768;
    public const UInt32 AccessDenied = 32769;
    public const UInt32 NotSupported = 32770;
    public const UInt32 Unknown = 32771;
    public const UInt32 Timeout = 32772;
    public const UInt32 InvalidParameter = 32773;
    public const UInt32 SystemInUse = 32774;
    public const UInt32 InvalidState = 32775;
    public const UInt32 IncorrectDataType = 32776;
    public const UInt32 SystemNotAvailable = 32777;
    public const UInt32 OutofMemory = 32778;
}

Part 3: Inside the Guest VM Operating System

Part 3A: Sending

Writing messages back to the host is as simple as writing to the registry. Inside the Hyper-V Guest OS, the registry key “HKLM\SOFTWARE\Microsoft\Virtual Machine\Auto” stores the messages to be read by the Hyper-V Host. Write the keys and values as new string value entries.

You can see that this location already hosts several key/values that Hyper-V uses internally to communicate OS information back to the Host. This registry key location should always exist on Hyper-V guest operating systems, assuming that they have integration services components installed.

/// <summary>
/// Registry key location for the Guest outgoing KVP Items.
/// </summary>
private const string KVPOutgoingRegistryKey = @"SOFTWARE\Microsoft\Virtual Machine\Auto";

/// <summary>
/// Writes outgoing KVP messages to the registry.
/// </summary>
/// <param name="ItemsToAdd">Collection of items to add</param>
public void SendGuestKVPItems(Dictionary<string, string> ItemsToAdd)
{
    if (ItemsToAdd == null || ItemsToAdd.Count == 0)
        throw new ArgumentNullException("ItemsToAdd");

    foreach (var item in ItemsToAdd)
    {
        // write the value to the registry

        Registry.SetValue("HKEY_LOCAL_MACHINE\\" + KVPOutgoingRegistryKey, item.Key, item.Value);
    }
}

Part 3B: Receiving

Reading messages sent from the Host to the VM is similar to step 3A in that it involves the registry. We just open and read the registry key “HKLM\SOFTWARE\Microsoft\Virtual Machine\External”. Inside this location will be any key-value pair items that were written from the Host and floated down to the VM. Simply read the message items, and reconstruct the message or instruction in your desired format.

Unless you have been sending messages, this key is usually empty:

/// <summary>
/// Registry key location for the Guest incoming KVP Items.
/// </summary>
private const string KVPIncomingRegistryKey = @"SOFTWARE\Microsoft\Virtual Machine\External";

/// <summary>
/// Reads the Host KVP Data Exchanges items.
/// </summary>
/// <returns>Collection of key/value pairs.</returns>
public Dictionary<string, string> ReadHostKVPItems()
{
    Dictionary<string, string> KvpItems = new Dictionary<string, string>();

    using (RegistryKey HostKey = Registry.LocalMachine.OpenSubKey(KVPIncomingRegistryKey))
    {
        if (HostKey == null)
        {
            // this would indicate the host registry key doesn't exist.
            // the only time this should happen is on a machine that isn't a hyper-v VM
            // or we don't have access to open the key.

            throw new Exception("Host KVP Registry key not found.");
        }

        // read the key value names
        string[] ValueNames = HostKey.GetValueNames();

        if (ValueNames.Length == 0)
            return KvpItems; // no items found!

        foreach (string keyValueName in ValueNames)
        {
            // capture the value as a string
            // returns string empty if the key value is null.

            string keyValue = Registry.GetValue("HKEY_LOCAL_MACHINE\\" + KVPIncomingRegistryKey, keyValueName, string.Empty) as string;

            // add to the collection.

            KvpItems.Add(keyValueName, keyValue);
        }
    }

    return KvpItems;
}

Prerequisites:

First, ensure that PowerShell 2.0 or later is installed on the system you are developing on. The features used below will not be supported on PowerShell 1.0. Next, start by making a new console application (targeting .NET 4.0) in Visual Studio.

In the solution explorer, add a project reference to the System.Management.Automation assembly*. On my machine (PowerShell 3.0), it was located at C:\Program Files (x86)\Reference Assemblies\Microsoft\WindowsPowerShell\3.0. Then, add using statements for the above referenced assembly, along with System.Collections.Objectmodel, which is used later for execution output.

Note: You will need to install the Windows SDK in order to obtain the System.Management.Automation assembly file.
Note: You do not have to distribute the System.Management.Automation assembly file with your application binaries - it is located in the GAC on machines with Windows PowerShell installed and should resolve automatically.

Prepare the Pipeline for execution:

The first step is to create a new instance of the PowerShell class. The static method PowerShell.Create() creates an empty PowerShell pipeline for us to use for execution. The PowerShell class implements IDisposable, so remember to wrap it up in a using block.

    using (PowerShell PowerShellInstance = PowerShell.Create())
    {
    }

Next, we can add scripts or commands to execute. Call the AddScript() and AddCommand() methods to add this content to the execution pipeline. If your script has parameters, adding them is easy with the AddParameter() method. AddParameter() accepts a string parameter name, and object for the parameter value. Feel free to pass in full object instances/types if you want. The scripts and pipeline handle it just fine. No need to limit yourself with only passing in string values.

The string contents supplied to AddScript() can come from anywhere. Good choices may be text loaded from files on disk or embedded resources, or user input. For the purposes of this tutorial, I’m just hard-coding some example script text.

    using (PowerShell PowerShellInstance = PowerShell.Create())
    {
        // use "AddScript" to add the contents of a script file to the end of the execution pipeline.
        // use "AddCommand" to add individual commands/cmdlets to the end of the execution pipeline.
        PowerShellInstance.AddScript("param($param1) $d = get-date; $s = 'test string value'; " +
                "$d; $s; $param1; get-service");

        // use "AddParameter" to add a single parameter to the last command/script on the pipeline.
        PowerShellInstance.AddParameter("param1", "parameter 1 value!");
    }

Script/Command Execution:

So far, we have a PowerShell pipeline populated with script code and parameters. There are two ways we can call PowerShell to execute it: synchronously and asynchronously.

Synchronous execution:

For synchronous execution, we call PowerShell.Invoke(). The caller waits until the script or commands have finished executing completely before returning from the call to Invoke(). If you don’t care about the items in the output stream, the simplest execution looks like this:

    // invoke execution on the pipeline (ignore output)
    PowerShellInstance.Invoke();

For situations where you don’t need to see or monitor the output or results of execution, this may be acceptable. But, in other scenarios you probably need to peek at the results or perform additional processing with the output that comes back from PowerShell. Let’s see what that code looks like:

    // invoke execution on the pipeline (collecting output)
    Collection<PSObject> PSOutput = PowerShellInstance.Invoke();

    // loop through each output object item
    foreach (PSObject outputItem in PSOutput)
    {
        // if null object was dumped to the pipeline during the script then a null
        // object may be present here. check for null to prevent potential NRE.
        if (outputItem != null)
        {
            //TODO: do something with the output item 
            // outputItem.BaseOBject
        }
    }

The return object from Invoke() is a collection of PSObject instances that were written to the output stream during execution. PSObject is a wrapper class that adds PowerShell specific functionality around whatever the base object is. Inside the PSObject is a member called BaseObject, which contains an object reference to the base type you are working with. If nothing was written to the output stream, then the collection of PSObjects will be empty.

Besides the standard output stream, there are also dedicated streams for warnings, errors, debug, progress, and verbose logging. If any cmdlets leverage those streams, or you call them directly (write-error, write-debug, etc.), then those items will appear in the streams collections.

After invoking the script, you can check each of these stream collections to see if items were written to them.

    // invoke execution on the pipeline (collecting output)
    Collection<PSObject> PSOutput = PowerShellInstance.Invoke();

    // check the other output streams (for example, the error stream)
    if (PowerShellInstance.Streams.Error.Count > 0)
    {
        // error records were written to the error stream.
        // do something with the items found.
    }

In my sample script supplied above, I am writing a few manually-created objects to the output stream and calling the get-service cmdlet, which also writes its output to the stream since I didn’t save the output in a variable.

As a test, I write the type name and ToString() on all of the base objects that came back from the sample script. As you can see, accessing the base object allows you to view or manipulate the object directly as needed. The base types that come back from execution are usually standard .NET types you may already be familiar with, just wrapped up in a PSObject.

    // loop through each output object item
    foreach (PSObject outputItem in PSOutput)
    {
        // if null object was dumped to the pipeline during the script then a null
        // object may be present here. check for null to prevent potential NRE.
        if (outputItem != null)
        {
            //TODO: do something with the output item 
            Console.WriteLine(outputItem.BaseObject.GetType().FullName);
            Console.WriteLine(outputItem.BaseObject.ToString() + "\n");
        }
    }

Asynchronous execution:

For asynchronous execution, we call PowerShell.BeginInvoke(). BeginInvoke() immediately returns to the caller and the script execution begins in the background so you can perform other work. Unlike the synchronous Invoke() method, the return type of BeginInvoke() is not a collection of PSObject instances from the output stream. The output isn’t ready yet. The caller is given an IAsyncResult object to monitor the status of the execution pipeline. Let’s start with a really simple example:

    using (PowerShell PowerShellInstance = PowerShell.Create())
    {
        // this script has a sleep in it to simulate a long running script
        PowerShellInstance.AddScript("start-sleep -s 7; get-service");

        // begin invoke execution on the pipeline
        IAsyncResult result = PowerShellInstance.BeginInvoke();

        // do something else until execution has completed.
        // this could be sleep/wait, or perhaps some other work
        while (result.IsCompleted == false)
        {
            Console.WriteLine("Waiting for pipeline to finish...");
            Thread.Sleep(1000);

            // might want to place a timeout here...
        }

        Console.WriteLine("Finished!");
    }

Note: If you wrap the PowerShell instance in a using block like the sample above and do not wait for execution to complete, the pipeline will close itself, and will abort script execution, when it reaches the closing brace of the using block. You can avoid this by waiting for completion of the pipeline, or by removing the using block and manually calling Dispose() on the instance at a later time.

In this first asynchronous example, we ignored the output stream. Again, this is only useful if you don’t care about your script results. Fortunately, the BeginInvoke() method has a few overloads that allow us to extend the functionality. Let’s improve the example by adding output collection and event handling for data hitting the pipeline.

First, we will create a new instance of PSDataCollection<PSObject>. This collection is a thread-safe buffer that will store output stream objects as they hit the pipeline. Next, we will subscribe to the DataAdded event on this collection. This event will fire every time an object is written to the output stream. To use this new output buffer, pass it as a parameter to BeginInvoke().

I added some other functionality and comments to the next code block. First, notice that you can check the state of the pipeline to see its status. The State will equal Completed when your script is done. If State is Failed, it is likely caused by an unhandled exception that occurred in the script, also known as a terminating error. Second, if your scripts utilize write-error, write-debug, write-progress, etc. (all thread-safe collections), you can review these during or after execution to check for items logged there. I have subscribed to the DataAdded event on the Error stream as well to be notified in real time.

    /// <summary>
    /// Sample execution scenario 2: Asynchronous
    /// </summary>
    /// <remarks>
    /// Executes a PowerShell script asynchronously with script output and event handling.
    /// </remarks>
    public void ExecuteAsynchronously()
    {
        using (PowerShell PowerShellInstance = PowerShell.Create())
        {
            // this script has a sleep in it to simulate a long running script
            PowerShellInstance.AddScript("$s1 = 'test1'; $s2 = 'test2'; $s1; write-error 'some error';start-sleep -s 7; $s2");

            // prepare a new collection to store output stream objects
            PSDataCollection<PSObject> outputCollection = new PSDataCollection<PSObject>();
            outputCollection.DataAdded += outputCollection_DataAdded;

            // the streams (Error, Debug, Progress, etc) are available on the PowerShell instance.
            // we can review them during or after execution.
            // we can also be notified when a new item is written to the stream (like this):
            PowerShellInstance.Streams.Error.DataAdded += Error_DataAdded;

            // begin invoke execution on the pipeline
            // use this overload to specify an output stream buffer
            IAsyncResult result = PowerShellInstance.BeginInvoke<PSObject, PSObject>(null, outputCollection);

            // do something else until execution has completed.
            // this could be sleep/wait, or perhaps some other work
            while (result.IsCompleted == false)
            {
                Console.WriteLine("Waiting for pipeline to finish...");
                Thread.Sleep(1000);

                // might want to place a timeout here...
            }

            Console.WriteLine("Execution has stopped. The pipeline state: " + PowerShellInstance.InvocationStateInfo.State);

            foreach (PSObject outputItem in outputCollection)
            {
                //TODO: handle/process the output items if required
                Console.WriteLine(outputItem.BaseObject.ToString());
            }
        }
    }

    /// <summary>
    /// Event handler for when data is added to the output stream.
    /// </summary>
    /// <param name="sender">Contains the complete PSDataCollection of all output items.</param>
    /// <param name="e">Contains the index ID of the added collection item and the ID of the PowerShell instance this event belongs to.</param>
    void outputCollection_DataAdded(object sender, DataAddedEventArgs e)
    {
        // do something when an object is written to the output stream
        Console.WriteLine("Object added to output.");
    }

    /// <summary>
    /// Event handler for when Data is added to the Error stream.
    /// </summary>
    /// <param name="sender">Contains the complete PSDataCollection of all error output items.</param>
    /// <param name="e">Contains the index ID of the added collection item and the ID of the PowerShell instance this event belongs to.</param>
    void Error_DataAdded(object sender, DataAddedEventArgs e)
    {
        // do something when an error is written to the error stream
        Console.WriteLine("An error was written to the Error stream!");
    }

As you can see above, the complete asynchronous model allows for some pretty interesting scenarios with long-running scripts. We can listen for events like data being added to the output stream. We can monitor the progress stream to see how much longer a task may take and provide feedback to the UI. We can listen for new errors being written to the error stream and react accordingly, instead of waiting until all execution has completed.

Execution Policy:

When you invoke cmdlets through the PowerShell class in C#, the execution policy behavior is subject to the policy restrictions of the machine. This behavior is the same is if you opened up a PowerShell prompt on the machine. You can issue commands just fine, but invoking another script might get blocked if your execution policy is undefined or restricted in some way. An easy way to get around this is to set the execution policy for the scope of the application process. Simply run Set-ExecutionPolicy and specify the scope to be Process. This should allow you to invoke secondary scripts without altering the machine/user policies. For more information about policies and their order of precedence, see here.

Shared Namespace:

To wrap up our discussion, I’d like to share a potentially useful feature that can expand some of the functionality for your scripts. When you use the PowerShell class to invoke a script, that script has access to the classes inside the caller’s namespace, if they were declared public.

In the example code below, we make a public class with a single public property, and a public static class with a single public method. Both of these items exist in the same namespace as the PowerShell executor code. The script we execute creates a new instance of the class, sets the property, and writes it to the pipeline. The static class and method are then called directly from inside the script, saving the results to a string which is then written to the pipeline as well.

namespace PowerShellExecutionSample
{
    /// <summary>
    /// Test class object to instantiate from inside PowerShell script.
    /// </summary>
    public class TestObject
    {
        /// <summary>
        /// Gets or sets the Name property
        /// </summary>
        public string Name { get; set; }
    }

    /// <summary>
    /// Test static class to invoke from inside PowerShell script.
    /// </summary>
    public static class TestStaticClass
    {
        /// <summary>
        /// Sample static method to call from insider PowerShell script.
        /// </summary>
        /// <returns>String message</returns>
        public static string TestStaticMethod()
        {
            return "Hello, you have called the test static method.";
        }
    }

    /// <summary>
    /// Provides PowerShell script execution examples
    /// </summary>
    class PowerShellExecutor
    {
        /// <summary>
        /// Sample execution scenario 3: Namespace test
        /// </summary>
        /// <remarks>
        /// Executes a PowerShell script synchronously and utilizes classes in the callers namespace.
        /// </remarks>
        public void ExecuteSynchronouslyNamespaceTest()
        {
            using (PowerShell PowerShellInstance = PowerShell.Create())
            {

                // add a script that creates a new instance of an object from the caller's namespace
                PowerShellInstance.AddScript("$t = new-object PowerShellExecutionSample.TestObject;" + 
                                             "$t.Name = 'created from inside PowerShell script'; $t;" +
                                             "$message = [PowerShellExecutionSample.TestStaticClass]::TestStaticMethod(); $message");

                // invoke execution on the pipeline (collecting output)
                Collection<PSObject> PSOutput = PowerShellInstance.Invoke();

                // loop through each output object item
                foreach (PSObject outputItem in PSOutput)
                {
                    if (outputItem != null)
                    {
                        Console.WriteLine(outputItem.BaseObject.GetType().FullName);

                        if (outputItem.BaseObject is TestObject)
                        {
                            TestObject testObj = outputItem.BaseObject as TestObject;
                            Console.WriteLine(testObj.Name);
                        }
                        else
                        {
                            Console.WriteLine(outputItem.BaseObject.ToString());
                        }
                    }
                }
            }
        }
    }
} 

As we can see from the console output, the public static class and non-static class were both available from inside the script for use. The ability to leverage public members from the caller’s namespace allows you to create some interesting scenarios calling C# code directly from your PowerShell scripts.

We encounter enum types frequently when using PowerShell cmdlets. For anyone who isn’t familiar, an enum is an enumeration of named constants; essentially, a static list of options or choices. A good example of this is when you run Get-VM in Hyper-V to examine a Virtual Machine. The State property of the Virtual Machine object displays whether the VM is Running, Stopped, Saved, etc.

Instead of storing this data in a text/string field, this object is stored as an enum type. This means there are limited and defined possible choices this value can be – and it will never fall outside of these possible values. This becomes really helpful in scripts for the consumer of the cmdlet to make logic decisions based on the value (such as the leveraging the switch statement).

How do we know the property is an enum type?

Utilize the GetType() method found on any object inside PowerShell (or, the .NET Framework). In the example below we have run GetType() against both the Name and State properties of the VM object. As seen in the output the base type for State is System.Enum. This means we have an enum type.

How do we find the other possible enumeration values?

If the VM is currently in Running state, what other possible states exist? This is a very common question that arises when working with enums. The answer is usually found in the cmdlet documentation, but this is not always the case. Follow these steps to retrieve the answer on your own:

First, locate the full name of the enumeration type. Extract the FullName property from the enum, as depicted below.

Second, call the GetValues() static method on the enum type. Be sure to enclose the full type name inside square brackets. Example with desired output is below.

Note 1: If you attempt to use GetValues() on the partial type name (VMState) instead of the full type name (Microsoft.HyperV.PowerShell.VMState), PowerShell is likely going to complain that it can’t find the type. Ensure you use the full type name.

Note 2: A newer PSv3 only method to accomplish this same task is to call [Microsoft.HyperV.PowerShell.VMState].GetEnumValues().

Capturing enumeration Integer values:

To take it one step further, you can also find the associated integer values of the enumeration. This can be useful in certain programming scenarios.

Here is a one-liner to accomplish that. All we do is cast the enumeration value to int and print it to the screen along with the text value.

The first requirement is to understand the types of errors that can occur during execution.

Terminating vs. Non-Terminating Errors:

• Terminating Error: A serious error during execution that halts the command (or script execution) completely. Examples can include non-existent cmdlets, syntax errors that would prevent a cmdlet from running, or other fatal errors.
• Non-Terminating Error: A non-serious error that allows execution to continue despite the failure. Examples include operational errors such file not found, permissions problems, etc.

Update 12/13/2013: Writing a cmdlet? For further information regarding how a cmdlet should determine when to throw a terminating error or non-terminating error, MSDN has a nice explanation here.

Update 12/13/2013: Want to know if an error you encountered is terminating or non-terminating? Check to see if the error behavior is affected by changing the $ErrorActionPreference. According to the MSDN documentation here, "Neither $ErrorActionPreference nor the ErrorAction common parameter affect how Windows PowerShell responds to terminating errors (those that stop cmdlet processing).".

The $error variable:

When either type of error occurs during execution, it is logged to a global variable called $error. This variable is a collection of PowerShell Error Objects with the most recent error at index 0. On a freshly initialized PowerShell instance (no errors have occurred yet) the $error variable is ready and waiting as an empty collection: 

 
In the next snippet I have executed a cmdlet that doesn’t exist, throwing an error. If we grab the count on $error, you will notice it has increased to one item. Dumping that object to the pipeline by accessing $error[0] just prints the error we already saw, right back at us.

 
There is more available to us than just what is immediately visible. The ErrorRecord is a rich object that contains many useful properties to explore. Try piping the error to get-member (aliased by gm) to see what options we have available to us:

For details on what each property member provides, visit the ErrorRecord MSDN documentation. A couple important highlights:

• $error[0].InvocationInfo provides details about the context which the command was executed, if available.
• $error[0].Exception contains the original exception object as it was thrown to PowerShell. If we explore that object (also piped to get-member) we can see important items to pull up like stack trace, source, HResult, InnerException, etc.

Diving into the exception object itself ($error[0].Exception) can provide very important diagnostic details not immediately visible on the top level error record. This is especially useful in troubleshooting third party cmdlets!

Error Action Preference:

PowerShell halts execution on terminating errors, as mentioned before. For non-terminating errors we have the option to tell PowerShell how to handle these situations. This is where the error action preference comes in. Error Action Preference allows us to specify the desired behavior for a non-terminating error; it can be scoped at the command level or all the way up to the script level.

Available choices for error action preference:

• SilentlyContinue – error messages are suppressed and execution continues.
• Stop – forces execution to stop, behaving like a terminating error.
• Continue - the default option. Errors will display and execution will continue.
• Inquire – prompt the user for input to see if we should proceed.
• Ignore – (new in v3) – the error is ignored and not logged to the error stream. Has very restricted usage scenarios.

Example: Set the preference at the script scope to Stop, place the following near the top of the script file:

Example: Set the preference at the cmdlet level to Inquire, add error action switch (or alias EA): 

Try/Catch/Finally Blocks:

The Try, Catch, and Finally statements allow us to control script flow when we encounter errors. The statements behave similar to the statements of the same name found in C# and other languages.

The behavior of try/catch is to catch terminating errors (exceptions). This means Non-terminating (operational) errors inside a try block will not trigger a Catch*. If you would like to catch all possible errors (terminating and non-terminating) – then simply set the error action preference to Stop. Remember that Stop error action forces a non-terminating error to behave like a terminating error, which means it can then be trapped in a catch block. Here is an example:

*Update 12/13/2013: In almost all cases, non-terminating errors will not trigger a catch. However I did recently observe a situation where a non-terminating error did trigger a catch block. It wasn't from a cmdlet, but an exception generated from directly calling a method on a .net object. So keep in mind that behavior might be possible.

 
You can also have Catch blocks that will only trap specific exceptions. The reason for doing this is so you can add different handlers for each possible failure condition that you may encounter. Some exceptions you may just want to log and exit, but others you may have a recovery action for. Here is a Catch statement that would trap a specific Exception type. The Exception type is displayed in brackets after the catch statement:

 
You might be wondering how I found the type name for the previous exception. The possible exceptions for cmdlets are not usually documented, so you may need to find them on your own. When an exception occurs you can look up the error in the $error collection, or while inside a catch block under the $_ variable. Call the GetType() method on the base exception to extract the FullName property. Like shown here:

Handling Errors from non-PowerShell processes:

What happens when your script needs to run an external process from PowerShell and you want to know if it succeeded? An example would be a cmdline tool such as robocopy.exe. It’s an external application that returns an exit code upon completion. But since it is an external process, its errors will not be caught in your try/catch blocks.

To trap this exit code utilize the $LastExitCode PowerShell variable.

When the launched process exits, PowerShell will write the exit code directly to $LastExitCode. In most cases an exit code of 0 means success, and 1 or greater indicates a failure. Check the external tool's documentation to verify of course.

Here it is seen in action: