{"id":8318,"date":"2014-12-02T06:00:19","date_gmt":"2014-12-02T14:00:19","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=8318"},"modified":"2016-04-08T16:36:01","modified_gmt":"2016-04-08T23:36:01","slug":"beyond-custom-objects-create-a-net-class","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2014\/12\/02\/beyond-custom-objects-create-a-net-class\/","title":{"rendered":"Beyond custom objects: Create a .NET class"},"content":{"rendered":"

In yesterday’s blog post<\/a>, I used the Select-String<\/a> cmdlet to capture\u00a0the table of keywords and references from the about_language_keywords<\/a> help topic and then used the new ConvertFrom-String<\/a> cmdlet in the Windows PowerShell\u00a05.0 preview\u00a0to convert each row of the table into a custom object (PSCustomObject). The custom object\u00a0worked quite well. I could search, sort, format, and use the objects in Windows PowerShell.<\/p>\n

PS C:\\> $k = $table | ConvertFrom-String -TemplateContent $template \r\n    | Select-Object -Property Keyword, Reference\r\n\r\nPS C:\\> $k | where Keyword -eq \"Trap\"\r\n\r\nKeyword    Reference                                                                                 \r\n-------    ---------                                                                                 \r\nTrap       about_Trap, about_Break, about_Try_Catch_Finally<\/pre>\n
But, it’s just a simple step from the generic custom object to a named dynamic .NET object that I can create, manage, and use in many different contexts. In this post, I’ll use the new class<\/strong> feature of the Windows PowerShell 5.0 preview to create a Keyword <\/strong> class and real Keyword objects.<\/p>\n
The class feature is new and works somewhat differently in the September version of the preview ($PSVersionTable.PSVersion = 5.0.9814.0) than it does in the November version (5.0.9883.0), so it’s likely to continue to change until (and even after) the official release.<\/p>\n
For background, see the release notes that come with the Windows PowerShell 5.0 preview and Windows PowerShell MVP Trevor Sullivan’s playful and informative blog post, Implementing a .NET Class in PowerShell v5<\/a>, in which he creates a Beer class.<\/p>\n
 <\/p>\n
Custom Objects for Keywords<\/strong><\/h2>\n
The\u00a0ConvertFrom-String<\/a> cmdlet returns custom objects with the properties that you specify, either by using the PropertyNames <\/strong>parameter or one of the template parameters, TemplateContent<\/strong> or TemplateFile<\/strong>.<\/p>\n
To see the properties and method of the objects that it returns, pipe the output (in this case, saved in the $k variable)\u00a0to the Get-Member<\/a> cmdlet.<\/p>\n
PS C:\\> $k | Get-Member\r\n\r\n   TypeName: Selected.System.Management.Automation.PSCustomObject\r\n\r\nName        MemberType   Definition                                                       \r\n----        ----------   ----------                                                       \r\nEquals      Method       bool Equals(System.Object obj)                                   \r\nGetHashCode Method       int GetHashCode()                                                \r\nGetType     Method       type GetType()                                                   \r\nToString    Method       string ToString()                                                \r\nKeyword     NoteProperty System.String Keyword=Begin                                      \r\nReference   NoteProperty System.String Reference=about_Functions, about_Functions_Advanced<\/pre>\n
The objects have the Keyword<\/strong> and Reference<\/strong> properties that we need, but the methods are pretty generic and not particularly useful.<\/p>\n
And, beginning in Windows PowerShell 5.0, it’s very easy to create a .NET class dynamically.<\/p>\n
Create a Keyword Class<\/strong><\/h2>\n
To create a class, begin with the class<\/strong> keyword followed by\u00a0the name of the class, which, in this case, is Keyword<\/strong>. The content of the class is enclosed in curly braces.<\/p>\n
To add properties to the class, just create global variables. In this case, I’ve added Name<\/strong> and Reference<\/strong> properties. (Yes, it’s that easy.)<\/p>\n
class Keyword \r\n{\r\n    #Properties\r\n    [String]$Name\r\n    [String]$Reference\r\n}<\/pre>\n
 <\/p>\n
To allow people to create objects that are instances of the class, add at least one constructor.<\/p>\n
A constructor<\/strong> is a special type of method that creates new objects. It has the same name as the class and it never returns anything (the return type is [Void], which means nothing. You can have multiple constructors, but each one has to take different numbers and types of parameters.<\/p>\n
In the Keyword class, I added one constructor that has two string parameters, Keyword<\/strong> and Reference<\/strong>. The commands in the constructor assign the value of the Keyword<\/strong> parameter to the Name<\/strong> property of the object and the value of the Reference<\/strong> parameter to the Reference<\/strong> property of the object.<\/p>\n
class Keyword \r\n{\r\n    #Properties\r\n    [String]$Name\r\n    [String]$Reference\r\n\r\n    #Constructor\r\n    Keyword (\r\n        [String]$Keyword\r\n        [String]$Reference\r\n    )\r\n    {\r\n        $this.Name = $Keyword\r\n        $this.Reference = $Reference\r\n    }\r\n}\r\n\r\n<\/pre>\n
Unlike the output types of functions, which are just notes, the output types of methods are enforced. If the method doesn’t return the declared output type, the method generates an error.<\/p>\n
The parentheses that surround the parameters are required, even when the method doesn’t take any parameters.<\/p>\n
As we discussed in the section about constructors, all method parameters are mandatory and positional. Each method has only one parameter set. Methods in a class can have the same name, but if they do, they must take different types and numbers of parameters.<\/p>\n
Did you notice the $this<\/strong> automatic variable? Like $_<\/strong> in pipelines, $this<\/strong> refers to the current object. Inside a class, when you refer to a property of the current object, you must use the $this prefix, a dot, and the property name.<\/p>\n
For example, to refer to the Name<\/strong> property of the current object, type:<\/p>\n
$this.Name<\/pre>\n
Requiring the $this<\/strong> variable lets you use parameters with the same names as the properties. Windows PowerShell uses the $this<\/strong> to distinguish the property from the parameter. For example, I used $Reference<\/strong> as a property of the object and a parameter of the constructor. To assign the $Reference<\/strong> parameter value to the $Reference<\/strong> property, I type:<\/p>\n
        # Property      = Parameter               \r\n\t$this.Reference = $Reference<\/pre>\n
 <\/p>\n
Create Keyword Objects<\/h2>\n
Now that our class is complete, we can create Keyword objects. To create an object that is an instance of a .NET class, call the New<\/strong> method. (The New-Object cmdlet doesn’t yet work for dynamically created .NET classes.) New<\/strong> is a static method — a method of the class, not of any particular object in the class. All .NET objects have the New<\/strong> method, because they inherit it from the System.Object class.<\/p>\n
To call a static method, type the class name in square brackets, two colons (with no intervening spaces), the method name, New<\/strong>, and a set of parentheses.<\/p>\n
This code calls the New method of the Keyword class:<\/p>\n
[Keyword]::New()<\/pre>\n
Inside the parentheses, call the constructor. Enter a comma-separated list of the values (omit the names) of the constructor parameters. All constructor parameters are mandatory and positional, so pay attention to the order of the values.<\/p>\n
The Keyword class constructor has $Keyword and $Reference string parameters (in that order). To create a keyword object for the “If” keyword, use a command like this one:<\/p>\n
[Keyword]::New(\"If\", \"about_If\")<\/pre>\n
To convert a custom object that has Keyword and Reference properties to a Keyword object, use a command like this one. It pipes the custom objects in the $k <\/strong>variable to the ForEach-Object<\/strong> cmdlet, which calls the New<\/strong> static method of the Keyword class on each object and then stores the results in the $keywords variable.<\/p>\n
$keywords = $k | ForEach-Object { [Keyword]::new($_.Keyword, $_.Reference)<\/pre>\n
Let’s see the result. The display looks just like the custom objects.<\/p>\n
PS C:\\> $keywords\r\n\r\nName         Reference                                                                                 \r\n----         ---------                                                                                 \r\nBegin        about_Functions, about_Functions_Advanced                                                 \r\nBreak        about_Break, about_Trap                                                                   \r\nCatch        about_Try_Catch_Finally                                                                   \r\nContinue     about_Continue, about_Trap<\/pre>\n
But, when you pipe them to the Get-Member cmdlet, you can see that the type is Keyword.<\/p>\n
PS C:\\> $keywords | Get-Member\r\n\r\n   TypeName: Keyword\r\n\r\nName        MemberType Definition                    \r\n----        ---------- ----------                    \r\nEquals      Method     bool Equals(System.Object obj)\r\nGetHashCode Method     int GetHashCode()             \r\nGetType     Method     type GetType()                \r\nToString    Method     string ToString()             \r\nName        Property   string Name {get;set;}        \r\nReference   Property   string Reference {get;set;}<\/pre>\n
The real value becomes evident when you add methods to the class.<\/p>\n
 <\/p>\n
Add a Method<\/h2>\n
The value of the Reference property of each keyword is a list of help topics that explain how the keyword is used in Windows PowerShell. Let’s add a GetHelp() method to the Keyword class that returns the first help topic in each reference set.<\/p>\n
The syntax of a class method is as follows.<\/p>\n
    [OutputType] Name (Parameters)<\/pre>\n