New Practices for PowerShell Core

[Jaykul]

There are going to be a few new things which we need to keep in mind to make our scripts work across multiple platforms. Windows, Nano, Linux, FreeBSD and OSX, ARM and IoT ...

Best Practices for Scripts and Modules:

1. Don't put aliases into scripts. Aliases are (currently) different on each platform. Double-check using a tool like ResolveAlias.
2. Add the shebang to scripts: #!/usr/bin/env pwsh (or the more fragile: #!/usr/bin/pwsh -noprofile)
3. Save scripts with Unix style line endings, or the shebang will not work.
   Mac and Windows both accept \n but the Unix shell interpreter will choke on the carriage return in the shebang. If you don't add the shebang, this doesn't matter. Note that you can always fix it:
   Set-Content $scriptPath ((Get-Content $scriptPath -raw) -replace "\r") -Encoding utf8
4. Always encode in utf-8.
5. Be careful with paths. Use forward slashes. Use Join-Path and Split-Path
6. ONLY use the new -PSEdition value allowed for #requires or module manifests, when you need to restrict to Core, not for Desktop, since it only works in PowerShell 5.1+
7. ALWAYS use three digits for versions (i.e. 5.0.0, not 5.0) because they may be parsed as SemanticVersion which currently doesn't work unless you provide the patch version explicitly.
8. [System.Environment]::CurrentDirectory doesn't in .Net Core. But if you need to call path-sensitive .Net APIs, you need to use [System.IO.Directory]::SetCurrentDirectory( (Get-Location -PSProvider FileSystem).ProviderPath ) to update the environment. Note that PowerShell sets the working directory fine when launching apps...

Finally: Test the code on Linux and Nano, if possible. There are differences.

ProTips

Use this in your profile: $PSDefaultParameterValues["Out-File:Encoding"] = "UTF8" to help with 1.

Don't forget you can install PowerShell 6 alphas side-by-side on Windows (they install to Program Files, and don't use the same profile or module paths). You don't have to set up docker or a VM to get started. It's just that in that scenario, you have access to things you won't have access to on Unix (like Set-ExecutionPolicy), so you should test elsewhere before publishing.

Cmdlet Differences

• Invoke-WebRequest uses HttpClient instead of WebClient, has totally different exceptions

[rkeithhill]

Always encode in utf-8

BOM or no BOM? That's the question. :-) IIRC the .NET UTF8 encoder has BOM enabled by default and PS uses it that way.

Add the shebang to scripts: #!/usr/bin/powershell (or for mac: #!/usr/local/bin/powershell ... ??)

Surely Bash scripts must already have a way to handle the platform difference. Maybe you specify both and multiple #! are searched until the shell is found?

Instead of specifying \n, I would do something like:

$NL = [System.Environment]::NewLine

It would be nice if this were added as an automatic variable.

ALWAYS use three digits for versions

👍

[Jaykul]

OK, changed it to the best thing, which is #!/usr/bin/env powershell ... which would use the first powershell on the path.

But FreeBSD is a pain (and thus, OS X) and /usr/local/bin is not necessarily on the path.

Also, you can't specify parameters to PowerShell if you do that, like: #!/usr/bin/powershell -noprofile works, but #!/usr/bin/env powershell -noprofile doesn't, because the interpreters will try to look up "powershell -noprofile" so a ProTip is going to be to figure out a way to tell (in your profile) if PowerShell is being used as an interpreter vs. as a shell.

I will reword the bit about \n -- the point is that you must save your actual PowerShell script with JUST newlines, or shebangs do not work.

[dlwyatt]

That's a pain in the ass. Git will convert line endings for you, but not sure what happens if we're publishing to the Gallery from a Windows machine.

[Jaykul]

Just ... stop using carriage returns. It's 2016. 🎱 says YAGNI

[dlwyatt]

It's not like we're manually typing \r\n after every line. The editors do it. :P

[Jaykul]

Other than notepad.exe, it's always a setting.

[dlwyatt]

Oh? Where's that setting in the ISE?

[rkeithhill]

Are you sure Visual Studio allows you to configure line endings? You can configure it to warn you of inconsistent line endings.

[Jaykul]

OMG. I just remembered the other reason I despise ISE.

[rkeithhill]

@Jaykul You only have two reasons for that? 😛

[dlwyatt]

Don't get him started! :P

[rkeithhill]

I will reword the bit about \n -- the point is that you must save your actual PowerShell script with JUST newlines, or shebangs do not work.

I think it is worth differentiating this point between how you save your scripts and what you use in your scripts for NL.

[Jaykul]

I guess if you're using PowerShell on other OS's, you're going to outgrow ISE and start using VS Code anyway.

Also, if don't need the shebang functionality (i.e. running PowerShell scripts "as apps" or from bash), don't worry about it -- they work fine in PowerShell regardless.

@rkeithhill I had simply forgotten that particular reason. Anyway. Visual Studio just uses what's in the file already for encoding and for line endings, you just have to hit the File -> Advanced Save Options to set it, and it figures it out from the file from then on...