How to investigate an unknown method in powershell? - powershell

Question

I'm learning Powershell by myself .There are tons of information around about the most common things, however when I'm faced with a slightly too specific thing, either I follow someone's previous steps or I'm lost. For instance, I don't know how to get help for specific methods. I'll give you my current situation as an example, however the question is about any case, not only this one.
I'm trying to automate some Internet Explorer browsing, and for that I'm using this guide.
However it only shows an example on GetElementsByTagName. I already know how to use Get-MemberSo I follow his code like this:
$ie = new-object -ComObject "InternetExplorer.Application"
$ie.silent = $true
$ie.navigate($requestUri)
while($ie.Busy) { Start-Sleep -Milliseconds 100 }
$doc = $ie.Document
After that I use Get-Member -InputObject $doc so I know all possible methods and I see the one I need: GetElementByID. I try to use it like this:
PS C:\Users\Myuser> $main=$doc.getElementById("main")
Cannot find an overload for "getElementById" and the argument count: "1".
At line:1 char:1
+ $main=$doc.getElementById("main")
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [], MethodException
+ FullyQualifiedErrorId : MethodCountCouldNotFindBest
I get that it expects more than one argument, but I don't know how to get or find any documentation about it.
What's your go-to when you want to know what a function/method does and what does it expect?

Answer 1

PowerShell offers a very convenient way to inspect method and even constructor signatures (overloads):
Simply access the method name without parentheses, and PowerShell will show you all overloads (signatures) defined for this method; .e.g:
# Method
PS> 'foo'.ToUpper # Inspect the .ToUpper() method - NO () at the end.
OverloadDefinitions
-------------------
string ToUpper()
string ToUpper(cultureinfo culture)
# Constructors, via a type literal (`[...]`) and its pseudo static new() method:
PS> [xml]::new # Constructors for [xml] (System.Xml.XmlDocument)
OverloadDefinitions
-------------------
xml new()
xml new(System.Xml.XmlNameTable nt)
This technique generally also works for COM objects, such as in your case:
$ie = New-Object -ComObject InternetExplorer.Application
$ie.Navigate('http://example.org')
$ie.Document.getElementById # Get signatures for .getElementById()
In Windows PowerShell v5.1 on Windows 10 this yields (abridged):
OverloadDefinitions
-------------------
mshtml.IHTMLElement ... getElementById(string v)
mshtml.IHTMLElement ... DispHTMLDocument.getElementById(string v)
mshtml.IHTMLElement ... IHTMLDocument3.getElementById(string v)
Caveat: For some COM objects, the signatures are listed without parameter names in versions before PowerShell Core v7, which can make it much harder to understand what it does.
For instance, COM Automation server WScript.Shell is affected:
Windows PowerShell and PowerShell Core 6.x:
PS> (New-Object -ComObject WScript.Shell).Popup
OverloadDefinitions
-------------------
int Popup (string, Variant, Variant, Variant) # !! No parameter names.
In PowerShell Core 7.0 (preview 5):
PS> (New-Object -ComObject WScript.Shell).Popup
OverloadDefinitions
-------------------
int Popup (string Text, Variant SecondsToWait, Variant Title, Variant Type) # OK

Answer 2

For cmdlets, I look up the cmdlet online documentation (you can check on https://learn.microsoft.com or just google it). A shortcut to get to online documentation for most cmdlets is to use Get-Help cmdlet -Online. For example:
Get-Help Start-Process -Online
You can also use the help alias in place of Get-Help if you wish.
For .NET classes I also use https://learn.microsoft.com, but to make sure you get the right class and member, I will search for the full name including the namespace (you can see this when you pipe an object to Get-Member. From the class documentation, you can navigate to the member documentation on that class.
For WMI classes, once again I also look at https://learn.microsoft.com, searching for the WMI class name, and navigating to any member properties or functions attributed to that class.
Of course, this is all assuming you are looking for information on Microsoft constructs. If you are looking for third-party library documentation, you will need to reference that third-party's documentation.
In general, if you're not quite sure where to find API documentation on something, a good thing to try searching via any search engine is "LIBRARYNAME api documentation", where LIBRARYNAME could be either the library or class you want to find documentation for. Usually you'll find something relevant in the first few hits.