Appendix A: About Windows PowerShell for Virtual Machine Manager

Article
01/17/2008

You can use the Windows PowerShell - Virtual Machine Manager command shell to perform all administrative functions in Virtual Machine Manager either interactively from the command line or through the use of scripts. For those not yet familiar with either Windows PowerShell or Virtual Machine Manager, this appendix explains the relationship between the two technologies.

How Virtual Machine Manager Uses Windows PowerShell

Windows PowerShell and Virtual Machine Manager each provide commands (called cmdlets) that you can use separately to perform simple administrative tasks or together with other cmdlets or command-line elements to perform complex tasks.

The Virtual Machine Manager command shell includes all of the standard Windows PowerShell cmdlets and also provides a comprehensive set of cmdlets that are designed specifically for use with Virtual Machine Manager. You can use these cmdlets to manage all functions in a Virtual Machine Manager environment, including the following tasks:

Adding and working with virtual machine hosts and host groups
Adding the Virtual Machine Manager library and maintaining the resources that it stores
Creating and working with virtual machines that are deployed on a host or stored in the library
Managing the virtual machine environment
Creating virtual machine checkpoints
Backing up the Virtual Machine Manager database
Administering the virtual machine self-service feature

Windows PowerShell and Virtual Machine Manager differentiate between commands and cmdlets as follows:

Cmdlet. A cmdlet is a single-feature command that is used to interact with any managed application, including Virtual Machine Manager, and the operating system. A cmdlet is typically formatted as a verb-noun pair separated by a dash (such as Get-VirtualNetwork). The verb acts on a Windows PowerShell object (the noun).
Most cmdlets are simple but designed to work in combination with other cmdlets. For example, the “Get” cmdlets only retrieve data and the “Set” cmdlets only specify or change data.
Example of a Virtual Machine Manager cmdlet:
```
Get-VMCheckPoint
```
Command. A command might or might not include one or more cmdlets. Examples of commands that do not include cmdlets are 2+2 or the assignment of a value or an array of values to a variable, such as $IntegerArray = @(0,1,2,3,4,5,6,7,8,9). However, assigning a value to a variable often does include the use of a cmdlet, such as $Credential = Get-Credential, which prompts you for Active Directory credentials (<DomainName>\<UserName> and password) and then stores those credentials in the variable $Credential. A command can use a pipeline operator (|) to pass the output of one cmdlet to another cmdlet as input.
Example of a Virtual Machine Manager command that uses the pipeline operator:
```
Get-VMCheckpoint -MostRecent | where { $_.VM -eq "VM01" } | Restore-VMCheckpoint
```

Customers who have installed Virtual Machine Manager can access both standard Windows PowerShell cmdlets and Virtual Machine Manager cmdlets at the Virtual Machine Manager command-line interface. Windows PowerShell command-line Help for the standard Windows PowerShell cmdlets is provided with Windows; command-line Help for Virtual Machine Manager cmdlets is provided with the Virtual Machine Manager product.

How a Snap-in Provides Virtual Machine Manager Cmdlets

Windows PowerShell is installed with a set of built-in snap-ins. These Windows PowerShell snap-ins contain:

Providers. The standard Windows PowerShell providers provide access to various data stores in a format that is modeled on the file system interface in Windows.
Cmdlets. The standard Windows PowerShell cmdlets are available for use with any server product that supports Windows PowerShell, including Virtual Machine Manager.

For example, the Microsoft.PowerShell.Core snap-in includes the FileSystem, Registry, Alias, Environment, Function, and Variable providers and also includes basic cmdlets such as Get-Help, Get-Command, and Get-History.

Like other Microsoft server products, such as Microsoft Exchange Server or Microsoft System Center Operations Manager 2007, Virtual Machine Manager extends the standard functionality of Windows PowerShell by providing its own Windows PowerShell snap-in. The Virtual Machine Manager snap-in for Windows PowerShell does not include a separate Windows PowerShell provider for Virtual Machine Manager, but it does provide a set of Virtual Machine Manager cmdlets. You can use these cmdlets with, or as an alternative to, the Virtual Machine Manager Administrator Console to manage your servers and virtual machines.

To see the complete list of Windows PowerShell snap-ins

On a Virtual Machine Manager server on which the Administrator Console for Virtual Machine Manager is installed, click Start, point to All Programs, point to Microsoft System Center Virtual Machine Manager 2007, and then click Windows PowerShell – Virtual Machine Manager to open the command shell.
At the command prompt, type the following command to list the Virtual Machine Manager cmdlets:
```
Get-PSSnapin
```
Review the command output and confirm that the list includes an entry called VirtualMachineManagerSnapin

To list the Virtual Machine Manager cmdlets

At the command prompt, type the following command:

Get-Command -PSSnapin VirtualMachineManagerSnapin

Confirm that the output lists the Virtual Machine Manager cmdlets.

The first cmdlet listed is Add-LibraryServer and the last cmdlet is Update-VMMManagedComputer.

How the Administrator Console Uses Virtual Machine Manager Cmdlets

The Virtual Machine Manager Administrator Console is built on Windows PowerShell. Most server administrators do not need an in-depth understanding, at the programmatic level, of the interaction between the Administrator Console and Windows PowerShell. However, the following synopsis of the standard call sequence for any hypothetical Administrator Console operation illustrates the integration of Windows PowerShell and the Administrator Console:

The Administrator Console makes a call to a Windows PowerShell cmdlet.
The Windows PowerShell cmdlet makes a Windows Communication Foundation call to the Virtual Machine Manager server service.
Virtual Machine Manager initiates a job if the operation changes state or is long-running and, therefore, needs to be audited or monitored asynchronously.
Virtual Machine Manager makes SQL calls, as necessary, to read and update the Virtual Machine Manager database.
Virtual Machine Manager makes Windows Remote Management (WinRM) calls, as necessary, to access remote hosts on which virtual machines are deployed or to access remote library servers on which Virtual Machine Manager library resources are stored.
WinRM calls, in turn, access Windows Management Instrumentation (WMI) methods on Virtual Machine Manager hosts or library servers. These WMI methods ship either in the operating system or as part of the Virtual Machine Manager agent service.
Some of these WMI methods, in turn, call the Virtual Server component object model application programming interface (COM API).

All operations that you perform by using the Administrator Console in Virtual Machine Manager are actually performing these tasks.

How Objects Represent All Entities in Virtual Machine Manager

All entities in a Virtual Machine Manager environment are represented as an object. This section provides a brief introduction to the use of objects in Windows PowerShell in the context of Virtual Machine Manager.

Windows PowerShell, although it is based on object-oriented programming and Microsoft .NET Framework classes, does not require server administrators to gain an exhaustive knowledge of these topics. On the contrary, Windows PowerShell is designed to enable server administrators to learn quickly how to manipulate objects either interactively at the command-line or through scripting.

How Managing Objects Is More Efficient Than Text-Based Processing

One of the most important features to understand about objects is how the use of objects by Windows PowerShell differs from the text-based processing that is characteristic of many earlier command shells. Traditional command shells that use text-based processing require a variety of text processing utilities in order to function.

By contrast, Windows PowerShell transfers data between its cmdlets as structured objects rather than as text, which means that each Windows PowerShell cmdlet can interpret and act on any object that is passed to it. The cmdlet that receives the object can act directly on that object and its properties without requiring any conversion or manipulation, as is the case for text-based processing.

How to Access an Object

Each of the objects that Windows PowerShell for Virtual Machine Manager uses is an instance of a .NET Framework class, which consists of data and operations that are associated with that data. An object is made up of three kinds of data:

Type. The type of the object indicates what kind of object it is. For example, the type for a Virtual Machine Manager library server is:
```
TypeName: Microsoft.SystemCenter.VirtualMachineManager.LibraryServer
```
Properties. The properties of the object are its characteristics. After you connect to the Virtual Machine Manager database, when you run the Get-<Object> cmdlet for any Virtual Machine Manager object (such as Get-VMHost, Get-VirtualNetwork, Get-VirtualDVDDrive, and so on), you see a list of information about the state of each property for that object.
Methods. The methods of the object are the actions that you can perform on the entity (such as a server or virtual machine) that the object represents.

When you call a cmdlet by typing the cmdlet name at the command line, the command shell returns the specified object. In a single command line, you can use one or more pipeline operators (|) to pass an object from one cmdlet to another. You specify properties and methods of the object by name, rather than by having to calculate the position of the data in output that is formatted as text.

All objects of the same type, such as a specific type of file or a specific type of server, share the same properties and methods, but each instance of an object can have different values for its properties. For example, all Virtual Machine Manager library servers are the same type of object, but, typically, you define a different Name and Description property for each library server object, whereas multiple servers might have the same value for the DomainName property.

Differentiating Between an Object and What It Represents

An object is not the same as the entity that the object represents. For example, a library server object is not the library server itself. Rather, it represents the physical file server that is configured as a Virtual Machine Manager library server so that you can use cmdlets to perform operations on that server. You might use the Add-LibraryServer cmdlet to add a new library server object to the Virtual Machine Manager database, or you might use the Get-LibraryServer cmdlet to retrieve the object that represents an existing library server and view its properties.

A Windows PowerShell array, including a Virtual Machine Manager array, is an array of objects. You might, for example, create an array that stores the object that represents each virtual machine that is currently turned off and then pass all of these virtual machine objects to a cmdlet that starts each virtual machine in the array.

Typically, an array contains objects of the same type. However, an untyped array in Windows PowerShell can contain different types of .NET Framework objects in each element of the array.

Viewing an Object

You can use the standard Windows PowerShell cmdlet, Get-Member, to view the properties and methods of any object, as shown in the following example.

To display the type, methods, and properties for the Virtual Machine Manager server object

On a Virtual Machine Manager server on which the Administrator Console for Virtual Machine Manager is installed, click Start, point to All Programs, point to Microsoft System Center Virtual Machine Manager 2007, and then click Windows PowerShell – Virtual Machine Manager to open the command shell.
At the command prompt, type the following two commands:
1. $VMMServer = Get-VMMServer –Computername “<YourVMMServerName>.<YourDomainName>.com”
2. $VMMServer | Get-Member
Confirm that the command output displays the object type and lists a set of methods and a set of properties for the server object. In the following example, the object type appears at the top of the output in the following format:
```
TypeName: Microsoft.SystemCenter.VirtualMachineManager. Remoting.ServerConnection
```
In the following example, following the TypeName header, the output lists the name and definition for all methods and properties that are associated with the Virtual Machine Manager server object.

How Virtual Machine Manager Cmdlets Work with Objects

You can use Virtual Machine Manager cmdlets to manage all Virtual Machine Manager objects at the command line. These objects are stored in a SQL Server database called the Virtual Machine Manager database. The database is stored on the Virtual Machine Manager server itself or on a remote SQL server that is associated with the Virtual Machine Manager server. Virtual Machine Manager supports SQL Server 2005 and Microsoft SQL Server 2005 Express Edition SP1.

Examples of Virtual Machine Manager objects include:

Computers. Objects that represent each type of physical or virtual computer in a Virtual Machine Manager environment are stored in the Virtual Machine Manager database. These servers include the Virtual Machine Manager server itself, servers that act as hosts for virtual machines, servers that act as libraries to store resources, Web servers that act as Self-Service Portals (for users who allowed to create or manage their own virtual machines, or both), and virtual machines that are either deployed on a host or stored in the library.
Resources. Objects that represent library resources (such as library shares, virtual machine templates, ISO images, scripts, and so on) that are stored in the library catalog in the Virtual Machine Manager database. Files that these library objects represent are stored as specific file types on the physical library server.
Components of a virtual machine. Objects that represent parts of a virtual machine (such as virtual floppy drives, virtual network adapters, virtual SCSI adapters, or virtual COM ports) can be stored on a virtual machine, on a template, or on a hardware profile.

The Virtual Machine Manager cmdlets typically use standard Windows PowerShell verb names for similar actions performed on specific objects. For example:

New-<Object> cmdlets. Used to create new objects (such as virtual machines, virtual network adapters, templates, or self-service policies) and store them in the Virtual Machine Manager database.
Add-<Object> cmdlets. Used to add a object for something that already exists (such as a library server, a library share, a host server, a host network adapter, or a virtual hard disk) to the Virtual Machine Manager database. Other objects are added to the database automatically.
Get-<Object> cmdlets. Used to retrieve the object that represents a Virtual Machine Manager entity (such as a host, host group, virtual machine, template, script, job, self-service policy, or any other Virtual Machine Manager object) from the Virtual Machine Manager database. You can then review the characteristics of that retrieved object or use other Virtual Machine Manager cmdlets to act on that object.
Set-<Object> cmdlets. Used to specify or change data (properties) associated with an object.
Remove-<Object> cmdlets. Used to remove an object from the Virtual Machine Manager database.

The preceding list is not the complete list of verbs for Virtual Machine Manager cmdlets, but each of these verbs is used for all or most objects in both standard Windows PowerShell and in Virtual Machine Manager.

How Virtual Machine Manager Updates Objects Stored in the Library

The following scenario outlines a simple but typical administrative situation. In the following scenario, you have a large Virtual Machine Manager library that is distributed across multiple physical machines, and, therefore, library resources might be stored as files on any of several library servers. However, the objects that represent each library server (and the objects that represent every resource stored on each of those library servers) are all stored in the Virtual Machine Manager database that is managed by the Virtual Machine Manager server service.

A file that you use in your Virtual Machine Manager environment called "SysPrepAnswerFile" is stored in NetworkShareA on the physical library server called LibServ01.
You use a file system tool (such as Windows Explorer) to move SysPrepAnswerFile to NetworkShareB on LibServ02.
Through one of the following methods, Virtual Machine Manager discovers that you moved SysPrepAnswerFile to a different folder on another server:
- By default, the Virtual Machine Manager library refresher feature is enabled. The library refresher discovers new or moved objects that are stored in shares on library servers at regular intervals (by default, once every hour) and updates the Virtual Machine Manager database accordingly.
- Alternatively, you can run the Refresh-LibraryShare cmdlet at any time to update immediately the state and metadata of all Virtual Machine Manager library objects stored in the specified share or shares.

How Virtual Machine Manager "Live" Objects Work

Virtual Machine Manager objects differ from standard Windows PowerShell objects because all Virtual Machine Manager objects are "live" and are thus are kept synchronized with each other. Standard Windows PowerShell objects typically are not synchronized.

For example, if you type the series of commands shown in the following procedure at the Windows PowerShell command line, the final result is that the contents of $StandardPSObject1 and the contents of $StandardPSObject2 are not the same.

To verify that Windows PowerShell objects are not synchronized

On any computer on which Windows PowerShell is installed, click Start, point to All Programs, point to Windows PowerShell 1.0, and then click Windows PowerShell to open the command shell.

Note

The command shell that you open is the standard version of Windows PowerShell and does not include the Virtual Machine Manager cmdlets.
Type the following series of commands at the command prompt, and then view the results:
1. $StandardPSObject1 = "abc"
2. $StandardPSObject2 = $StandardPSObject1
3. $StandardPSObject1 = "123"
4. $StandardPSObject1
5. $StandardPSObject2
View the output to confirm that the contents of $StandardPSObject1 is 123, but the contents of $StandardPSObject2 is abc. Standard Windows PowerShell does not synchronize objects.

However, if you type the series of commands shown in the following procedure at the command line in the Virtual Machine Manager command shell, the final result is that both Virtual Machine Manager objects contain the same information.

To verify that Virtual Machine Manager objects are synchronized

On a Virtual Machine Manager server on which the Administrator Console for Virtual Machine Manager is installed, click Start, point to All Programs, point to Microsoft System Center Virtual Machine Manager 2007, and then click Windows PowerShell – Virtual Machine Manager to open the command shell.

Note

The following example assumes that you have a Virtual Machine Manager server named VMMServer1 and a file server named LibServ01 and that both servers are located in the Contoso.com domain. It also assumes that you have an ISO image named VMAdditions.
Type the following series of commands at the command prompt, and then view the results:
1. $VmmIsoObject1 = Get-ISO -VMMServer VMMServer1.Contoso.com | where { $_.Name -eq "VMAdditions" -and $_.LibraryServer.Name -eq "LibServ01.Contoso.com" }
2. $VmmIsoObject2 = Get-ISO -VMMServer VMMServer1.Contoso.com | where { $_.Name -eq "VMAdditions" -and $_.LibraryServer.Name -eq "LibServ01.Contoso.com" }
3. Set-ISO -ISO $VmmIsoObject2 -Name “VMAdditions-RTM”
4. $VmmIsoObject1 | format-list -property Name
5. $VmmIsoObject2 | format-list -property Name
Confirm that the name displayed for both $VmmIsoObject1 and $VmmIsoObject2 is VMAdditions-RTM. In the Windows PowerShell - Virtual Machine Manager command shell, objects are synchronized.

The commands in the preceding example perform the following tasks:

The first command retrieves from the library catalog in the Virtual Machine Manager database the object that represents the ISO file named VMAdditions on library server LibServ01. The command stores the ISO object in variable $VmmIsoObject1.
The second command retrieves the same object and stores it in variable $VmmIsoObject2. Retrieving and storing the object might be done, for example, by a different server administrator working on a different computer.
The third command changes the name of the object stored in $VmmIsoObject2 to VMAdditions-RTM.
The last two commands display the name property of the objects stored in variables $VmmIsoObject1 and $VmmIsoObject2. Because all Virtual Machine Manager objects are "live" objects, they are synchronized, so, as the output shows, the name of the object in each variable has been changed to VMAdditions-RTM.