Can I exclude a single function from Export-ModuleMember? - powershell

I have a large set of functions defined in a PowerShell script module. I want to use Export-ModuleMember -Function *, but I want to exclude just one function. It'll be easier for me to exclude this one function than to list all the included functions. Is there anyway to achieve this?

My stock answer about excluding functions is to use verb-noun naming for functions I want to export, and use initial caps for everything else.
Then, Export-ModuleMember -function *-* takes care of it.

Find all functions in a script and then filter based on what you want to exclude (assuming PowerShell v2):
$errors = $null
$functions = [system.management.automation.psparser]::Tokenize($psISE.CurrentFile.Editor.Text, [ref]$errors) `
| ?{(($_.Content -Eq "Function") -or ($_.Content -eq "Filter")) -and $_.Type -eq "Keyword" } `
| Select-Object #{"Name"="FunctionName"; "Expression"={
$psISE.CurrentFile.Editor.Select($_.StartLine,$_.EndColumn+1,$_.StartLine,$psISE.CurrentFile.Editor.GetLineLength($_.StartLine))
$psISE.CurrentFile.Editor.SelectedText
}
}
This is the technique I used for v2 to create a ISE Function Explorer. However, I don't see a reason why this won't work with plain text outside ISE. You need to workaround the caret line details though. This is just an example on how to achieve what you want.
Now, filter what is not required and pipe this to Export-ModuleMember!
$functions | ?{ $_.FunctionName -ne "your-excluded-function" }
If you are using PowerShell v3, the parser makes it a lot easier.

So I know this is way late to the party, but the simple solution is to place all functions you do not want exported AFTER the Export-ModuleMember cmdlet. Any Functions defined AFTER that statement will not be exported and WILL be available to your module (aka private functions).
Perhaps the more elegant method is to include a Module Definition file, and simply not include that function on the list of functions to include.
The idea of writing code inside the module to not include functions in the module seems overly complicated, this is not a new feature, I've been placing functions after Export since the very early days of PowerShell.

My solution, using PowerShell V3, as hinted by ravikanth (who was using V2 in his solution), is to define a PSParser module:
Add-Type -Path "${env:ProgramFiles(x86)}\Reference Assemblies\Microsoft\WindowsPowerShell\3.0\System.Management.Automation.dll"
Function Get-PSFunctionNames([string]$Path) {
$ast = [System.Management.Automation.Language.Parser]::ParseFile($Path, [ref]$null, [ref]$null)
$functionDefAsts = $ast.FindAll({ $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $true)
$functionDefAsts | ForEach-Object { $_.Name }
}
Export-ModuleMember -Function '*'
And in a module, if I want to exclude a given function, the last line would look like:
Export-ModuleMember -Function ( (Get-PSFunctionNames $PSCommandPath) | Where { $_ -ne 'MyPrivateFunction' } )
Note that this will only work in PowerShell V3 or later because the AST parser and $PSCommandPath were introduced in version 3.

Related

How to pass a custom function inside a ForEach-Object -Parallel

I can't find a way to pass the function. Just variables.
Any ideas without putting the function inside the ForEach loop?
function CustomFunction {
Param (
$A
)
Write-Host $A
}
$List = "Apple", "Banana", "Grape"
$List | ForEach-Object -Parallel {
Write-Host $using:CustomFunction $_
}
The solution isn't quite as straightforward as one would hope:
# Sample custom function.
function Get-Custom {
Param ($A)
"[$A]"
}
# Get the function's definition *as a string*
$funcDef = ${function:Get-Custom}.ToString()
"Apple", "Banana", "Grape" | ForEach-Object -Parallel {
# Define the function inside this thread...
${function:Get-Custom} = $using:funcDef
# ... and call it.
Get-Custom $_
}
Note: This answer contains an analogous solution for using a script block from the caller's scope in a ForEach-Object -Parallel script block.
Note: If your function were defined in a module that is placed in one of the locations known to the module-autoloading feature, your function calls would work as-is with ForEach-Object -Parallel, without extra effort - but each thread would incur the cost of (implicitly) importing the module.
The above approach is necessary, because - aside from the current location (working directory) and environment variables (which apply process-wide) - the threads that ForEach-Object -Parallel creates do not see the caller's state, notably neither with respect to variables nor functions (and also not custom PS drives and imported modules).
As of PowerShell 7.2.x, an enhancement is being discussed in GitHub issue #12240 to support copying the caller's state to the parallel threads on demand, which would make the caller's functions automatically available.
Note that redefining the function in each thread via a string is crucial, as an attempt to make do without the aux. $funcDef variable and trying to redefine the function with ${function:Get-Custom} = ${using:function:Get-Custom} fails, because ${function:Get-Custom} is a script block, and the use of script blocks with the $using: scope specifier is explicitly disallowed in order to avoid cross-thread (cross-runspace) issues.
However, ${function:Get-Custom} = ${using:function:Get-Custom} would work with Start-Job; see this answer for an example.
It would not work with Start-ThreadJob, which currently syntactically allows you to do & ${using:function:Get-Custom} $_, because ${using:function:Get-Custom} is preserved as a script block (unlike with Start-Job, where it is deserialized as a string, which is itself surprising behavior - see GitHub issue #11698), even though it shouldn't. That is, direct cross-thread use of [scriptblock] instances causes obscure failures, which is why ForEach-Object -Parallel prevents it in the first place.
A similar loophole that leads to cross-thread issues even with ForEach-Object -Parallel is using a command-info object obtained in the caller's scope with Get-Command as the function body in each thread via the $using: scope: this too should be prevented, but isn't as of PowerShell 7.2.7 - see this post and GitHub issue #16461.
${function:Get-Custom} is an instance of namespace variable notation, which allows you to both get a function (its body as a [scriptblock] instance) and to set (define) it, by assigning either a [scriptblock] or a string containing the function body.
I just figured out another way using get-command, which works with the call operator. $a ends up being a FunctionInfo object.
EDIT: I'm told this isn't thread safe, but I don't understand why.
function hi { 'hi' }
$a = get-command hi
1..3 | foreach -parallel { & $using:a }
hi
hi
hi
So I figured out another little trick that may be useful for people trying to add the functions dynamically, particularly if you might not know the name of it beforehand, such as when the functions are in an array.
# Store the current function list in a variable
$initialFunctions=Get-ChildItem Function:
# Source all .ps1 files in the current folder and all subfolders
Get-ChildItem . -Recurse | Where-Object { $_.Name -like '*.ps1' } |
ForEach-Object { . "$($_.FullName)" }
# Get only the functions that were added above, and store them in an array
$functions = #()
Compare-Object $initialFunctions (Get-ChildItem Function:) -PassThru |
ForEach-Object { $functions = #($functions) + #($_) }
1..3 | ForEach-Object -Parallel {
# Pull the $functions array from the outer scope and set each function
# to its definition
$using:functions | ForEach-Object {
Set-Content "Function:$($_.Name)" -Value $_.Definition
}
# Call one of the functions in the sourced .ps1 files by name
SourcedFunction $_
}
The main "trick" of this is using Set-Content with Function: plus the function name, since PowerShell essentially treats each entry of Function: as a path.
This makes sense when you consider the output of Get-PSDrive. Since each of those entries can be used as a "Drive" in the same way (i.e., with the colon).

Get All Functions In A PowerShell Script

I have a problem similar to this question. I want to get all the functions in a given PowerShell script but the difference being I don't want to execute the contents of the script and I don't want to execute the functions.
The intent is to be able to load all the functions into the runspace to be able to pull the comment-based help from each function for documentation purposes.
Does anyone have any magical tricks to just load the functions from a .ps1 without executing all the other code within that file?
I thought about using [System.Management.Automation.PSParser]::Tokenize() to parse the script file but that's a whole lot more work than I would like to do. If someone has something easier, I'd be delighted.
# I want to load this to get the comment-based help
Function Invoke-Stuff {
<#
.SYNOPSIS
Stuff doer
.DESCRIPTION
It does lots of stuff
.EXAMPLE
Invoke-Stuff
#>
Write-Host "Stuff was done"
}
# But I don't want to execute any of this
$Items = Get-ChildItem
$Items | ForEach-Object {
Invoke-Stuff
}
The AST is the way to go for static(ish) analysis. Here's how I would do what you described
$rs = [runspacefactory]::CreateRunspace()
$rs.Open()
# Get the AST of the file
$tokens = $errors = $null
$ast = [System.Management.Automation.Language.Parser]::ParseFile(
'MyScript.ps1',
[ref]$tokens,
[ref]$errors)
# Get only function definition ASTs
$functionDefinitions = $ast.FindAll({
param([System.Management.Automation.Language.Ast] $Ast)
$Ast -is [System.Management.Automation.Language.FunctionDefinitionAst] -and
# Class methods have a FunctionDefinitionAst under them as well, but we don't want them.
($PSVersionTable.PSVersion.Major -lt 5 -or
$Ast.Parent -isnot [System.Management.Automation.Language.FunctionMemberAst])
}, $true)
# Add the functions into the runspace
$functionDefinitions | ForEach-Object {
$rs.SessionStateProxy.InvokeProvider.Item.Set(
'function:\{0}' -f $_.Name,
$_.Body.GetScriptBlock())
}
# Get help within the runspace.
$ps = [powershell]::Create().AddScript('Get-Help MyFunction')
try {
$ps.Runspace = $rs
$ps.Invoke()
} finally {
$ps.Dispose()
}
You could also use the $tokens from near the top if you want to go a purely static route. The comments won't be in the AST but they will be in the tokens.
Edit The method above actually loses comment help somewhere in the process, not because of the runspace but just because of how the function is assigned. Likely due to the comments not really being a part of the AST. In any case there is a more direct and more static way to obtain the help.
Instead of defining the functions, you can use the GetHelpContent method on FunctionDefinitionAst
$helpContent = $functionDefinitions | ForEach-Object { $_.GetHelpContent() }
This will return a CommentHelpInfo object for each function. It's important to note that this is not the same object returned by the Get-Help cmdlet. Most notably it does not distinguish between things like the code and the description in an example block. However, if you need the CBH to be parsed as normal you can get the comment block text and define your own fake version.
$helpContent = $functionDefinitions | ForEach-Object {
# Get the plain string comment block from the AST.
$commentBlock = $_.GetHelpContent().GetCommentBlock()
# Create a scriptblock that defines a blank version of the
# function with the CBH. You may lose some parameter info
# here, if you need that replace param() with
# $_.Body.ParamBlock.Extent.Text
$scriptBlock = [scriptblock]::Create(('
function {0} {{
{1}
param()
}}' -f $_.Name, $commentBlock))
# Dot source the scriptblock in a different scope so we can
# get the help content but still not pollute the session.
& {
. $scriptBlock
Get-Help $_.Name
}
}
Ideally, you'd have your functions in a module (or their own script file), which you could load. Your 'execution' script would then be it's own thing that you only run when you do want to execute the function, or you run the functions manually.
If you had your functions in a module, in one of the paths that PowerShell looks to for them, you'd be able to run this to see the functions:
Get-Command -Module Example -CommandType Function
Most of the time you wouldn't include the CommandType parameter, unless there was extra stuff in the module you didn't care about.
This module approach (or separation of function/execution) would be the only way to get your comment based help working as you'd expect it to work.
If you're happy to just see the names of your functions, you'd have to load the content of the script file, and check for lines starting with the function keyword. There's probably smarter ways to do this, but that's where my mind went to.
Just to be a bit more clear about what I'm getting at around separating the functions from the execution code, it'd look something like:
functions.ps1
# I want to load this to get the comment-based help
Function Invoke-Stuff {
<#
.SYNOPSIS
Stuff doer
.DESCRIPTION
It does lots of stuff
.EXAMPLE
Invoke-Stuff
#>
Write-Host "Stuff was done"
}
You can then freely load the function into your session, making the comment based help accessible.
execute.ps1
. .\path\functions.ps1
# But I don't want to execute any of this
$Items = Get-ChildItem
$Items | ForEach-Object {
Invoke-Stuff
}

Can I override a Powershell native cmdlet but call it from my override

In Javascript it is possible to do so, I think. In Powershell I'm not sure how to :
Let's say I want to override every call to write-host with my custom method but at some time I want to execute the native write-host inside my overide. Is it possible to store the native implentation under another name so as to call it later from new implementation ?
Update : it seems to me that the answer https://serverfault.com/a/642299/236470 does not fully answer the second part of my question. How do I store and call the native implementation ?
Calls to functions will override cmdlets. You can read more on this from about_Command_Precedence on TechNet ...
If you do not specify a path, Windows PowerShell uses the following
precedence order when it runs commands:
Alias
Function
Cmdlet
Native Windows commands
So simply making a function of the same name as a native cmdlet will get you what you want.
function Write-Host{
[cmdletbinding()]
param(
[Parameter(Mandatory,ValueFromPipeline)]
$string
)
Process {
# Executes once for each pipeline object
If ($string -match "bagels"){
Microsoft.PowerShell.Utility\Write-Host $string -ForegroundColor Green
}else{
Microsoft.PowerShell.Utility\Write-Host $string
}
}
}
So now write-host works with pipeline input that we can filter with. Calling the "real" cmdlet is as easy as specifying the module in the call. You can see I have done that twice in the above code sample. Some sample usage and output would be the following:
Be careful that you don't forget you have done this if you save it in a profile or something of that nature. Use Get-Command Write-Host whenever in doubt. In my case you can remove the override by calling Remove-Item function:write-host
You can also look into what are called proxy functions but I think that is overkill for what you intend to do.
Yes you can. I have an answer for that here on ServerFault, but since it's a different site I'll copy it since I can't close as duplicate to another site.
Yes, you can override Get-ChildItem or any other cmdlet in Powershell.
Name Your Function The Same
If you make a function with the same name in the same scope, yours will be used.
Example:
Function Get-ChildItem {
[CmdletBinding()]
param(
# Simulate the parameters here
)
# ... do stuff
}
Using Aliases
Create your own function, and then create an alias to that function, with the same name as the cmdlet you want to override.
Example:
Function My-GetChildItem {
[CmdletBinding()]
param(
# Simulate the parameters here
)
# ... do stuff
}
New-Alias -Name 'Get-ChildItem' -Value 'My-GetChildItem' -Scope Global
This way is nice because it's easier to test your function without
stomping on the built-in function, and you can control when the cmdlet
is overridden or not within your code.
To remove the alias:
Remove-Item 'Alias:\Get-ChildItem' -Force

Calling all functions with certain signature

I have a module (psm1 file), where I have a set of function. I need to call all functions in that module, which accept one parameter (an array of PSToken). Obviously, I can directly call all functions, but I need that changes in the module, didn't require changes in the calling script. How can I do this?
You can use the Get-Command commandlet to iterate over the functions in a given module, and then call each function using dot-sourcing:
Import-Module MyPowershellModule
$arrPsToken = #($token1, token2, token3)
Get-Command -Module MyPowershellModule |
Select-Object -ExpandProperty Name |
ForEach-Object {
. "$_" $arrPsToken
}
Keep in mind that this code assumes that all functions have the same signature, which is risky.

Use of property names in PowerShell pipeline $_ variable

As a C# developer, I'm still learning the basics of PowerShell and often getting confused.
Why does the $_. give me the intellisense list of vaild property names in the first example, but not the second?
Get-Service | Where {$_.name -Match "host" }
Get-Service | Write-Host $_.name
What is the basic difference in these two examples?
When I run the second one, it gives this error on each iteration of Get-Service:
Write-Host : The input object cannot be bound to any parameters for the command either because the command does not take pipeline input or the input and its properties do not match any of the parameters
that take pipeline input.
At line:3 char:15
+ Get-Service | Write-Host $_.name
+ ~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidArgument: (wuauserv:PSObject) [Write-Host], ParameterBindingException
+ FullyQualifiedErrorId : InputObjectNotBound,Microsoft.PowerShell.Commands.WriteHostCommand
My coworker and I were first using a foreach loop to iterate a Get-commandlet, and we were stuck getting the property names to appear. We tried to simplify till we go to the core basics above.
Just figured out sometimes it's a typo in the commandlet, below first one fails because the commandlet should be Get-Service instead of Get-Services.
foreach ($item in Get-Services)
{
Write-Host $item.xxx #why no intellisense here?
}
foreach ($item in Get-Service)
{
Write-Host $item.Name
}
First part: you can't use $_ like that, it represents current pipeline object only within script blocks. These script blocks are usually used with any *-Object cmdlet (but there are other use cases too). Not all parameters/ cmdlet support it. Write-Host is one of those that don't.
Second: It looks like you are using own function (GetServices). PowerShell v3 intellisense is depending on command metadata (OutputType). If any cmdlet/ function produces object but is silent about OutputType, intellisense won't work. It's pretty simple to get it, and you can lie and still get proper intellisense for any existing type:
function Get-ServiceEx {
[OutputType('System.ServiceProcess.ServiceController')]
param ()
'This is not really a service!'
}
(Get-ServiceEx).<list of properties of ServiceController object>
You can read more about it on my blog.
Intellisense will work if you put $_ inside a scriptblock.
The following will trigger intellisense:
Get-Service | Foreach-Object {$_.Name} # Intellisense works
Get-Service | Where-Object {$_.Name} # Intellisense works
Get-Service | Write-Host {$_.Name} # Intellisense works
Note that your command need not be a valid command: the third example will not work but intellisense will display auto-complete for $_ anyway because it is inside a scriptblock.
I suspect it is because $_ is only usable inside a scriptblock (e.g. switch, %, ?) but I have no hard-evidence for it.
$_ is the current object in the pipeline. It's the same as $item in a foreach ($item in $array).
Get-Service | Where {$_.name -Match "host" }
Get-Service | Write-Host $_.name
The difference between these two lines is a fundamental part of the PowerShell design. Pipelines are supposed to be easy. You should be able to ex. search for and delete files as simply as:
Get-ChildItem *.txt | Remove-Item
This is clean, simple, and everyone can use it. The cmdlets are built to identify the type of the incoming object, adapt to support the specific type, and process the object.
However, sometimes you need more advanced object manipulation in the pipeline, and that's where Where-Object and Foreach-Object comes in. Both cmdlets lets you write your own processing logic without having to create an function or cmdlet first. To be able to access the object in your code(processing logic), you need an identifier for it, and that is $_. $_ is also supported in some other special cmdlets, but it's not used in most cmdlets(including Write-Host).
Also, Intellisense in foreach ($item in Get-Service) works. You had a typo.