Repository navigation
New Practices for PowerShell Core #68
Description
Activity
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
👍
OK, changed it to the best thing, which is
#!/usr/bin/env powershell... which would use the firstpowershellon the path.But FreeBSD is a pain (and thus, OS X) and
/usr/local/binis not necessarily on the path.Also, you can't specify parameters to PowerShell if you do that, like:
#!/usr/bin/powershell -noprofileworks, but#!/usr/bin/env powershell -noprofiledoesn'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.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.
Just ... stop using carriage returns. It's 2016. 🎱 says YAGNI
It's not like we're manually typing \r\n after every line. The editors do it. :P
Reacted by Keith HillOther than notepad.exe, it's always a setting.
Oh? Where's that setting in the ISE?
Reacted by Matt McNabbReacted by Joel BennettAre you sure Visual Studio allows you to configure line endings? You can configure it to warn you of inconsistent line endings.
OMG. I just remembered the other reason I despise ISE.
@Jaykul You only have two reasons for that? 😛
Don't get him started! :P
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.
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...
9 remaining items
+1 on Join-Path and Split-Path. I think using
/on all platforms should work fine, but those might help for dealing with path quoting, etc.Reacted by Joel Bennett, Mikey Lombardi (He/Him) and Warren FrameMaybe we should just create some default Pester tests that users could run on their code to verify compliance with the new "stylesheet"?
Reacted by Matt McNabb@torgro I think PSScriptAnalyzer rules would be a better fit for this. Depending on your editor you can get live feedback on best practices while you're writing scripts.
@daviwil I'd be glad to open the discussion on this, although I've done little real debugging in VSCode. I tend to do this in the ISE and am ready to accept that the issues are probably my own. I'll dig in and try to work up something a bit more coherent and post it as an issue if it feels necessary. Maybe that will help inform your direction on further integration with the live terminal?
Reacted by Tore Groneng@mattmcnabb I forgot about PSScriptAnalyzer. I think both would be sweet. Reason for that is many people use a regular texteditor like notepad++/notepad/etc. At least that is my impression from forums. Very, very few people use PSSA and/or Pester.
I do most of my work in VSCode (thank you @daviwil if I have not said that before) and use Pester quite a bit. In any project that target cross-platform compatibility, it makes sense to have tests that verify these best practices.
Reacted by Matt McNabb@mattmcnabb yeah, if you can give me an overview of your typical debugging workflow in the ISE that'd help me figure out how to replicate it in VS Code with the integrated terminal. Probably how you use the ISE isn't far off from what others do, so it'd be good to have the general debugging workflow patterns written down somewhere.
And thanks Tore! :)
Reacted by Matt McNabbWhat would be the best location for storing user configurations (like API clientid and secret) for PowerShell modules? For Windows I used c:\users\stefstr etc.a and user environment variables. For usage on Linux that's not going to work. Any suggestions?
Perhaps just in:
Split-Path $ProfileYeah, normally per-user config stuff would be
~/.config/powershell... but it's going to be confusing if something in there gets added toPSModulePathtoo ...Ok, found another one ... we're going to need a list of cmdlets which are implemented drastically differently. Invoke-WebRequest, for instance, has lost it's error handling
And another:
[System.Environment]::CurrentDirectorydoesn't exist, so if you need to call path-sensitive .Net APIs, you need to use[System.IO.Directory]::SetCurrentDirectory( $pwd )instead to set the .net environment.Reacted by Matt McNabb and Keith HillI just wanted to link (and point out) the RFC on UTF8:
https://github.com/PowerShell/PowerShell-RFC/blob/master/2-Draft-Accepted/RFC0020-DefaultFileEncoding.md- locked and limited conversation to collaborators
on Jul 22, 2023
Best Practices for Scripts and Modules:
#!/usr/bin/env pwsh(or the more fragile:#!/usr/bin/pwsh -noprofile)Mac and Windows both accept
\nbut 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 utf8Join-PathandSplit-Path-PSEditionvalue allowed for#requiresor module manifests, when you need to restrict to Core, not for Desktop, since it only works in PowerShell 5.1+[System.Environment]::CurrentDirectorydoesn'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