The PowerShell AST essentially breaks down the code into a hierarchical tree with each element representing a part of the tree, making the scripts self aware.
Have you ever seen the movie Inception? It's about a guy that can enter someone's dreams and steal stuff from their subconscious. It's a trip that will leave you questioning the reality around you. It gave me that same feeling as The Matrix did, like reality is not what you believe it to be. It's some deep stuff. This has nothing to do with PowerShell, but it gives you a sense of what the PowerShell Abstract Syntax Tree (AST) does.
Imagine a PowerShell script that is self-aware. Imagine a PowerShell script that can read itself, or even generate other scripts based on what's contained in itself. Think of it as meta-scripting. It's a neat concept and has a lot of practical uses! This is what the PowerShell AST can do. The PowerShell AST essentially breaks down the code into a hierarchical tree with each element representing a part of the tree.
In this article, I'm going to go over how you can use the PowerShell AST and go over a few examples of how it works to parse PowerShell code.
To get started, you'll need to get familiar with the System.Management.Automation.Language.Parser class. This is a class that contains a few applicable static methods that we can use to read scripts and code. This class has two methods that you'll routinely use called ParseInput() and ParseFile(), which essentially do the same thing. ParseInput() reads code as a big string while ParseFile() assists you in converting a text file containing PowerShell code and converts it into a string for parsing. Both end up with the same result.
Let's say I have a simple script with the following lines:
Write-Host 'I am doing something here'
Write-Verbose 'I am doing something here too'
Write-Host 'Again, doing something.'
$var1 = 'abc'
$var2 = '123'
From within the script itself, I'd like to determine all the references to each cmdlet I have and each variable. To do this, I'll first need to figure out a way to get the entire script contents as one, big string. I can do that by using the $MyInvocation.MyCommand.ScriptContents property. I'll just add this as the last line in the script and execute it.
Once I have the script contents, I can then pass this to the ParseInput() method as mentioned above to build a "tree" from my script. I'll replace that $MyInvocation.MyCommand.ScriptContents reference with below:
[System.Management.Automation.Language.Parser]::ParseInput($MyInvocation.MyCommand.ScriptContents, [ref]$null, [ref]$null)
This gets me an output that looks like this:
PS> C:\test.ps1
I am doing something here
Again, doing something.
Attributes : {}
UsingStatements : {}
ParamBlock :
BeginBlock :
ProcessBlock :
EndBlock : Write-Host 'I am doing something here'
Write-Verbose 'I am doing something here too'
Write-Host 'Again, doing something.'
$var1 = 'abc'
$var2 = '123'
[System.Management.Automation.Language.Parser]::ParseInput($MyInvocation.MyCommand.ScriptContents,
[ref]$null, [ref]$null)
DynamicParamBlock :
ScriptRequirements :
Extent : Write-Host 'I am doing something here'
Write-Verbose 'I am doing something here too'
Write-Host 'Again, doing something.'
$var1 = 'abc'
$var2 = '123'
[System.Management.Automation.Language.Parser]::ParseInput($MyInvocation.MyCommand.ScriptContents,
[ref]$null, [ref]$null)
Parent :
This doesn't do much good, though. I'd like a way to look into this and find only the function and variables contained in my script. To do that, I'll need to assign our AST to a variable. I'll call mine $ast.
PS> $ast = C:\test.ps1
This gets me an object that has various methods and properties I can now use.
PS> $ast | gm
TypeName: System.Management.Automation.Language.ScriptBlockAst
Name MemberType Definition
---- ---------- ----------
Copy Method System.Management.Automation.Language.Ast Copy()
Equals Method bool Equals(System.Object obj)
Find Method System.Management.Automation.Language.Ast Find(System.Func[System.Management.Automatio...
FindAll Method System.Collections.Generic.IEnumerable[System.Management.Automation.Language.Ast] Find...
GetHashCode Method int GetHashCode()
GetHelpContent Method System.Management.Automation.Language.CommentHelpInfo GetHelpContent()
GetScriptBlock Method scriptblock GetScriptBlock()
GetType Method type GetType()
SafeGetValue Method System.Object SafeGetValue()
ToString Method string ToString()
Visit Method System.Object Visit(System.Management.Automation.Language.ICustomAstVisitor astVisitor...
Attributes Property System.Collections.ObjectModel.ReadOnlyCollection[System.Management.Automation.Languag...
BeginBlock Property System.Management.Automation.Language.NamedBlockAst BeginBlock {get;}
DynamicParamBlock Property System.Management.Automation.Language.NamedBlockAst DynamicParamBlock {get;}
EndBlock Property System.Management.Automation.Language.NamedBlockAst EndBlock {get;}
Extent Property System.Management.Automation.Language.IScriptExtent Extent {get;}
ParamBlock Property System.Management.Automation.Language.ParamBlockAst ParamBlock {get;}
Parent Property System.Management.Automation.Language.Ast Parent {get;}
ProcessBlock Property System.Management.Automation.Language.NamedBlockAst ProcessBlock {get;}
ScriptRequirements Property System.Management.Automation.Language.ScriptRequirements ScriptRequirements {get;}
UsingStatements Property System.Collections.ObjectModel.ReadOnlyCollection[System.Management.Automation.Languag...
The most useful method to use is the FindAll() method. This is a method that allows you to query the AST itself looking for particular types of language constructs. In our case, we're looking for function calls and variable assignments.
Read: Managing IIS Web Application Pools In PowerShell
To only find the language constructs we're looking for, we must first figure out what class is represented by each type. In our examples, those classes are CommandAst for function calls and VariableExpression for variable assignments. You can view all of the different class types at the MSDN System.Management.Automation.Language namespace page.
Here I will find all of the function references.
PS> $ast.FindAll({$args[0] -is [System.Management.Automation.Language.CommandAst]}, $true)
CommandElements : {Write-Host, 'I am doing something here'}
InvocationOperator : Unknown
DefiningKeyword :
Redirections : {}
Extent : Write-Host 'I am doing something here'
Parent : Write-Host 'I am doing something here'
CommandElements : {Write-Verbose, 'I am doing something here too'}
InvocationOperator : Unknown
DefiningKeyword :
Redirections : {}
Extent : Write-Verbose 'I am doing something here too'
Parent : Write-Verbose 'I am doing something here too'
CommandElements : {Write-Host, 'Again, doing something.'}
InvocationOperator : Unknown
DefiningKeyword :
Redirections : {}
Extent : Write-Host 'Again, doing something.'
Parent : Write-Host 'Again, doing something.'
Let's now find all of the variable assignments as well.
PS> $ast.FindAll({$args[0] -is [System.Management.Automation.Language.VariableExpressionAst]},$true)
ariablePath : var1
Splatted : False
StaticType : System.Object
Extent : $var1
Parent : $var1 = 'abc'
VariablePath : var2
Splatted : False
StaticType : System.Object
Extent : $var2
Parent : $var2 = '123'
VariablePath : MyInvocation
Splatted : False
StaticType : System.Object
Extent : $MyInvocation
Parent : $MyInvocation.MyCommand
VariablePath : null
Splatted : False
StaticType : System.Object
Extent : $null
Parent : [ref]$null
VariablePath : null
Splatted : False
StaticType : System.Object
Extent : $null
Parent : [ref]$null
You can see that each construct now becomes an object you can work with. You now have the knowledge to break apart your script in just about any way you'd like. By using the AST, your PowerShell scripts now can become self-aware. Just don't blame me when your scripts start trying to take your job themselves!