#Requires -Module works also inside function (not doc'd)

[it-praktyk]

The #Requires -Module statement works also when the statement is inside function - like ilustrated on the screenshot below.

Help about_Requires states:

You can use #Requires statements in any script. You cannot use them in functions, cmdlets, or snap-ins.

[zjalexander]

We should be touching this doc as part of PS6 release, let's clean this up while we are there.

[sdwheeler]

@joeyaiello @zjalexander The current docs say: 'You cannot use them in functions, cmdlets, or snap-ins.'

Who can verify the actual rules for where #requires can be used? And did this change in some version (e.g. cannot be done in v3, can in v4+)?

[sdwheeler]

@joeyaiello @zjalexander Can we get someone to clarify how this works so we can update the docs?

[rjmholt]

I've just been looking at and tracing the execution of this behaviour in the following PowerShell version:

Name                           Value
----                           -----
PSVersion                      6.0.1
PSEdition                      Core
GitCommitId                    v6.0.1-279-gf7c2b7def1cf7428dbd66c018b6fb23ef6a1c68d
OS                             Microsoft Windows 10.0.16299
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

#requires annotations are collected as the script is parsed for the first time, and parsing continues as normal irrespective of where the #requires occurs or whether it should succeed. All occurrences of #requires in a script are then bundled as a top-level property of the Ast object that represents that parsed script. Then the parser performs all semantic and type checking. This means the #requires annotations are effectively hoisted, no matter where they occur in a script.

When the script gets called, the command processor checks the requirements attached to the AST and decides whether or not to proceed. Note that it's only when a script is actually invoked that the requirements are checked (done here).

This behaviour strikes me as a bit strange, only because we should probably be forcing the #requires annotations to be at the top of the script and reject parsing otherwise. So I'm going to open an RFC that addresses this and adds a couple of other suggestions.

Related: #694, PowerShell #5022, PowerShell #2846, PowerShell #3751, PowerShell #3803, PowerShell #4549.

Thanks to @sdwheeler for collecting all these issues.

Also /cc @lzybkr and @BrucePay, who may be able to offer more insight or corrections into how #requires works and is intended to work.

[rjmholt]

I've opened an RFC on updating the behaviour of #requires. Please feel free to comment in the PR.