Edit

Share via

Creating a List View

  • Article

A list view displays data in a single column (in sequential order). The data displayed in the list can be the value of a .NET property or the value of a script.

A List View Display

The following output shows how Windows PowerShell displays the properties of System.Serviceprocess.Servicecontroller?Displayproperty=Fullname objects that are returned by the Get-Service cmdlet. In this example, three objects were returned, with each object separated from the preceding object by a blank line.

Get-Service | format-list

Name                : AEADIFilters
DisplayName         : Andrea ADI Filters Service
Status              : Running
DependentServices   : {}
ServicesDependedOn  : {}
CanPauseAndContinue : False
CanShutdown         : False
CanStop             : True
ServiceType         : Win32OwnProcess

Name                : AeLookupSvc
DisplayName         : Application Experience
Status              : Running
DependentServices   : {}
ServicesDependedOn  : {}
CanPauseAndContinue : False
CanShutdown         : False
CanStop             : True
ServiceType         : Win32ShareProcess

Name                : AgereModemAudio
DisplayName         : Agere Modem Call Progress Audio
Status              : Running
DependentServices   : {}
ServicesDependedOn  : {}
CanPauseAndContinue : False
CanShutdown         : False
CanStop             : True
ServiceType         : Win32OwnProcess
...

Defining the List View

The following XML shows the list view schema for displaying several properties of the System.Serviceprocess.Servicecontroller?Displayproperty=Fullname object. You must specify each property that you want displayed in the list view.

<View>
  <Name>System.ServiceProcess.ServiceController</Name>
  <ViewSelectedBy>
    <TypeName>System.ServiceProcess.ServiceController</TypeName>
  </ViewSelectedBy>
  <ListControl>
    <ListEntries>
      <ListEntry>
        <ListItems>
          <ListItem>
            <PropertyName>Name</PropertyName>
          </ListItem>
          <ListItem>
            <PropertyName>DisplayName</PropertyName>
          </ListItem>
          <ListItem>
            <PropertyName>Status</PropertyName>
          </ListItem>
          <ListItem>
            <PropertyName>ServiceType</PropertyName>
          </ListItem>
        </ListItems>
      </ListEntry>
    </ListEntries>
  </ListControl>
</View>

The following XML elements are used to define a list view:

  • The View element is the parent element of the list view. (This is the same parent element for the table, wide, and custom control views.)

  • The Name element specifies the name of the view. This element is required for all views.

  • The ViewSelectedBy element defines the objects that use the view. This element is required.

  • The GroupBy element defines when a new group of objects is displayed. A new group is started whenever the value of a specific property or script changes. This element is optional.

  • The Controls element defines the custom controls that are defined by the list view. Controls give you a way to further specify how the data is displayed. This element is optional. A view can define its own custom controls, or it can use common controls that can be used by any view in the formatting file. For more information about custom controls, see Creating Custom Controls.

  • The ListControl element defines what is displayed in the view and how it is formatted. Similar to all other views, a list view can display the values of object properties or values generated by script.

For an example of a complete formatting file that defines a simple list view, see List View (Basic).

Providing Definitions for Your List View

List views can provide one or more definitions by using the child elements of the ListControl element. Typically, a view will have only one definition. In the following example, the view provides a single definition that displays several properties of the System.Diagnostics.Process?Displayproperty=Fullname object. A list view can display the value of a property or the value of a script (not shown in the example).

<ListControl>
    <ListEntries>
      <ListEntry>
        <ListItems>
          <ListItem>
            <PropertyName>Name</PropertyName>
          </ListItem>
          <ListItem>
            <PropertyName>DisplayName</PropertyName>
          </ListItem>
          <ListItem>
            <PropertyName>Status</PropertyName>
          </ListItem>
          <ListItem>
            <PropertyName>ServiceType</PropertyName>
          </ListItem>
        </ListItems>
      </ListEntry>
    </ListEntries>
  </ListControl>

The following XML elements can be used to provide definitions for a list view:

  • The ListControl element and its child elements define what is displayed in the view.

  • The ListEntries element provides the definitions of the view. In most cases, a view will have only one definition. This element is required.

  • The ListEntry element provides a definition of the view. At least one ListEntry is required; however, there is no maximum limit to the number of elements that you can add. In most cases, a view will have only one definition.

  • The EntrySelectedBy element specifies the objects that are displayed by a specific definition. This element is optional and is needed only when you define multiple ListEntry elements that display different objects.

  • The ListItems element specifies the properties and scripts whose values are displayed in the rows of the list view.

  • The ListItem element specifies a property or script whose value is displayed in a row of the list view. A list view must specify at least one property or script. There is no maximum limit to the number of rows that can be specified.

  • The PropertyName element specifies the property whose value is displayed in the row. You must specify either a property or a script, but you cannot specify both.

  • The ScriptBlock element specifies the script whose value is displayed in the row. You must specify either a script or a property, but you cannot specify both.

  • The Label element specifies the label that is displayed to the left of the property or script value in the row. This element is optional. If a label is not specified, the name of the property or the script is displayed. For a complete example, see List View (Labels).

  • The ItemSelectionCondition element specifies a condition that must exist for the row to be displayed. For more information about adding conditions to the list view, see Defining Conditions for Displaying Data. This element is optional.

  • The FormatString element specifies a pattern that is used to display the value of the property or script. This element is optional.

For an example of a complete formatting file that defines a simple list view, see List View (Basic).

Defining the Objects That Use the List View

There are two ways to define which .NET objects use the list view. You can use the ViewSelectedBy element to define the objects that can be displayed by all the definitions of the view, or you can use the EntrySelectedBy element to define which objects are displayed by a specific definition of the view. In most cases, a view has only one definition, so objects are typically defined by the ViewSelectedBy element.

The following example shows how to define the objects that are displayed by the list view using the ViewSelectedBy and TypeName elements. There is no limit to the number of TypeName elements that you can specify, and their order is not significant.

<View>
  <Name>System.ServiceProcess.ServiceController</Name>
  <ViewSelectedBy>
    <TypeName>System.Diagnostics.Process</TypeName>
  </ViewSelectedBy>
  <ListControl>...</ListControl>
</View>

The following XML elements can be used to specify the objects that are used by the list view:

  • The ViewSelectedBy element defines which objects are displayed by the list view.

  • The TypeName element specifies the .NET object that is displayed by the view. The fully qualified .NET type name is required. You must specify at least one type or selection set for the view, but there is no maximum number of elements that can be specified.

For an example of a complete formatting file, see List View (Basic).

The following example uses the ViewSelectedBy and SelectionSetName elements. Use selection sets where you have a related set of objects that are displayed using multiple views, such as when you define a list view and a table view for the same objects. For more information about how to create a selection set, see Defining Selection Sets.

<View>
  <Name>System.ServiceProcess.ServiceController</Name>
  <ViewSelectedBy>
    <SelectionSetName>.NET Type Set</SelectionSetName>
  </ViewSelectedBy>
  <ListControl>...</ListControl>
</View>

The following XML elements can be used to specify the objects that are used by the list view:

  • The ViewSelectedBy element defines which objects are displayed by the list view.

  • The SelectionSetName element specifies a set of objects that can be displayed by the view. You must specify at least one selection set or type for the view, but there is no maximum number of elements that can be specified.

The following example shows how to define the objects displayed by a specific definition of the list view using the EntrySelectedBy element. Using this element, you can specify the .NET type name of the object, a selection set of objects, or a selection condition that specifies when the definition is used. For more information about how to create a selection conditions, see Defining Conditions for Displaying Data.

<ListEntry>
  <EntrySelectedBy>
    <TypeName>.NET Type</TypeName>
  </EntrySelectedBy>
</ListEntry>

The following XML elements can be used to specify the objects that are used by a specific definition of the list view:

  • The EntrySelectedBy element defines which objects are displayed by the definition.

  • The TypeName element specifies the .NET object that is displayed by the definition. When using this element, the fully qualified .NET type name is required. You must specify at least one type, selection set, or selection condition for the definition, but there is no maximum number of elements that can be specified.

  • The SelectionSetName element (not shown) specifies a set of objects that can be displayed by this definition. You must specify at least one type, selection set, or selection condition for the definition, but there is no maximum number of elements that can be specified.

  • The SelectionCondition element (not shown) specifies a condition that must exist for this definition to be used. You must specify at least one type, selection set, or selection condition for the definition, but there is no maximum number of elements that can be specified. For more information about defining selection conditions, see Defining Conditions for Displaying Data.

Displaying Groups of Objects in a List View

You can separate the objects that are displayed by the list view into groups. This does not mean that you define a group, only that Windows PowerShell starts a new group whenever the value of a specific property or script changes. In the following example, a new group is started whenever the value of the System.Serviceprocess.Servicecontroller.Servicetype property changes.

<GroupBy>
  <Label>Service Type</Label>
  <PropertyName>ServiceType</PropertyName>
</GroupBy>

The following XML elements are used to define when a group is started:

  • The GroupBy element defines the property or script that starts the new group and defines how the group is displayed.

  • The PropertyName element specifies the property that starts a new group whenever its value changes. You must specify a property or script to start the group, but you cannot specify both.

  • The ScriptBlock element specifies the script that starts a new group whenever its value changes. You must specify a script or property to start the group, but you cannot specify both.

  • The Label element defines a label that is displayed at the beginning of each group. In addition to the text specified by this element, Windows PowerShell displays the value that triggered the new group and adds a blank line before and after the label. This element is optional.

  • The CustomControl element defines a control that is used to display the data. This element is optional.

  • The CustomControlName element specifies a common or view control that is used to display the data. This element is optional.

For an example of a complete formatting file that defines groups, see List View (GroupBy).

Using Format Strings

Formatting strings can be added to a view to further define how the data is displayed. The following example shows how to define a formatting string for the value of the StartTime property.

<ListItem>
  <PropertyName>StartTime</PropertyName>
  <FormatString>{0:MMM} {0:DD} {0:HH}:{0:MM}</FormatString>
</ListItem>

The following XML elements can be used to specify a format pattern:

  • The ListItem element specifies the data that is displayed by the view.

  • The PropertyName element specifies the property whose value is displayed by the view. You must specify either a property or a script, but you cannot specify both.

  • The FormatString element specifies a format pattern that defines how the property or script value is displayed in the view.

  • The ScriptBlock element (not shown) specifies the script whose value is displayed by the view. You must specify either a script or a property, but you cannot specify both.

In the following example, the ToString method is called to format the value of the script. Scripts can call any method of an object. Therefore, if an object has a method, such as ToString, that has formatting parameters, the script can call that method to format the output value of the script.

<ListItem>
  <ScriptBlock>
    [String]::Format("{0,-10} {1,-8}", $_.LastWriteTime.ToString("d"), $_.LastWriteTime.ToString("t"))
  </ScriptBlock>
</ListItem>

The following XML element can be used to calling the ToString method:

  • The ListItem element specifies the data that is displayed by the view.

  • The ScriptBlock element (not shown) specifies the script whose value is displayed by the view. You must specify either a script or a property, but you cannot specify both.

See Also

Writing a Windows PowerShell Cmdlet