You can use filters to reduce large sets of output data by retrieving only the objects that correspond to the filter criteria that you provide. You can use vSphere PowerCLI views to define and use filters to select specific objects based on property values.

To apply a filter to the results of VimClient.FindEntityView() or VimClient.FindEntityViews(), you can supply an optional filter parameter. The value of the parameter is a NameValueCollection object containing one or more pairs of filter criteria. Each of the criteria consists of a property path and a match value. The match value can be either a string, or a regular expression object. If the match value is a string, the property value of the target objects must be exactly the same as the string.

Example: Filtering virtual machines by power state

The following commands retrieve all powered-off virtual machines.

NameValueCollection filter = new NameValueCollection();
filter.Add("Runtime.PowerState", "PoweredOff")
Example: Filtering objects by name

The following commands retrieve all virtual machines with names that start with Test.

NameValueCollection filter = new NameValueCollection();
filter.Add("name", "^Test");
Example: Filter for creating views of Windows virtual machines only

The following example uses VimClient.FindEntityViews() in combination with a filter. It retrieves a list of all Windows virtual machines in the virtual environment.

NameValueCollection filter = new NameValueCollection();
filter.Add("Config.GuestFullName", "Windows");

IList EntityViewBase vmList = 
	client1.FindEntityViews(typeof(VirtualMachine), null, filter, null);

// Print VM names
foreach (VirtualMachine vm in vmList) {
	Console.WriteLine(vm.Name);
Example: Multiple criteria filter

This example uses a filter with multiple criteria. It retrieves all powered-on Windows virtual machines.

NameValueCollection filter = new NameValueCollection();
filter.Add("Runtime.PowerState", "PoweredOn");
filter.Add("Config.GuestFullName", "Windows");

IList EntityViewBase vmList =
	client1.FindEntityViews(typeof(VirtualMachine), null, filter, null);

// Print VM names
foreach (VirtualMachine vm in vmList) {
	Console.WriteLine(vm.Name);