Chapter 6. Using Objects

PowerShell always works with objects. Whenever you output objects into the PowerShell console, PowerShell automatically converts the rich objects into readable text. In this chapter, you will learn what objects are and how to get your hands on PowerShell objects before they get converted to simple text.

Topics Covered:

• Objects = Properties + Methods
  • Creating a New Object
  • Adding Properties
  • Adding Methods
• Properties: What an Object "Is"
  • Properties Containing Objects
  • Read-Only and Read-Write Properties
    • Table 6.1: Properties of the RawUI object
  • Property Types
  • Listing All Properties
• Methods: What an Object "Can Do"
  • Eliminating "Internal" Methods
    • Get_ and Set_ Methods
    • Standard Methods
      • Table 6.2: Standard methods of a .NET object
  • Calling a Method
  • Call Methods with Arguments
    • Which Arguments are Required?
    • Low-Level Functions
  • Several Method "Signatures"
    • Playing with PromptForChoice
• Working with Real-Life Objects
  • Storing Results in Variables
    • Using Object Properties
    • PowerShell-Specific Properties
      • Table 6.3: Different property types
    • Using Object Methods
    • Different Method Types
      • Table 6.4: Different types of methods
• Using Static Methods
  • Table 6.5: Mathematical functions from the [Math] library
  • Finding Interesting .NET Types
    • Converting Object Types
    • Using Static Type Members
    • Using Dynamic Object Instance Members
  • Listing Assemblies
    • EndFinding Interesting Classes (Types)
    • Looking for Methods
• Creating New Objects
  • Creating New Objects with New-Object
    • Using Constructors
  • New Objects by Conversion
  • Loading Additional Assemblies: Improved Internet Download
  • Using COM Objects
    • Which COM Objects Are Available?
    • How Do You Use COM Objects?
• Summary

Objects = Properties + Methods

In real life, you probably already know what an object is: everything you can touch. Objects in PowerShell are actually quite similar. Let's turn a typical real-world object like a pocketknife into a PowerShell object.

How would you describe this object to someone, let's say over a phone line? You would probably carefully examine the object and then describe what it is and what it can do:

• Properties: a pocketknife has particular properties, such as its color, manufacturer, size, or number of blades. The object is red, weights 55 grams, has three blades, and is made by the firm Idera. So properties describe what an object is.
• Methods: in addition, you can do things with this object, such as cut, turn screws, or pull corks out of wine bottles. The object can cut, screw, and remove corks. Everything that an object can is called its methods.

In the computing world, an object is very similar: its nature is described by properties, and the actions it can perform are called its methods. Properties and methods are called members.

Creating a New Object

Let's turn our real-life pocketknife into a virtual pocketknife. Using New-Object, PowerShell can generate new objects, even a virtual pocketknife. First you need a new and empty object:

This new object is actually pretty useless right now. If you call it, PowerShell will literally return "nothing":

Adding Properties

Next, let's start describing what our object is. To do that, add properties to the object.

Use the Add-Member cmdlet to add properties. Here, you added the property Color with the value Red to the object $pocketknife. If you call the object now, it suddenly has a first property telling the world that its color is red:

In the same way, you now add more properties to describe the object even better. Remember that you don't need to completely write out parameter names. It is enough to write only as much as to make the parameter name unambiguous:

In fact, you don't need to specify parameter names for some of the parameters at all because some of them are positional: provided you specify parameters in the right order, PowerShell can automatically assign your values to the correct parameter. Adding new properties to your object becomes even easier:

Most PowerShell cmdlets can receive their input objects either by parameter (-inputObject) or via the pipeline, so you can add properties to your object in yet another way:

By now, you've described the object in $pocketknife with a total of four properties. If you output the object in $pocketknife in the PowerShell console, PowerShell automatically converts the object into readable text:

Outputting an object to the console gets you a quick overview over its properties. To access the value of a specific property, add a dot and then the property name:

Adding Methods

With every new property you added to your object, $pocketknife has been gradually taking shape, but it still really can't do anything. Properties only describe what an object is, not what it can do.

The actions your object can do are called its methods. So let's teach your object a few useful methods:

Again, you used the Add-Member cmdlet, but this time you added a method instead of a property (in this case, a ScriptMethod). The value is a scriptblock marked by braces, which contains the PowerShell instructions you want the method to perform. If you output your object, it will still look the same because PowerShell only visualizes object properties, not methods:

To use any of the three newly added methods, add a dot and then the method name followed by two parentheses, which are what distinguish properties from methods. For example, if you'd like to remove a cork with your virtual pocketknife, enter this instruction:

Your object really does carry out the exact script commands you assigned to the corkscrew() method. So, methods perform actions, while properties merely provide information. Always remember to add parentheses to method names. If you forget them, something interesting happens:

You just received a method description. What's interesting about this is mainly the OverloadDefinitions property. As you'll see later, it reveals the exact way to use a command for any method. In fact, the OverloadDefinitions information is in an additional object. For PowerShell, absolutely everything is an object so you could store the object in a variable and then specifically ask the OverloadDefinitions property for information:

The "virtual pocketknife" example reveals that objects are containers that contain data (properties) and actions (methods).

Our virtual pocketknife was a somewhat artificial object with no real use. Next, let's take a look at a more interesting object which PowerShell stores in the variable $host.

Properties: What an Object "Is"

Properties describe an object. Object properties are automatically converted into text when you output the object to the console. That's enough to investigate any object. Check out the properties in $host!

The object stored in the variable $host apparently contains seven properties. The properties' names are listed in the first column. So, if you want to find out which PowerShell version you're using, you could access and return the Version property:

It works—the version is displayed. However, the version isn't displayed as a single number. Rather, PowerShell displays four columns: Major, Minor, Build and Revision. Whenever you see columns, you know these are the object properties that PowerShell has just converted into text. Let's check out the data type that the Version property uses:

The version is not stored as a String object but as a System.Version object. This object type is perfect for storing versions, allowing you to easily read all details about any given version:

Knowing an object type is very useful because once you know there is a type called System.Version, you can use it for your own purposes as well. Try and convert a simple string of your choice into a rich version object! To do that, simply make sure the string consists of four numbers separated by dots (the typical format for versions), then make PowerShell convert the string into a System.Version type. You convert things by adding the target type in square brackets in front of the string:

The CurrentCulture property is just another example of the same concept. Read this property and find out its type:

Country properties are again stored in a highly specialized type that describes a culture with the properties LCID, Name, and DisplayName. If you wanted to know which international version of PowerShell you are using, read the DisplayName property:

Likewise, you could convert any suitable string into a CultureInfo-object. So if you wanted to find out details about the 'de-DE' locale, do this:

You could also convert the LCID into a CultureInfo object by converting a suitable number:

Properties Containing Objects

The properties of an object store data, and this data is, in turn, stored in various other objects. Two properties in $host seem to be special: UI and PrivateData. When you output $host into the console, all other properties are converted into readable text - except for the properties UI and PrivateData:

The reason is that both these properties contain an object that, as the only property, provides, in turn, an object. If you'd like to find out what is actually stored in the UI property, read the property:

You see that the property UI contains only a single property called RawUI, in which yet another object is stored. Let's see what sort of object is stored in the RawUI property:

"RawUI" stands for "Raw User Interface" and exposes the raw user interface settings your PowerShell console uses. You can read all of these properties, but can you also change them?

Read-Only and Read-Write Properties

Can you actually change properties, too? And if you can, what happens then?

Properties need to accurately describe an object, so if you modify a property, the underlying object has to also be modified to reflect that change. If that is not possible, the property cannot be changed and is called "read-only."

Console background and foreground colors are a great example of properties you can easily change. If you do, the console will change colors accordingly. Your property changes are reflected by the object, and the changed properties still accurately describe the object.

Type cls so the entire console adopts this color scheme.

Other properties cannot be changed. If you try anyway, you'll get an error message:

Whether the console receives key press input, or not, depends on whether you pressed a key or not. You cannot control that by changing a property, so this property refuses to be changed. You can only read it.

Property Types

Some properties accept numeric values. For example, the size of a blinking cursor is specified as a number from 0 to 100 and corresponds to the fill percentage. The next line sets a cursor size of 75%. Values outside the 0-100 numeric range generate an error:

Other properties expect color settings. You cannot specify any color that comes to your mind, though. Instead, PowerShell expects a "valid" color, and if your color is unknown, you receive an error message listing the colors you can use:

Sometimes, a property expects a value wrapped in a specific object. For example, if you'd like to change the PowerShell window size, you could use the WindowSize property. As it turns out, the property expects a new window size wrapped in an object of type System.Management.Automation.Host.Size. Where can you get an object like that?

Listing All Properties

Because properties and methods are all members of an object, Get-Member returns detailed information about them. Let's use Get-Member to examine all properties defined in $host. To limit Get-Member to only properties, use the memberType parameter and specify "property":

In the column Name, you now see all supported properties in $host. In the column Definition, the property object type is listed first. For example, you can see that the Name property stores a text as System.String type. The Version property uses the System.Version type.

At the end of each definition, braces report whether the property is read-only ({get;}) or can also be modified ({get;set;}). You can see at a glance that all properties of the $host object are only readable. Now, take a look at the $host.ui.rawui object:

This result is more differentiated. It shows you that some properties could be changed, while others could not.

Methods: What an Object "Can Do"

Methods are things that an object can do. When you output an object to the console, only its properties are converted into readable text. Its methods remain invisible. To list the methods of an object, use Get-Member and use the parameter "memberType" with the value "method":

Eliminating "Internal" Methods

Get-Member lists all methods defined by an object. Not all of them are really useful to you. Let's check out why some of the listed methods are really only of limited use.

Get_ and Set_ Methods

Any method that starts with "get_" is really a method to retrieve a property value. So the method "get_someInfo()" is getting you the very same information you could also have retrieved with the "someInfo" property.

The same is true for Set_ methods: they change a property value and exist for properties that are read/writeable. Note in this example: all properties of the $host object can only be read so there are no Set_ methods. There can be more internal methods like this, such as Add_ and Remove_ methods. Generally speaking, when a method name contains an underscore, it most likely is an internal method.

Standard Methods

In addition, nearly every object contains a number of "inherited" methods that are also not specific to the object but perform general tasks for every object:

To sort out all methods that contain an underscore, you could use Where-Object and the comparison operator -notlike:

The $host object really only contains these unique and useful methods:

Calling a Method

Watch out: before you invoke a method: make sure you know what the method will do. Methods are commands that do something, and what a command does can be dangerous. To call a method, add a dot to the object and then the method name. Add an opened and closed parenthesis, like this:

The PowerShell prompt changes to ">>". You have used EnterNestedPrompt() to open a nested prompt. Nested prompts are not especially useful in a normal console, so exit it again using the exit command or call $host.ExitNestedPrompt().

Nested prompts are very useful in functions or scripts because they work like breakpoints and can temporarily stop a function or script so you can verify variable contents or make code changes, after which you continue the code by entering exit. You'll learn more about this in Chapter 11.

Call Methods with Arguments

There are a bunch of useful methods in the UI object. Here's how you get a good overview:

Most methods require additional arguments from you, which are listed in the Definition column.

Which Arguments are Required?

Pick out a method from the list, and ask Get-Member to get you more info. Let's pick WriteDebugLine():

The Definition property tells you how to call the method. Every definition starts with the object type that a method returns. In this example it is System.Void, a special object type because it represents "nothing": the method doesn't return anything at all. A method "returning" System.Void is really a procedure, not a function.

Next, a method's name follows, which is then followed by required arguments. WriteDebugLine needs exactly one argument called message, which is of String type. Here is how you call WriteDebugLine():

Low-Level Functions

WriteDebugLine() really does nothing spectacular. In fact, most methods found in the $host object are really only low-level commands used by the standard PowerShell cmdlets. For example, you could also have output the debug notification by using the following cmdlet:

However, there are differences: No matter what—WriteDebugText() always writes out yellow debug messages. The high-level Write-Debug cmdlet only outputs the debug message when the $DebugPreference variable is set to anything other than "SilentlyContinue" (which is the default).

The same applies to the WriteErrorLine, WriteVerboseLine, and WriteWarningLine methods, which are the low-level functions for the Write-Error, Write-Verbose, and Write-Warning cmdlets.

So, if you'd like to output error or warning messages that are independent of the various preference settings in PowerShell, use the low-level commands in $host.UI.RawUI instead of the cmdlets.

Several Method "Signatures"

Some methods accept different argument types or even different numbers of arguments. To find out which "signatures" a method supports, use Get-Member again and look at the Definition property:

Unfortunately, the definition is hard to read at first. Make it more readable by using Replace() to add line breaks.

This definition tells you: You do not necessarily need to supply arguments:

The result is an empty line.

To output text, you specify one argument only, the text itself:

The third variant adds support for foreground and background colors:

WriteLine() actually is the low-level function of the Write-Host cmdlet:

Playing with PromptForChoice

Most methods you examined so far turned out to be low-level commands for cmdlets. This is also true for the following methods: Write() (corresponds to Write-Host -noNewLine) or ReadLine()/ReadLineAsSecureString() (Read-Host -asSecureString) or PromptForCredential() (Get-Credential).

A new functionality is exposed by the method PromptForChoice(). Let's first examine which arguments this method expects:

The definition reveals that this method returns a numeric value (System.Int32). It requires a heading and a message respectively as text (String). The third argument is a bit strange: Collection`1 choices. The fourth argument is a number (Int32), the standard selection. You should have noticed by now the limitations of PowerShell's built-in description.

This is how you could use PromptForChoice() to create a simple menu:

Working with Real-Life Objects

Every single PowerShell command returns objects, which is a good thing. However, it is not that easy to get your hands on objects because whenever objects hit the PowerShell console, they will be converted to text and lose a lot of their information.

Storing Results in Variables

Do not output command results to the console to prevent PowerShell from converting objects into simple strings. The console is a hostile place for objects because anything output to the PowerShell console will end up as text. Instead, save the command result in a variable, which is a safe place for objects.

However, variables are only safe places for objects until you dump their content to the console: the objects stored inside of your variable would again be converted to text.

So, to get in touch with the real objects, you can directly access them inside of a variable. Dir has stored its directory listing in $listing. Since the listing consists of more than one entry, it is wrapped in an array. Access an array element to get your hands on a real object:

The object picked here happens to match the folder Application Data; so it represents a directory. If you would prefer to directly pick a particular directory or file, you can do this:

Using Object Properties

You can now use Get-Member again to produce a list of all available properties:

Properties marked with {get;set;} in the column Definition may also be modified:

PowerShell-Specific Properties

PowerShell can add additional properties to an object. Whenever that occurs, Get-Member labels the property accordingly in the MemberType column. Native properties are just called "Property." Properties added by PowerShell use a prefix, such as "ScriptProperty" or "NoteProperty."

A NoteProperty like PSChildName contains static data. PowerShell adds it to tag additional information to an object. A ScriptProperty like Mode executes PowerShell script code that calculates the property's value.

If you want to see the script code being executed when you call the ScriptProperty Mode, ask Get-Member to list the property definition:

As it turns out, Mode evaluates the native Attributes property which is a bitmask. Binary bitmasks are hard to read so that is why the new Mode script property converts the binary information into a more user friendly format.

Using Object Methods

Use Get-Member again to find out the methods that an object supports:

You can apply methods just like you did in the previous examples. For example, use the CreateSubDirectory method if you'd like to create a new subdirectory. Find out first which arguments this method requires and what it returns:

You can see that the method has two signatures. Use the first to create a subdirectory and the second to add access permissions.

The next line creates a subdirectory called "My New Directory" without any special access privileges:

Because the method returns a DirectoryInfo object as result and you haven't caught and stored this object in a variable, the pipeline converts it into text and outputs it. You could just as well have stored the result of the method in a variable:

Different Method Types

Similarly to properties, PowerShell can also add additional methods to an object.

Using Static Methods

By now, you know that PowerShell stores information in objects, and objects always have a type. You know that simple text is stored in objects of type System.String and that a date, for example, is stored in an object of type System.DateTime. You also know by now that each .NET object has a GetType() method with a FullName property which tells you the name of the type this object was derived from:

Every type can have its own set of private members called "static" members. Simply specify a type in square brackets, then pipe it to Get-Member and use the -static parameter to see the static members of a type.

The System.DateTime class supplies you with a bunch of important date and time methods. For example, to convert a date string into a real DateTime object and use the current locale, use Parse():

You could easily find out whether a certain year is a leap year:

Or you'd like to tell your children with absolute precision how much time will elapse before they get their Christmas gifts:

Two dates are being subtracted from each other here so you now know what happened during this operation:

• The first time indication is actually text. For it to become a DateTime object, you must specify the desired object type in square brackets. Important: Converting a String to a DateTime this way always uses the US locale. To convert a String to a DateTime using your current locale, use the Parse() method as shown a couple of moments ago!
• The second time comes from the Now static property, which returns the current time as DateTime object. This is the same as calling the Get-Date cmdlet (which you'd then need to put in parenthesis because you wouldn't want to subtract the Get-Date cmdlet but rather the result of the Get-Date cmdlet).
• The two timestamps are subtracted from each other using the subtraction operator ("-"). This was possible because the DateTime class defined the op_Subtraction() static method, which is needed for this operator.

Of course, you could have called the static method yourself and received the same result:

Now it's your turn. In the System.Math class, you'll find a lot of useful mathematical methods. Try to put some of these methods to work.

Finding Interesting .NET Types

The .NET framework consists of thousands of types, and maybe you are getting hungry for more. Are there other interesting types? There are actually plenty! Here are the three things you can do with .NET types:

Converting Object Types

For example, use System.Net.IPAddress to work with IP addresses. This is an example of a .NET type conversion where a string is converted into a System.Net.IPAddress type:

Using Static Type Members

Or use System.Net.DNS to resolve host names. This is an example of accessing a static type method like GetHostByAddress():

Using Dynamic Object Instance Members

Or you can derive an instance of a type and use its dynamic members. For example, to download a file from the Internet:

Listing Assemblies

The search for interesting types begins with assemblies as they contain the types. First, you need to get a list of all the assemblies that PowerShell has loaded. Use the AppDomain type to find out the loaded assemblies. Its CurrentDomain() static method will give you access to the internal PowerShell .NET framework where you'll find the GetAssemblies() dynamic method, which will enable you to get a list of the loaded assemblies:

Finding Interesting Classes (Types)

To find out which types are located in an assembly, use the GetExportedTypes() method provided by an assembly. Since most assemblies contain way too many types you could search for a specific keyword. This code list all types that include the search word "environment":

One of the types that show up is the type System.Environment. The System.Environment type can do very useful things. Let's list its static members:

For example, the static methods of the System.Environment class will show you which user has executed the script on which machine:

Using GetFolderPath(), the class will also reveal the paths to all important Windows folders. To find out the proper values for an argument, specify an invalid argument, and the error message will list all valid argument values:

So, if you'd like to know where the picture folder is on your computer, use MyPictures.

Looking for Methods

Next, let's search for some interesting methods. Here's a way for you to find the GetFolderPath() method of the previous example:

The search can easily take a few minutes because PowerShell examines every single method in every type exposed by every loaded assembly.

Creating New Objects

You have seen that many .NET types contain useful static methods. In addition, you can create new objects (instances) that are derived from a specific type. To create new instances, you can either convert an existing object to a new type, or you can create a new instance using New-Object. In addition, you may be able to call some cmdlet or method that happens to return the object type you are after:

Creating New Objects with New-Object

You can create a .NET object with New-Object, which gives you full access to all type "constructors." These are invisible methods that create the new object. To create a new instance of a type, the type needs to have at least one constructor. If it has none, you cannot create instances of this type.

The DateTime type has one constructor that takes no argument. If you create a new instance of a DateTime object, you get back a date set to the very first date a DateTime type can represent which happens to be January 1, 0001:

To create a specific date, you would use a different constructor. There is one that takes three numbers for year, month, and day:

If you simply add a number, yet another constructor is used which interprets the number as ticks, the smallest time unit a computer can process:

Using Constructors

When you create a new object using New-Object, you can submit additional arguments by adding argument values as a comma separated list enclosed in parentheses. New-Object in fact is calling a method called ctor which is the type constructor. Like any other method, it can support different argument signatures.

Let's check out how you can discover the different constructors a type supports. The next line creates a new instance of a System.String and uses a constructor that accepts a character and a number:

To list the available constructors for a type, use the GetConstructors() method available in each type. For example, you could find out which constructors are offered by the System.String type to produce System.String objects:

In fact, there are eight different signatures to create a new object of the System.String type. You just used the last variant: the first argument is the character, and the second a number that specifies how often the character is to be repeated. PowerShell itself uses the next to last constructor so if you specify text in quotation marks, it will interpret text in quotation marks as a field with nothing but characters (Char[]).

New Objects by Conversion

Objects can often be created without New-Object by using type casting instead. You've already seen how it's done for variables in Chapter 3:

So, if you enclose the desired .NET type in square brackets and put it in front of a variable name, PowerShell will require you to use precisely the specified object type for this variable. If you assign a value to the variable, PowerShell automatically converts it to that type. That process is sometimes called "implicit type conversion." Explicit type conversion works a little different. Here, the desired type is put in square brackets again but placed on the right side of the assignment operator:

PowerShell would first convert the text into a date because of the type specification and then assign it to the variable $value, which itself remains a regular variable without type specification. Because $value is not limited to DateTime types, you can assign other data types to the variable later on.

Using the type casting, you can also create entirely new objects without New-Object. First, create an object using New-Object:

You could have accomplished the same thing without New-Object:

In the second example, the string System was converted into the System.Diagnostics.Eventlog type: The result is an EventLog object representing the System event log.

So, when should you use New-Object and when type conversion? It is largely a matter of taste, but whenever a type has more than one constructor and you want to select the constructor, use New-Object and specify the arguments for the constructor of your choice. Type conversion automatically chooses one constructor, and you have no control over which constructor is picked.

Loading Additional Assemblies: Improved Internet Download

To get access to even more functionality, you can load additional assemblies with more types and members. If you have ever written VBScript scripts, you may want to get back some of your beloved VisualBasic methods such as MsgBox() or InputBox(). Simply load the Microsoft.VisualBasic assembly, which is located in the global assembly cache:

Once you did that, you have access to a whole bunch of new types:

Or, you could use a much-improved download method, which shows a progress bar while downloading files from the Internet:

Using COM Objects

In addition to .NET, PowerShell can also load and access COM objects which work similar to .NET types and objects but use an older technology.

Which COM Objects Are Available?

COM objects each have a unique name known as ProgID or Programmatic Identifier, which is stored in the registry. So, if you want to look up COM objects available on your computer, visit the registry:

How Do You Use COM Objects?

Once you know the ProgID of a COM component, use New-Object to put it to work in PowerShell. Just specify the additional parameter -comObject:

You'll get an object which behaves very similar to .NET objects. It will contain properties with data and methods that you can execute. And, as always, Get-Member finds all object members for you. Let's look at its methods:

The information required to understand how to use a method can be inadequate. Only the expected object types are given, but not why the arguments exist. If you want to know more about a COM command, the Internet can help you. Go to a search site of your choice and enter two keywords: the ProgID of the COM components (in this case, it will be WScript.Shell) and the name of the method that you want to use.

Some of the commonly used COM objects are WScript.Shell, WScript.Network, Scripting.FileSystemObject, InternetExplorer.Application, Word.Application, and Shell.Application. Let's create a shortcut to powershell.exe using WScript.Shell Com object and its method CreateShorcut():

Summary

Everything in PowerShell is represented by objects that have exactly two aspects: properties and methods, which both form the members of the object. While properties store data, methods are executable commands.

Objects are the result of all PowerShell commands and are not converted to readable text until you output the objects to the console. However if you save a command's result in a variable, you will get a handle on the original objects and be able to evaluate their properties or call their commands. If you would like to see all of an object's properties, then pass the object to Format-List and type an asterisk after it. In this way, all—and not only the most important—properties will be output as text.

The Get-Member cmdlet retrieves even more data, enabling you to output detailed information on the properties and methods of any object.

All the objects with which you work in PowerShell originate from .NET framework, on which PowerShell is layered. Aside from the objects that PowerShell commands provide you as results, you can also invoke objects directly from the .NET framework and gain access to a powerful arsenal of new commands. Along with the dynamic methods furnished by objects, there are also static methods, which are provided directly by the class from which objects are also derived.

If you cannot perform a task either with the cmdlets, regular console commands, or methods of the .NET framework, you can resort to the unmanaged world outside the .NET framework. Either directly access the low-level API functions, the foundation of the .NET framework, or use COM components.