9/10 times if you are trying to use the Invoke-Expression cmdlet, there is a better way. Building the arguments to a command dynamically? Use an array of arguments. Building the arguments to a cmdlet? Use splatting with an array or hashtable. Your command has a space in the path to it? Use the call operator (&).
This might seem open ended, but Invoke-Expression is an easily accessible cmdlet where the answer is almost always to never use it. But the cmdlet exists for a reason, is not deprecated, and most criticisms of its use state something similar to, "it's almost never the right answer", but never states when it is acceptable to use it. In what case is it acceptable to use Invoke-Expression? Or to word it a bit less openly, how was Invoke-Expression designed to be used?
To quote from a PowerShell team blog post titled Invoke-Expression considered harmful (emphasis added):
The bottom line: Invoke-Expression is a powerful and useful command for some scenarios such as creating new scripts at runtime, but in general, if you find yourself using Invoke-Expression, you should ask yourself, or maybe a respected colleague if there is a better way.
EBGreen notes:
Or to phrase it another way, It [Invoke-Expression] is ok to use as long as a user is never involved in any part of generating the string that will be invoked. But even then, not using it will enforce better habits than using it would.
In short:
As a matter of habit, always consider a different (usually more robust and secure) solution first.
If you do find that Invoke-Expression is your only choice, carefully consider the security implications: if a string from an (untrusted) outside source (e.g., user input) is passed directly to Invoke-Expression, arbitrary commands may be executed.
Therefore: Only use Invoke-Expression if you fully control or implicitly trust the input.
Note: As of Windows PowerShell v5.1 / PowerShell Core v6.1.0, the official Invoke-Expression help topic doesn't provide such guidance; this GitHub issue suggests rectifying that.
Rare examples of justified (safe) use of Invoke-Expression:
Creating PSv5+ custom classes dynamically:
so that the class can be used in a remote session.
so that the set of properties can be created based on conditions at runtime.
Using Invoke-Expression in combination with Write-Output:
to parse a string with embedded quoting, with extra precautions.
to parse command lines stored in a file, if trusted.
Using Invoke-Expression for nested property access:
via a property path stored in a string.
Related
I've been trying to work with an API that only accepts raw text or base64 encoded values in a JSON object. The content I'm POSTing is data from an XML file. So I used Powershell's Get-Content cmdlet (without -Raw) to retrieve the data from the .xml and then base64 encode it and sent it to the API. The API then decodes it, but the XML formatting was lost.
I found a SO post about using the -Raw switch on Get-Content, but it seems like the documentation for this switch is vague. When I used the -Raw switch, encoded it and sent it back to the API, the formatting was good.
briantist's helpful comment on the question sums up the answer succinctly (in his words; lightly edited, emphasis added):
Get-Content [by default] reads a file line by line and returns an array of the lines. Using -Raw reads the entire contents of the file as a single string.
The name -Raw is tad unfortunate, because it mistakenly suggests reading raw bytes, whereas -Raw still detects encodings and ultimately reads everything into a .NET [string] type.
(By contrast, you need either -Encoding Byte (Windows PowerShell) or -AsByteStream (PowerShell Core) to read a file as a byte array.)
Given -Raw's actual purpose, perhaps something like -Whole would have been a better name, but that ship has sailed (though adding an alias name for a parameter is still an option).
Let's take a look at why this information may currently be difficult to discover [Update: It no longer is]:
[Update: This section is now OBSOLETE, except the link to the PowerShell documentation GitHub repository, which welcomes contributions, bug reports, suggestions]
A Tale of PowerShell Documentation Woes
The central conflict of this tale is the tension between the solid foundation of PowerShell's potentially great help system and its shoddy current content.
As is often the case, third parties come to the rescue, as shown in gms0ulman's helpful answer.
As briantist also points out, however, PowerShell's documentation is now open-source and welcomes contributions; he states:
"I will direct your attention to the Edit link
[for the Get-Content help topic on GitHub] [...] so you can actually fix it up and submit something better
(including examples). I have done it before; they do accept pull
requests for it."
The caveat is that while future PowerShell Core versions will benefit from improvements, it's not clear whether improvements will make their way back into Windows PowerShell.
Let's ask PowerShell's built-in help system, accessible via the standard Get-Help cmdlet (the content for which may not be preinstalled; install when prompted, or run Update-Help from an elevated session):
Get-Help Get-Content -Parameter Raw
Note how you can conveniently ask for help on a specific parameter (-Parameter Raw).
On Windows PowerShell v5.1, this yields:
-Raw
Ignores newline characters and returns the entire contents of a file in one string.
By default, the contents of a file is returned as a array of strings that is delimited
by the newline character.
Raw is a dynamic parameter that the FileSystem provider adds to the Get-Content cmdlet.
This parameter works only in file system drives.
This parameter is introduced in Windows PowerShell 3.0.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
That is indeed what we were looking for and quite helpful (leaving the awkward phrasing "delimited by the newline character" aside and that on Windows a newline is a character sequence).
On Powershell Core v6.0.2, this yields:
-Raw
Required? false
Position? Named
Accept pipeline input? false
Parameter set name (All)
Aliases None
Dynamic? true
While the meta-data is more detailed - including a hint that the parameter is dynamic (see below) - it is crucially missing a description of the parameter.
Some provider-cmdlet parameters are dynamic, in that they are specific to a given provider, so there is a mechanism to specify the target provider when asking for help, by passing a provider-specific example path to the -Path parameter.
In the case at hand, let's therefore try (PowerShell Core on Windows):
Get-Help Get-Content -Parameter Raw -Path C:\
Sadly, the result is the same unhelpful response as before.
Note that, as long as you're invoking the command from a filesystem location, explicit use of -Path should not be necessary, because the provider underlying the current location is implicitly targeted.
Now let's take a look at the online versions of PowerShell's help topics:
As it turns out, a given provider cmdlet can have multiple documentation pages:
A generic one that applies to all providers.
Provider-specific pages that document provider-exclusive behavior and parameters, such as -Raw for the filesystem provider.
Sadly, the generic topics make no mention of the existence of the provider-specific ones, making them hard to discover.
Googling Get-Content takes you to https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content, the generic topic, which contains the following misleading statement: This parameter is not supported by any providers that are installed with Windows PowerShell.
This is not only unhelpful, but actively misleading, because the PowerShell file-system provider clearly is installed with PowerShell and it does support -Raw.
[Drive] providers are PowerShell's generalization of the filesystem drive metaphor to support targeting other [typically hierarchical] storage systems with a unified set of cmdlets. For instance, Windows PowerShell also ships with the registry drive provider, which allows managing the registry as if it were a drive.
The -Online switch for Get-Help conveniently allows opening the online version of the requested topic in the browser; so let's try that (Get-Help Get-Content -Online):
Windows PowerShell v5.1: Takes you a 404 page(!) related to v4.
PowerShell Core v6.0.1: Takes you to the same generic topic that googling does.
There's a sliver of hope, however: The aforementioned 404 page offers a link to the filesystem-provider-specific topic:
Get-Content for FileSystem
It is there that we finally discover the online version of the truly relevant, provider-specific information, which is the same that Get-Help Get-Content -Parameter Raw provides locally, but - as stated - only in Windows PowerShell.
As per Kory Gill's comment and your own, the built-in Get-Help and MSDN documentation should be your first port of call. But you've already RTFM!
When that fails, ss64 is great reference for Powershell documentation and additional examples.
Get-Content page here. It has this to say about -Raw:
Return multiple lines as a single string (PowerShell 3.0)
In PowerShell 2.0 use the static method: [System.IO.File]::ReadAllText(string path)
I'm new to PowerShell scripting and am looking to create ps1 scripts that I can used as cmdlets. My background is in using strongly typed variables, but I'm struggling to find how (or if) it is possible to ensure that all user variables in a script are explicitly typed. Some languages only allow explicitly typed variables. VBA allows the directive "Option Explicit" and I was hoping to find some way to achieve the same in any PSH scripts I create.
I've done a lot of searching (google, stackoverflow etc.) but not found anything. If there is no way to force all variable definitions to be explicitly typed, I'll have to write a cmdlet to parse my scripts to find any implicitly typed variables ... but hoping for a better solution.
I don't think you can do that in PowerShell. Closest you can get is to use Set-StrictMode which will, among other things, prohibit use of uninitialized variables.
But if you want to parse the scripts, maybe don't write your own solution. Use PSScriptAnalyzer module. It has a lot of built-in rules, unfortunately none for checking explicit types. But you can define your own rules, and maybe someone already created the one you're looking for and posted it somewhere.
While I did find a lot of information on how to name Cmdlets and functions in the Cmdlet Development Guidelines I did not find any information on whether functions should be named in upper or in lower case.
What is the convention here?
(I do understand that Cmdlets themselves are generally named in upper case, even though they are not case-sensitive when it comes to executing.)
Naming convention can be tricky. While a fixed naming convention may provide aesthetics or simplified usage, it is not required to be followed. In general, a naming convention that I advocate for is the one that is used already in Powershell. As functions are created on verb-noun base, each word starts with a capital letter or if it is an abbreviation - all capitals, or if it is a proprietary - then as it is accordingly.
I have, for example, created some functions for myself:
Get-ServerDiag
Mount-TrueCryptVolumes
Start-RDP
Generate-RandomPassword
Nuke-Environment
You can imagine what these functions do, it is rather clear, straightforward and compliant with built-in Powershell functions. I do however have exceptions which come from "importing" a several Unix commands to Powershell (like killall, pidof etc...) You can always use a Set-Alias if you prefer to write something else.
This question, however important, is discussable as there does not seem to be the 'one, best way'. It is all, in the end, up to personal preferences.
A function is mostly a script-based cmdlet. A cmdlet is written in ex. C#, while a function is written as a script. Because of this similarity, I recommend using the same style as cmdlets for my "standalone-functions" so that it blends in with the other PowerShell cmdlets. Ex. I had a filecount(per folder)-function that I used often. I called it Get-FileCount.
However, I usually name helper functions(functions you only use in other functions) using a simpler name like convertsidtousername etc.
You could use aliases to create short names for a function.
I've got a PowerShell function Download-File, which uses WebClient.DownloadFile -- hence the name.
When I attempt to turn my .ps1 script into a .psm1 module, PowerShell warns me that "Download" is not in the list of recommended verbs.
What's a good alternative? Get- seems to be about getting properties, rather than contents (apart from Get-Content, oddly). Receive- seems a bit too passive for my liking (i.e. the script blocks until the information is sent) -- which doesn't fit well.
Ideas?
For me, 'Get' is the most natural verb. It gets everthing, not just properties. For the noun I would use something like 'WebFile', you can easily guess what you get and where it is coming from.
Wouldn't this work:
Start-Download -Url http://blah/
Or use Invoke-Download, as per the recommendations for synchronous operations. Start is for asynchronous.
What about New-Download or New-WebDownload or New-DownloadFile??
Maybe Request-TeamCityArtifacts?
https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?view=powershell-7.2
There is no synonym for download.
Copy is the closest I've found, being documented as a synonym of the unapproved Clone.
What's the best way to ensure your PowerShell function name is unique? The standard since version 1 is to put in a short unique id after the verb dash and before the noun. For example, with my initials I could create function Get-DWServer; this is fine until someone creates a function in a different module for getting an object reference to a datawarehouse and uses the same function name. Two or three letters just isn't sufficient but more than that gets ugly to read.
I'd prefer to have a unique prefix* similar to .NET namespaces. It's better for organization, easier on the eye and works with tab completion. And it expands gracefully so you could name it DW.Get-Server or DW.Network.Get-Server.
The downside of doing this is it runs afoul of PowerShell's proper verb check during module import/Export-ModuleMember. You can get around this by specifying DisableNameChecking during import but I'm wondering if doing this is sloppy and might be bad if PowerShell 3 comes out with a better solution. I know PS verb purists (are there any?) will complain that this probably 'hinders discovery' but I can't think of a better option.
What do you do?
(*You can refer to an exported function using module_name\function_name notation but this won't work with tab completion and still doesn't get around the problem of the function name being unique).
I have heard Jeffrey Snover (the inventor of PowerShell) talk about this a few times and he described it as a dilemma, not a problem. A dilemma has to be managed but can't be solved completely. A problem can be solved. As a PS verb "purist" I would say the best way to manage this is to have a 2 or 3 letter prefix to your nouns. This has been sufficient so far for many widely distributed sets of cmdlets. IE, Quest AD Cmdlets vs Microsoft's AD Cmdlets. Get-ADUser and get-qaduser.
If you are consuming a module and want to use your own prefix, you can specify one with
import-module mymodule -Prefix myPrefix
I know this isn't the one single silver bullet answer, but I would say it works for 95% of the situations.