是否可以将 $ErrorActionPreference = 'Stop' 配置为 powershell 模块中所有功能的默认值? [英] Is it possible to configure $ErrorActionPreference = 'Stop' as the default for all the functions in a powershell module?

问题描述

我希望模块中的所有函数都默认为 $ErrorActionPreference = 'Stop'.不修改所有功能可以吗?

I want all of the functions in my module to default to $ErrorActionPreference = 'Stop'. Is it possible without modifying all the functions?

每个函数都有一个文件.

I have a file per function.

推荐答案

假设你的模块是一个 script 模块，即用 PowerShell 代码实现:

Assuming that your module is a script module, i.e., implemented in PowerShell code:

重要:

• 模块有自己的作用域堆栈，独立于非模块代码(和其他模块)的作用域.虽然这提供了与通常有用的调用者环境的隔离，但这也意味着 调用者 $ErrorActionPreference 值 从不 对以下情况生效脚本模块函数(除非您直接从全局作用域运行，这些模块也可以看到)-但它对编译的cmdlets这样做.此 GitHub 问题 中讨论了这种问题严重的行为.

• Modules have their own stack of scopes that is independent of the scopes of non-module code (and other modules'). While this provides isolation from the caller's environment that is generally useful, it also means that the caller's $ErrorActionPreference value never takes effect for script-module functions (unless you directly run from the global scope, which modules also see) - but it does so for compiled cmdlets. This highly problematic behavior is discussed in this GitHub issue.

即使您目前无法通过$ErrorActionPreference从调用者控制脚本模块的错误行为，通过设置(覆盖)$ErrorActionPreference 在你的模块中你正在永久关闭那扇门.

Even though you therefore currently cannot control a script module's error behavior from the caller by way of $ErrorActionPreference, by setting (overriding) $ErrorActionPreference in your module you're closing that door permanently.

但是，使用 -ErrorAction 通用参数代替 $ErrorActionPreference preference 变量 仍然会覆盖你的模块全局 $ErrorActionPreference 值，因为在幕后，PowerShell 将 -ErrorAction 参数转换为 function-localem> $ErrorActionPreference 具有该值的变量.

However, using the -ErrorAction common parameter for a specific call instead of the $ErrorActionPreference preference variable will still override your module-global $ErrorActionPreference value, because, behind the scenes, PowerShell translates the -ErrorAction argument to a function-local $ErrorActionPreference variable with that value.

-ErrorAction 和 $ErrorActionPreference 机制受到不一致和模糊行为的困扰 - 这个 GitHub 文档问题 提供了 PowerShell 错误处理的全面概述.

The -ErrorAction and $ErrorActionPreference mechanisms are plagued by inconsistencies and obscure behaviors - this GitHub docs issue provides a comprehensive overview of PowerShell's error handling.

我希望模块中的所有函数都默认为 $ErrorActionPreference = 'Stop'.不修改所有功能可以吗?

I want all of the functions in my module to default to $ErrorActionPreference = 'Stop'. Is it possible without modifying all the functions?

是 - 只需将 $ErrorActionPreference = 'Stop' 放在您的 RootModule *.psm1 文件的顶级代码中.(模块清单文件 (*.psd1) 的 RootModule 条目指定模块的主模块 - 请参阅 文档).

Yes - simply place $ErrorActionPreference = 'Stop' in your RootModule *.psm1 file's top-level code. (The RootModule entry of a module's manifest file (*.psd1) specifies a module's main module - see the docs).

• 如果您没有引用 .psm1 文件的 RootModule 条目，只需在您的模块文件夹中创建一个 .psm1 文件(通常为封闭模块命名)内容为 $ErrorActionPreference = 'Stop'，并从 RootModule 条目中引用它 - 参见 此答案 了解背景信息.

• If you don't have a RootModule entry that references a .psm1 file, simply create a .psm1 file in your module folder (typically named for the enclosing module) with content $ErrorActionPreference = 'Stop', and reference it from the RootModule entry - see this answer for background information.

除非调用者在调用模块的函数(假设它们是高级函数)时使用通用的-ErrorAction参数覆盖，否则模块的顶级$ErrorActionPreference 值将对您模块的所有函数有效，除非，如果您的函数直接发出语句终止错误^[1]，在这种情况下，重要的是调用者的 $ErrorActionPreference 值.

Unless overridden by the caller by using the common -ErrorAction parameter when calling your module's functions (assuming they are advanced functions), your module's top-level $ErrorActionPreference value will be in effect for all of your module's functions, except if your function directly emits a statement-terminating error^[1], in which case it is the caller's $ErrorActionPreference value that matters.

如果您的模块是二进制模块，即导出编译的 cmdlet(通常在 C# 中实现):

If your module is a binary module, i.e., exports compiled cmdlets (typically implemented in C#):

编译的 cmdlet 没有自己的作用域 - 它们在调用者的作用域中运行.因此，调用者 $ErrorActionPreference 很重要，它可以在每次调用的基础上使用公共参数 -ErrorAction 覆盖，但仅适用于非终止错误.

Compiled cmdlets don't have their own scope - they run in the caller's scope. It is therefore the caller's $ErrorActionPreference that matters, which can be overridden on a per-call basis with common parameter -ErrorAction, but only for non-terminating errors.

与脚本模块中的高级函数一样，直接发出的语句终止错误^[1]总是受调用者的约束$ErrorActionPreference 值，即使使用了 -ErrorAction.(请注意，二进制 cmdlet 不会发出 script 终止错误).

As with advanced functions in script modules, directly emitted statement-terminating errors^[1] are always subject to the caller's $ErrorActionPreference value, even if -ErrorAction is used. (Note that binary cmdlets do not emit script-terminating errors).

[1] 语句-终止错误发生在以下情况:

[1] Statement-terminating errors occur in the following scenarios:

• 直接，中止封闭 cmdlet 或高级函数/脚本的执行:

• Directly, to abort execution of the enclosing cmdlet or advanced function/script:

• 当二进制 cmdlet 遇到阻止其继续运行的严重错误时，它会使用 ThrowTerminationError() 方法(或只是抛出异常).

• When a binary cmdlet encounters a severe error that prevents it from continuing, it reports such an error with the ThrowTerminatingError() method (or just throws an exception).

高级 PowerShell 函数/脚本同样必须使用 $PSCmdlet.ThrowTerminationError()，然而，这在实践中很少见；通常使用的 Throw 语句会创建一个 脚本-终止错误，默认情况下它也会终止整个线程，即也终止调用者及其所有调用者.

An advanced PowerShell function/script would similarly have to use $PSCmdlet.ThrowTerminatingError(), which, however, is rare in practice; the typically used Throw statement creates a script-terminating error instead, which by default also terminates the entire thread, i.e., also terminates the caller and all its callers.

间接，在 PowerShell 代码中:

Indirectly, in PowerShell code:

• 当表达式导致运行时错误时，例如1/0或'a,b' -拆分 ',', 'NotAnInt'.

当.NET 方法调用抛出异常时，例如[int]::Parse('NotAnInt')

When a .NET method call throws an exception, such as [int]::Parse('NotAnInt')

当在高级函数/脚本中调用另一个 cmdlet 或高级函数/脚本时，它本身会直接发出语句终止错误.

When, inside an advanced function/script, another cmdlet or advanced function / script is called that itself directly emits a statement-terminating error.

请注意，高级函数/脚本不能中继语句终止错误本身:

Note that advanced functions/scripts cannot relay statement-terminating errors as such:

• 默认情况下($ErrorActionPreference 包含 'Continue'，可能只是在本地范围内)表达式的/其他命令的终止错误有效地变成了 非-从调用者的角度来看的终止错误.

• By default (with $ErrorActionPreference containing 'Continue', possibly just in the local scope) the expression's / other command's terminating error effectively becomes a non-terminating error from the caller's perspective.

在 $ErrorActionPreference 设置为 'Stop' 的情况下，最初的语句终止错误被提升为 脚本-终止错误.

With $ErrorActionPreference set to 'Stop', the originally statement-terminating error is promoted to a script-terminating error.

这篇关于是否可以将 $ErrorActionPreference = 'Stop' 配置为 powershell 模块中所有功能的默认值?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！