Introduction
This is the next installment in my series on creating objects in PowerShell. In the first installment we showed how to create an object using the class type introduced in PowerShell 5. That covered the basics, and in the last installment of this series we’ll cover some advanced techniques.
In the last two installment of this series, I covered the various ways to create objects using the PSCustomObject. We saw how to create it using the New-Object cmdlet, then how to add your custom properties to it using the Add-Member cmdlet. In the subsequent post we saw how to add new methods to it.
In this post, we’ll cover something new, creating an object based on C# code!
For all of the examples we’ll display the code, then (when applicable) under it the result of our code. In this article I’ll be using PowerShell Core, 7.2.1, and VSCode. The examples should work in PowerShell 5.1 in the PowerShell IDE, although they’ve not been tested there.
Additionally, be on the lookout for the backtick ` , PowerShell’s line continuation character, at the end of many lines in the code samples. The blog formatting has a limited width, so using the line continuation character makes the examples much easier to read. My post Fun With PowerShell Pipelined Functions dedicates a section to the line continuation character if you want to learn more.
To run a snippet of code highlight the lines you want to execute, then in VSCode press F8 or in the IDE F5. You can display the contents of any variable by highlighting it and using F8/F5.
Why C#
You may be asking yourself, why integrate C# code into PowerShell? Why not just define our objects using PowerShell? There are several reasons, especially if you are working with a team of C# developers, or are a C# developer yourself.
First, it can make testing your C# classes easy. You can code the class and save it in a .CS file. Then run some simple PowerShell to create a new object from your class and test its various properties and methods. This lets you make changes easily and test again. All without having to create a full blown C# project just to test.
It also allows for code reuse. Let’s say your C# developers have created a library to do some calculations, and you need to use one of the methods from that library, but that library expects you to pass in an object based on a class.
Let’s further the example, perhaps you have the task of reading in a CSV file, doing a calculation for each row, then outputting another CSV file, or maybe even a JSON file. This is a one time use, so you don’t want to go to the effort of creating a full blown C# project.
Using the techniques in this demo, you could simply access the C# file in which the class was defined, and generate an object from it in PowerShell. Then all you’d have to do is populate the object and pass it into the library to do the calculation, and output the result.
These are just a few simple examples, I’m sure you’ll come up with many more as the need arises. I’ll be honest, this isn’t something you will need to do a great deal, but when you do you’ll appreciate knowing how.
Embedding a C# Class in your PowerShell
In this first method, we’ll define a standard C# class within a here string then add it as a new data type in PowerShell. Once it exists as a type, we can then generate new objects from it. Let’s take a look at a very simple class definition.
$code = @"
using System;
public class SchemaTable
{
public string DatabaseName;
public string SchemaTableName(string pSchema, string pTable)
{
string retVal = ""; // Setup a return variable
retVal = pSchema + "." + pTable;
return retVal;
} // public SchemaTableName
public string FullName(string pSchema, string pTable)
{
string retVal = ""; // Setup a return variable
retVal = this.DatabaseName + "." + pSchema + "." + pTable;
return retVal;
} // public FullName
} // class SchemaTable
"@
If you’ve read this far I’m going to assume you are familiar with C#, at least the basics of it, so I’ll keep this explanation at a high level.
We start by declaring a class named SchemaTable. The next line declares a variable (which will become a property) called DatabaseName.
I then create the first of two functions (which will become our methods). The SchemaTableName simply takes the two passed in values of pSchema and pTable and concatenates them together with a period between them.
The second, FullName, takes the value in DatabaseName and concatenates them with the schema and table name parameters, again using a period as a separator in the return string.
Next, we need to add this class as a new data type in PowerShell. You are already familiar with many data types, such as int, string, and more. We simply want to add a new data type to our PowerShell environment.
To do so, we will use the Add-Type cmdlet.
Add-Type -TypeDefinition $code `
-Language CSharp
The first parameter, TypeDefinition, takes the C# code we defined in the here string. The second, Language, is pretty obvious. We simply need to let PowerShell know what language this code was written in.
As of right now, the only supported language is C#. Because of this, if you leave off the -Language CSharp parameter, it will default to C# as the language. I included it here for completeness, but will omit it for future examples in this post.
So now we’ve defined a class in C#, and have added it as a new data type in PowerShell. How then do we create an object from it?
We’ll turn to our old friend, New-Object.
$result = New-Object -TypeName SchemaTable
That’s it, that simple one line will create our new object based on the C# code we defined in the $code variable. You can even use Get-Member to display its properties and methods like you would with any other object.
$result | Get-Member
Result:
Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
FullName Method string FullName(string pSchema, string pTable)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
SchemaTableName Method string SchemaTableName(string pSchema, string pTable)
ToString Method string ToString()
DatabaseName Property string DatabaseName {get;set;}
It contains the standard methods and properties built into all objects, but it also has the three we defined: FullName, SchemaTableName, and DatabaseName.
We can use these properties and methods just like ones in any other object. Let’s set the DatabaseName property, then display it.
$result.DatabaseName = 'MyDB'
$result.DatabaseName
Result:
MyDB
Likewise, we can access the methods we created. Here’s the SchemaTableName method.
$result.SchemaTableName('ASchema', 'ATable')
Result:
ASchema.ATable
And for completeness, the FullName method.
$result.FullName('ASchema', 'ATable')
Result:
MyDB.ASchema.ATable
C# Classes with Static Methods
In the original post in this series on basic PowerShell classes, I mentioned the concept of static methods and properties. As static method or property is simply one that can be called without having to generate a new object.
While we’ll circle back around to discuss implementing static methods and properties in PowerShell classes in the final post in this series, it is likely you’ll encounter C# classes with static methods and properties. As such we’ll go ahead and cover them here, while we are talking C#.
In the code below, I’ve defined a class with one method, and labeled it as static. In reality you will encounter many classes that have a mix of static and non-static members, but for this post we’ll keep the example simple.
$code = @"
using System;
public class StaticSchemaTable
{
public static string FullName(string pSchema, string pTable)
{
string retVal = "";
retVal = pSchema + "." + pTable;
return retVal;
} // public static FullName
} // class StaticSchemaTable
"@
As you can see, I’ve simply used the static keyword as part of the FullName function declaration. I also changed the name of the class, otherwise the code is the same as the previous demo.
Now we need to add this as a new type in our current PowerShell session.
Add-Type -TypeDefinition $code
Calling our static method requires different syntax. First, it won’t be necessary to create an object from it. Second, we’ll need to use the full name of our class in brackets, followed by two colons. We then indicate the name of the static function to call, and pass in any parameters.
$result = [StaticSchemaTable]::FullName('MySchema', 'myTable')
$result
Result:
MySchema.myTable
Static methods and parameters aren’t something that’s used a great deal, but they are used so you should know how to handle them.
Creating an Object from A C# File
While it is certainly possible to embed C# code right in your PowerShell, this could lead to some issues. The moment a developer makes a change to their .cs file, you are now out of sync. You don’t want to have to keep cutting and pasting all the time.
It makes far more sense, then, to simply access the C# file with the class definition, and load it at run time.
First, you need to create a C# file with the sample code. Here is what I put in my .cs file:
using System;
public class StaticSchemaTableInFile
{
public static string FullName(string pSchema, string pTable)
{
string retVal = "";
retVal = pSchema + "." + pTable;
return retVal;
} // public static FullName
} // class StaticSchemaTableInFile
This is the same static class you just saw, with the minor change to the class name.
In the next sample, I simply build the path to the file name, then use the Get-Content to read it.
$csPath = 'C:\Users\arcan\OneDrive\BlogPosts\Markdown\'
$file = "$($csPath)Fun-With-PowerShell-Objects-Part 3.cs"
$code = Get-Content $file | Out-String
Get-Content will read the contents of the file. By default Get-Content reads it as an array with each line in the file being an element, so we’ll have to pipe it through the Out-String cmdlet to convert it to a single string. This string is then stored in the $code variable. Of course you’ll need to update the path and file variables you used on your computer.
Now we do just like the previous demo, call Add-Type then run it.
Add-Type -TypeDefinition $code
$result = [StaticSchemaTableInFile]::FullName('mySchema', 'myTable')
$result
Result:
mySchema.myTable
Again, I reused the example from the static demo but we could also have used the first example, or any standard C# file containing class definitions.
Other Ways To Add Types
While outside the scope of this post, I did want to mention there are two other ways you can add new data types to your PowerShell scripts. First, Add-Type will let you load types stored in an assmebly, in other words a .dll file.
Second, if you are running on a Windows computer you can add types stored in native Windows APIs. If you want to learn more about these, I’ll refer you to the Add-Type Documentation at Microsoft.
Persistance
One last thing you need to be aware of. When you add a type it does not persist between sessions. The moment you close your command window or VSCode, that type goes away. You’ll need to recreate it the next time you run your script.
This is probably a good thing, as it’s doubtful you will need to use these types on a daily basis. Should you need to, though, you’ll have to edit your PowerShell profile and have them added within it.
Conclusion
In this post we saw how to create custom objects from C# classes. They could be embedded in our PowerShell code, or stored in external files. The subject of static methods and properties were mentioned, along with a demo on how to use them.
In the next post we’ll see a very useful technique, and cover the ability to add our own custom methods and properties to existing objects that others created, including ones built right into PowerShell.
The demos in this series of blog posts were inspired by my Pluralsight course PowerShell 7 Quick Start for Developers on Linux, macOS and Windows, one of many PowerShell courses I have on Pluralsight. All of my courses are linked on my About Me page.
If you don’t have a Pluralsight subscription, just go to my list of courses on Pluralsight . At the top is a Try For Free button you can use to get a free 10 day subscription to Pluralsight, with which you can watch my courses, or any other course on the site.
Arcane Code 