#Requires and Advanced Function

[Schwitzd]

Dear all,

can you please add a chapter for #Requires in the advanced function?
I don't really understood where place it.

Regards
Schwitzd

[BaileyLawson]

I'm not one of the "contributors" to this repo, but I might be able to help you out and I may submit a PR for this in the future...
As far as I have seen from various peoples scripts, the best practice for the #Requires statement is to put it on the first line, but it can technically go on any line (see https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_requires?view=powershell-6#rules-for-use). It also makes far more sense to go on the first line as the condition of #Requires must be met before the script can execute regardless of what line it is on.

[pauby]

#Requires isn't an Advanced Function directive. It's a script directive. If you've got each function in a script then the point is of course blurred but it's important to point this out.

[Schwitzd]

Normally I work with functions and I would like that specific function are executed as administrator.
Best is to place the #Requires inside the function or outside?

[pauby]

@Schwitzd The #Requires directive applies to everything in the file (ie. script) that it's in.

If you want to test a function is being run from an Administrator / elevated shell then you need to write the code around that inside the function. The #Requires directive won't help you here.

Something like this might help.

[Schwitzd]

@pauby thx for the link you share
If I'm not wrong if I put the #Requires inside the function and I run it as user I get an error

[pauby]

@Schwitzd If you have two functions in the same file with the #Requires you will get the error running the script, dot sourcing it or importing it (if it's a script module). The error appears for the whole file, not just your function.

script.ps1:

function function1 {
    #Requires -RunAsAdministrator
    Write-Host "function1"
}

function function2 { 
    Write-Host "function2"
}

Dot-sourcing:

> . .\script.ps1
. : The script 'script.ps1' cannot be run because it contains a "#requires" statement for running as Administrator. The current PowerShell session is not running as Administrator. Start PowerShell by using the Run as Administrator option, and then try running the script again.
At line:1 char:3
+ . .\script.ps1
+   ~~~~~~~~~~~~
+ CategoryInfo          : PermissionDenied: (script.ps1:String) [], ScriptRequiresException
+ FullyQualifiedErrorId : ScriptRequiresElevation

Running the script:

> .\script.ps1
.\script.ps1 : The script 'script.ps1' cannot be run because it contains a "#requires" statement for running as Administrator. The current PowerShell session is not running as Administrator. Start PowerShell by using the Run as Administrator option, and then try running the script again.
At line:1 char:1
+ .\script.ps1
+ ~~~~~~~~~~~~
+ CategoryInfo          : PermissionDenied: (script.ps1:String) [], ScriptRequiresException
+ FullyQualifiedErrorId : ScriptRequiresElevation

The #Requires affects both functions and it doesn't matter where in the file you put it.

[Schwitzd]

Ok! This is really good to know. Normally I have one function for each file

What you think about to write this on the style guide?

[darkoperator]

For modules I would say not recommended or in functions that get dot sourced in to a psm1 for loading. For a control script one would write do not see an issue. Still feel that code inside a function to handle the check for permission would be best since it allows the function to be moved from control script to module as one refactors.

[pauby]

@darkoperator It's handy for putting at the top of the Module Script file. That and the Manifest are the two important module files so they will likely be opened and the #Requires statement is clearly seen.

It really depends on where your functions came from. If they are all only for a module and the module really needs them to do most of what it does, then I would suggest that a #Requires directive at the top of the module script makes sense rather than each function checking for privileges. If it's one function inside the module that does a niche task then it makes more sense to put code in the function test for the privileges.

So it's really a matter of taste I would suggest. I don't think wither way is right or wrong. Just different ways of doing the same thing.

[pauby]

What you think about to write this on the style guide?

@Schwitzd I'm not sure what you mean by that?

[Schwitzd]

@pauby
I would like to summarise all this discussion in a chapter to add some where on the guideline.