I'm not an expert on powershell but today I came across this line of code (note that Write-Output is only used as an example):
"Foo" | Write-Output
I wonder if it is any different from what I would expect:
Write-Output "Foo"
In effect the two statements should be equivalent:
In Write-Output "Foo", "Foo" is implicitly bound to positional parameter -InputObject, which accepts type PSObject[], i.e., an array of objects of any type.
In "Foo" | Write-Output, by virtue of parameter -InputObject being defined as optionally accepting pipeline input (by value, i.e. whole objects), "Foo" is also bound to -InputObject.
I assume you chose Write-Output as an example, but it's worth nothing that there's rarely a good reason to use that cmdlet explicitly - simply omitting it in your examples would yield the same results.
Furthermore, there are several cmdlets where the two forms are not equivalent, namely those where -InputObject is defined as a scalar (with exceptions); consider the following:
1, 2 | Get-Member # reports [System.Int32]
Get-Member -InputObject 1, 2 # reports [System.Object[]]
1, 2 | Get-Member reports the type members for each element in the input array.
Get-Member -InputObject 1, 2, by contrast, reports the members of the array type itself.
This difference in behavior is intentional and documented: using the parameter (-InputObject) allows inspecting collection types as a whole, whereas using the pipeline allows inspecting a collection's individual elements' types.
Note that there are cmdlets that exhibit the same difference in behavior, even though passing collections as a whole to them doesn't make much sense, such as Export-Csv; in such cases, always use the pipeline - see this GitHub issue for background information.
To determine what parameters of a cmdlet accept pipeline input and thus understand what parameter pipeline input will be bound to:
To see the parameters in the context of the full help topic:
Run Get-Help -Full <cmdlet>; using -Full is crucial.
Search for occurrences of true (, which will match parameters that accept:
pipeline input by value (whole object) only: true (ByValue)
pipeline input by property name only: true (ByPropertyName)
either: true (ByValue, ByPropertyName)
More generally, each parameter description has an Accept pipeline input? line item followed by a Boolean.
To extract just the names and their aliases, data types, and binding characteristics (using Rename-Item as an example):
Get-Help Rename-Item -Parameter * | Where-Object pipelineInput -like 'true*' |
Select-Object Name, Aliases, Type, pipelineInput
Related
I need to get the value of an environment variable from a kubernetes pod. I have my values listed in a hash table.
I call
$hash["service-testurl"].spec.template.spec.containers.env
And it returns a table:
name value
---- -----
ADDR https://test.com
TOKEN 123456789
CERT_PATH public-certs/test
ENVIRONMENT dev
I need to get https://test.com into a variable in my ps1 script, but i'm not sure how to get this value. (consider that for each deployment the url will be different, like abc.com, def.com, ghj.com... so i can't filter by the name test.com)
I was looking for something like $hash["service-testurl"].spec.template.spec.containers.env.name["ADDR"].value
Running $hash["service-testurl"].spec.template.spec.containers.env.PSTypeNames returns
System.Object[]
System.Array
System.Object
To complement your own effective solution:
Even though your display output of $hash["service-testurl"].spec.template.spec.containers.env looks like the representation of a (single) hashtable, the value is actually:
(a) an array, as your diagnostic output with .pstypenames demonstrates,
(b) whose elements are (presumably) [pscustomobject] instances that each have a a .name and a .value property (an easy way to tell is that the display output's column headers are name and value, whereas with hashtables they would be Name and Value).
Leaving aside that the identifier ADDR is a property value rather than a property / key name in your case, you fundamentally cannot use key-based index notation (['ADDR']) on an array - that generally only works on a (single) hashtable (or, more generally, dictionary).[1]
In your case, you need to find the array element whose .name property value is 'ADDR', which then allows you to return its .value property value.
For collections already in memory, the intrinsic .Where() method (as used in your own solution) is a more efficient - and more flexible - alternative to filtering a collection via the Where-Object cmdlet.
It will often not matter in practice, but you can optimize a .Where() call to stop filtering once the first match has been found, if you expect or are only interested in one match:
$hash["service-testurl"].spec.template.spec.containers.env.Where(
{ $_.name -eq 'ADDR' },
'First'
).value
Note that .Where() always returns an array-like collection, even if only a single value is matched - see this answer for details. As such, the .value property access is attempted on that collection, which, however, still works as intended, courtesy of the PowerShell feature known as member-access enumeration.
Note how using (...) around the arguments is now a syntactic necessity.
While with only a single argument - the filter script block ({ ... }) - you can get away with not using (...) - .Where{ $_.name -eq 'ADDR' } as shorthand for .Where({ $_.name -eq 'ADDR' }) - omitting the (...) is problematic for two reasons:
Given that the Where-Object cmdlet can also be referred to as Where (via a built-in alias), the two command forms could be confused, and given that Where-Object allows and is typically used with a space separating the command name from its script-block argument (e.g, 1..3 | Where { $_ -eq 2 }, it is tempting to also try to use a space with the .Where() method, which does not work:
# !! BROKEN, due to space before "{"
(1..3).Where { $_ -eq 2 }
If you add another argument later, you need to remember to use (...)
[1] The fact that key-based index notation does not work with member-access enumeration, i.e. doesn't work on an array of hashtables (only dot notation does, which PowerShell supports for hashtables too) could be considered an inconsistency; e.g. #( #{ foo=1 } ).foo works (dot notation), but #( #{ foo=1 } )['foo'] does not, due to the array wrapper.
However, this inconsistency was declared to be by design - see GitHub issue #17514.
I was able to do it with something similar that #iRon proposed:
$hash["service-testurl"].spec.template.spec.containers.env.where{$_.name -eq 'ADDR'}.value
Thanks!
There is a PowerShell cmdlet Invoke-MgSubscribeGroup that I want to call this way:
Invoke-MgSubscribeGroup -GroupId da2d17a7-64a5-43e5-9d95-7b70333dd78c
#{ UserId = "ed3d927d-7999-459f-955d-2afc272bd4d4" }
(Split into multiple lines for better readability)
When calling it, I get en error message:
A positional parameter cannot be found that accepts argument "System.Collections.Hashtable".
Since I'm not that deep into PowerShell I must have some false understanding of how to pass a hashtable, or I have misunderstood the documentation that says:
...To create the parameters described below, construct a hash table containing the appropriate properties...
My question
What is the correct syntax to call the Invoke-MgSubscribeGroup cmdlet and pass the user ID?
To elaborate on your own answer:
PowerShell's syntax diagrams - available locally via Invoke-MgSubscribeGroup -? or Get-Command -Syntax Invoke-MgSubscribeGroup - contain all the relevant information.
That said, they're not easy to read, especially locally, and there's room for future improvement.
Quoting from Invoke-MgSubscribeGroup's documentation:
Invoke-MgSubscribeGroup
-GroupId <String>
# ...
Invoke-MgSubscribeGroup
-InputObject <IGroupsIdentity>
# ...
Each (partial) quote represents a distinct parameter set, i.e. a unique combination of parameters representing a distinct feature group.
That -GroupId and -InputObject are in different parameter sets and are exclusive to each, tells you that you cannot use them both in a given invocation (they way you mistakenly tried), i.e., that they are mutually exclusive.
Additionally, given that the parameter names -GroupId and -InputObject are not enclosed in [...] means that you can only pass named, not positional arguments to them - that is, you must precede an argument to bind to these parameters with the parameter name; e.g, -GroupId foo rather than just foo.
By convention, a parameter named -InputObject is typically used to represent values that can be supplied via the pipeline, as evidenced by the parameter's description stating Accept pipeline input: True - locally, you can see this with either Get-Help -Full Invoke-MgSubscribeGroup or - parameter-specifically - with Get-Help Invoke-MgSubscribeGroup -Parameter InputObject
Often, multiple input objects can only (meaningfully) be supplied via the pipeline; that is, -InputObject is often a mere implementation detail whose purpose is to facilitate pipeline input - see GitHub issue #4242.
GitHub issue #4135 proposes making syntax diagrams directly reflect which parameters accept pipeline input.
What complicates matters with respect to Invoke-MgSubscribeGroup's documentation, specifically (which seems to be very sparse in general):
The help topic contains no examples (which you could normally request locally with Get-Help -Examples Invoke-MgSubscribeGroup)
The data type of the -InputObject parameter, <IGroupsIdentity> (Microsoft.Graph.PowerShell.Models.IGroupsIdentity) doesn't seem to have its own documentation; it is only described in the "Notes" section of the help topic, as accepting a hashtable (#{ ... }), along with a list of the supported entries (keys and value types).
All that said: you could have passed your hashtable via the pipeline, as follows:
#{
UserId = 'ed3d927d-7999-459f-955d-2afc272bd4d4'
GroupId = 'da2d17a7-64a5-43e5-9d95-7b70333dd78c'
} | Invoke-MgSubscribeGroup
The advantage of this approach over passing an argument to -InputObject is that it would allow you to pass multiple hashtables to act on.
After further investigating and reading the documentation again and again, I've found the correct syntax:
Invoke-MgSubscribeGroup -InputObject #{
UserId = "ed3d927d-7999-459f-955d-2afc272bd4d4";
GroupId = "da2d17a7-64a5-43e5-9d95-7b70333dd78c" }
(Split into multiple lines for better readability)
I now face permission issues, but this is out-of-scope for this question, since I've asked for the correct syntax only.
So I need to return the alias of ipconfig.exe but when I look for ipconfig I don't get any result. It's like this command is not working with the camp at the right of the arrow, so how is the correct command to look what is the alias of ipconfig?
To look up an alias by its name or name wildcard pattern, use Get-Alias -Name:
# Note: The (first) positional argument implies -Name
Get-Alias *config*
To look up an alias by its definition (wildcard patterns also accepted), use the -Definition parameter:
Get-Alias -Definition *config*
As for what you tried:
It's natural to think that, given that Get-Alias's for-display output formatting reports both the alias name and its definition in its Name display column (separated with ->), that the underlying .Name property of the underlying System.Management.Automation.AliasInfo type also contains that information.
However, the Name display column is an artifact of the formatting data associated with the output type, which provides a concise representation of aliases that combines two of the underlying type's properties, namely the .Name property, which contains the alias' name only, and the separate .Definition property, containing the alias' definition (only), which is the one that Get-Alias's -Definition parameter acts on.
As Olaf suggests, you can pipe the output from Get-Alias to the Get-Member cmdlet in order to reflect on the output type (to see its properties and methods and, if applicable, events).
In other words: Your original approach would have worked if you had targeted the .Definition property in your Where-Object call instead - but using the -Definition parameter is both more concise and more efficient:
# Less efficient equivalent of:
# Get-Alias -Definition *config*
Get-Alias | Where-Object Definition -match config
The documentation for ForEach-object says "When you use the InputObject parameter with ForEach-Object, instead of piping command results to ForEach-Object, the InputObject value is treated as a single object." This behavior can easily be observed directly:
PS C:\WINDOWS\system32> ForEach-Object -InputObject #(1, 2, 3) {write-host $_}
1 2 3
This seems weird. What is the point of a "ForEach" if there is no "each" to do "for" on? Is there really no way to get ForEach-object to act directly on the individual elements of an array without piping? if not, it seems that ForEach-Object with InputObject is completely useless. Is there something I don't understand about that?
In the case of ForEach-Object, or any cmdlet designed to operate on a collection, using the -InputObject as a direct parameter doesn't make sense because the cmdlet is designed to operate on a collection, which needs to be unrolled and processed one element at a time. However, I would also not call the parameter "useless" because it still needs to be defined so it can be set to allow input via the pipeline.
Why is it this way?
-InputObject is, by convention, a generic parameter name for what should be considered to be pipeline input. It's a parameter with [Parameter(ValueFromPipeline = $true)] set to it, and as such is better suited to take input from the pipeline rather passed as a direct argument. The main drawback of passing it in as a direct argument is that the collection is not guaranteed to be unwrapped, and may exhibit some other behavior that may not be intended. From the about_pipelines page linked to above:
When you pipe multiple objects to a command, PowerShell sends the objects to the command one at a time. When you use a command parameter, the objects are sent as a single array object. This minor difference has significant consequences.
To explain the above quote in different words, passing in a collection (e.g. an array or a list) through the pipeline will automatically unroll the collection and pass it to the next command in the pipeline one at a time. The cmdlet does not unroll -InputObject itself, the data is delivered one element at a time. This is why you might see problems when passing a collection to the -InputObject parameter directly - because the cmdlet is probably not designed to unroll a collection itself, it expects each collection element to be handed to it in a piecemeal fashion.
Consider the following example:
# Array of hashes with a common key
$myHash = #{name = 'Alex'}, #{name='Bob'}, #{name = 'Sarah'}
# This works as intended
$myHash | Where-Object { $_.name -match 'alex' }
The above code outputs the following as expected:
Name Value
---- -----
name Alex
But if you pass the hash as InputArgument directly like this:
Where-Object -InputObject $myHash { $_.name -match 'alex' }
It returns the whole collection, because -InputObject was never unrolled as it is when passed in via the pipeline, but in this context $_.name -match 'alex' still returns true. In other words, when providing a collection as a direct parameter to -InputObject, it's treated as a single object rather than executing each time against each element in the collection. This can also give the appearance of working as expected when checking for a false condition against that data set:
Where-Object -InputObject $myHash { $_.name -match 'frodo' }
which ends up returning nothing, because even in this context frodo is not the value of any of the name keys in the collection of hashes.
In short, if something expects the input to be passed in as pipeline input, it's usually, if not always, a safer bet to do it that way, especially when passing in a collection. However, if you are working with a non-collection, then there is likely no issue if you opt to use the -InputObject parameter directly.
Bender the Greatest's helpful answer explains the current behavior well.
For the vast majority of cmdlets, direct use of the -InputObject parameter is indeed pointless and the parameter should be considered an implementation detail whose sole purpose is to facilitate pipeline input.
There are exceptions, however, such as the Get-Member cmdlet, where direct use of -InputObject allows you to inspect the type of a collection itself, whereas providing that collection via the pipeline would report information about its elements' types.
Given how things currently work, it is quite unfortunate that the -InputObject features so prominently in most cmdlets' help topics, alongside "real" parameters, and does not frame the issue with enough clarity (as of this writing): The description should clearly convey the message "Don't use this parameter directly, use the pipeline instead".
This GitHub issue provides an categorized overview of which cmdlets process direct -InputObject arguments how.
Taking a step back:
While technically a breaking change, it would make sense for -InputObject parameters (or any pipeline-binding parameter) to by default accept and enumerate collections even when they're passed by direct argument rather than via the pipeline, in a manner that is transparent to the implementing command.
This would put direct-argument input on par with pipeline input, with the added benefit of the former resulting in faster processing of already-in-memory collections.
The following two commands produce different output.
Get-ChildItem | Sort-Object -Property Length
Get-ChildItem | Sort-Object -Property Len
Len is not a member of System.IO.FileInfo. Is PowerShell matching Len to the Length member? If not, then why is there no error message saying that Len is not a property?
No, its not member of System.IO.FileInfo as you can see by adding the -Debugswitch:
Get-ChildItem | Sort-Object -Property Len -Debug
Output looks like:
DEBUG: "Sort-Object" - "Len" cannot be found in "InputObject".
I guess the reason for that is the defensive implementation of the cmdlet:
If an object does not have one of the specified properties, the
property value for that object is interpreted by the cmdlet as Null
and is placed at the end of the sort order.
To complement Martin Brandl's helpful answer with more general information:
While PowerShell's elastic syntax only applies to parameter names (e.g., specifying just -p for -Property) , not values (arguments), you do have options for completing values:
At edit time: use tab completion:
This works on the command line as well as in Visual Studio Code with the PowerShell extension installed (where you'll get IntelliSense as well), as long as PowerShell can statically infer the output type(s)[1]
of the command in the previous pipeline segment.
At runtime:
Sort-Object and several other cmdlets allow you to use a wildcard expression to match property names:
Get-ChildItem | Sort-Object -Property Len* # "Len*" matches "Length"
Note that multiple properties may match, and that a given parameter must be explicitly designed to support wildcards (unlike in POSIX-like shells, it is not PowerShell itself that resolves the wildcards).
When accessing a nonexistent property on an object directly, no error is reported by default, and $null is returned:
(Get-Item /).Foo # Outputs $null as the value of nonexistent property "Foo"
By contrast, if Set-StrictMode -Version 2 or higher is in effect, a (statement-terminating) error is reported in that case, but note that Set-StrictMode does not apply when passing property names as arguments, such as to Sort-Object above.
As for a possible motivation for why Sort-Object doesn't enforce the existence of specified properties:
PowerShell allows you to pass objects that are any mix of types as input through the pipeline, with the objects getting passed one at a time.
(Similarly, PowerShell's default array type is [object[]], which allows you to create mixed-type arrays such as 1, 'hi', $True)
Even with (potentially) homogeneous input (such as the [System.IO.FileInfo] instances emitted by Get-ChildItem -File, for instance), a receiving command cannot detect that case up front, because it only ever sees one object at a time.
In general, cmdlets should be able to handle a mix of types among the input gracefully, and treating nonexistent properties as $null is overall the better choice, especially given that:
a cmdlet may still be able to act meaningfully on the input if at least a subset of the input objects have the property of interest (see below).
a cmdlet cannot know in advance whether that subset is empty.
Example with heterogeneous input:
Send an array of custom objects through the pipeline and sort it by property val, which one of the objects lacks:
[pscustomobject] #{ n = 'o1'; val = 2 },
[pscustomobject] #{ n = 'o2' },
[pscustomobject] #{ n = 'o3'; val = 1 } | Sort-Object val
Output:
n val
- ---
o3 1
o1 2
o2
Sorting was performed among all the input objects that do have a .val property, whereas those that don't were placed at the end, as stated in the quote from Sort-Object's documentation in Martin's answer.
[1] This should be true of all built-in cmdlets; to ensure that it works with custom functions, define them with [OutputType(<type>)] attributes - see this answer of mine for more.