Save-Script should allow .PS1 extension

[SteveL-MSFT]

From @jpsnover on September 2, 2016 18:12

PS> save-script -name get-uptime.ps1 -path . 
PackageManagement\Save-Package : No match was found for the specified search criteria and script name 'get-uptime.ps1'.
At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm1:2486 char:21
+             $null = PackageManagement\Save-Package @PSBoundParameters
+                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Microsoft.Power...ets.SavePackage:SavePackage) [Save-Package], Exception
    + FullyQualifiedErrorId : NoMatchFoundForCriteria,Microsoft.PowerShell.PackageManagement.Cmdlets.SavePackage


PS> save-script -name get-uptime -path . 

PS> $PSVERSIONTABLE
Name                           Value                                                                                                             
----                           -----                                                                                                             
PSVersion                      5.0.10586.494                                                                                                     
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}                                                                                           
BuildVersion                   10.0.10586.494                                                                                                    
CLRVersion                     4.0.30319.42000                                                                                                   
WSManStackVersion              3.0                                                                                                               
PSRemotingProtocolVersion      2.3                                                                                                               
SerializationVersion           1.1.0.1                                                                                                           

Copied from original issue: PowerShell/PowerShell#2170

[SteveL-MSFT]

From @GeeLaw on September 2, 2016 19:13

The Name parameter is the name of the package, not the file in the package.

See get-uptime package on PowerShell Gallery -- its name is get-uptime, not get-uptime.ps1. Meanwhile, this package on PowerShell Gallery is named Azure.Storage. Therefore it is valid to have a package name with a dot ..

The first thing to consider is that, what happens if I upload two packages called Use-Ps1 and Use-Ps1.ps1? I am not sure whether I cannot do this and I would not like to do that just to test a rare case out (practically no one does this, making a package name end in .ps1 or .psm1, I think) and pollute the repository. Please do let me know if one cannot have Use-Ps1.ps1 as the package name.

Speaking from the perspective of "packages", I think one shouldn't use Use-Ps1.ps1 to refer to a package called Use-Ps1. After all, the Use-Ps1 package can include several script files and it sounds strange to save Use-Ps1.ps1, but getting more than one file.

Suppose the worst possible implementation is used in the next version of PowerShell: When you Save-Script -Name '<Abc>.ps1', the cmdlet first searches for a package exactly named <Abc>.ps1 (if it does not do this, some packages can never be downloaded), if it fails, it falls back to <Abc>. Then you are risking leading a new fashion of breaking dependencies -- when people find Saving-Script an <Abc>.ps1 sounds good since it calls the fact of saving a script out, people start Saving-Script get-uptime.ps1 for this fashionable reason, and all of a sudden, someone uploads get-uptime.ps1 package and everyone gets screwed up.

Moral: be accurate.

Though this will not be a breaking change, as nobody ever named their package <Abc>.ps1 (or is there?!), and we can add Accurate switch to this command, allowing one to download a script package with its name appended with .ps1 is stilled not recommended.

[SteveL-MSFT]

From @bjtucker on September 5, 2016 5:24

As a naive user, I would expect save-script to accept a filename with extension for the name and do the right thing.

If the downside is things getting confused when someone (wrongly!) publishes a package with a .ps1 at the end, maybe the right thing is to ignore it unless the user specifies they really want that with the switch. (And perhaps prevent doing that accidentally in as many package managers as reasonable).

I'd make them use a more pejorative sounding switch name than "Accurate" if they really want to load a package with .ps1 tacked onto the end of the name, but I'm cranky.

[SteveL-MSFT]

From @GeeLaw on September 5, 2016 5:27

Hmmm... Got a solution that both keeps backward compatibility and teaches the users.

Rename the parameter Name to PackageName, and add an alias (of course it's Name) for PackageName. New users will see PackageName in help or when tabbing thru the param list, and will surely understand what the parameter should be.

[SteveL-MSFT]

From @jpsnover on September 5, 2016 15:43

As a general rule - PowerShell attempts to more like an AK47 than an M16 - loose and reliable vs tight and finicky. My Issue was making the case that we don't want to be too precise here and that we know what the user is doing one way or the other so let them be sloppy and we'll figure it out. If they give us NAME, we look for the file NAME.ps1, why not exact the NAME if they specify Name.ps1?

So the question is, for scripts, what is the relationship between the "name" and the "filename"?

On Windows, you could assert that schema is that the FILENAME is of the form NAME.ps1.
But on Linux, a script can have a FILENAME in the form NAME. (We don't need .ps1 on Linux because you can put #!/path/powershell as the first line of the script instead).

So the first question to answer is whether we would allow BOTH FOO and FOO.PS1 to be published to the gallery?

In order to answer that Q, I would ask another question, would we allow FOO, FOo, Foo, foo to be published as different scripts? Unix is case sensitive, so these could be completely different scripts on Linux.

My initial reaction is to say NO - that for the gallery, we should use the Case-Preserving/Case-Insensitive rule. I've never heard a compelling argument for why the increase in usable namespace warranted the corresponding increase in errorspace. Of course I'm biased in this regard because I make lots of mistakes and I want a system that is forgiving.

When we pull on this thread long enough, I think it leads us to the question of community interaction - do we expect both the Unix and Windows scripts to be shared in the same repository. If the repository supports case sensitivity for the Unix community, it would support different scripts being named FOO and foo and you could write those scripts so that FOO required foo to run. Of course, this would break completely on a Windows system.

Thoughts:

1. The gallery exists and is used by the Windows community.
2. I think it is beneficial for both Unix and Windows community to share a common repository.
3. Adopting a case-preserving/case-insensitive rule for the repository is good tradeoff to accomplish that.
4. Ergo = adopting a sloppy model where we accept NAME.PS1 or NAME is desirable. If you give us either, it will be easy for us to find the NAME and the FILENAME so we should just be nice and do the work for the user.

We are left with the remaining hard problem:

• Since Unix allows scripts with just a NAME and not a .ps1 extension - do we allow those scripts to be published in the gallery or do we require them to have a .ps1 extension?

I'm inclined to trying and make that work but then encouraging people to adopt the best practice of always using a .PS1 extension AND putting #! in the first line.

I would love thoughts on that topic.

[SteveL-MSFT]

From @MaximoTrinidad on September 5, 2016 16:10

Well said Jeffrey Snover!

This could one strong topic to discuss in the next MVP Summit. Scripts collaboration between Windows and Linus will be a challenge . I wouldn't be good that a FOO, foO, or fOo.Ps1 would overwrite a foo.PS1 script in the gallery. So, again, the adoption of best practices for Linux will be critical.

This a good discussion!

[SteveL-MSFT]

From @GeeLaw on September 5, 2016 16:52

I agree that we should NEVER use Use-Ps1.ps1 as the same package name. But again, we should not confuse users with the name of a file in a package and the package itself.

There are many subtle things if you make Save-Script look for Abc given package name Abc.ps1.

1. Should we make Save-Module look for Abc given the package name Abc.psm1?
2. Should we make Save-Script look for Abc given the package name Abc.ps1.ps1, since a recursive elimination should be applied?

Now PSGallery keeps package names Case-Preserving/Case-Insensitive, that's good.

Another analogy is that, everyone who uses PowerShell should know that, we should Invoke-Item .\a.txt, not Invoke-Item .\a with extension hidden. And the user should be clear that he is saving a script package, not a script file, though the package could contain just one file.

Yet another analogy is that, say you have a git repo that has abc.ps1 in it, nobody will git clone remote://abc.ps1, because they know they are cloning a repo, not a file.

And you can't deal with the case, when the package name is Get-TaskmgrMeasures and there are two files, Get-UpTime.ps1 and Get-MemoryUsage.ps1. The changed behaviour becomes unintuitive again.

My point is that, this change may seem helpful and forgiving for newbies, but causes subtle trouble when looked into further. Therefore, what should be done, I think, is to guide and educate the user more effectively, by renaming the name of Name to PackageName.

On the cross-platform scripting, I think the idea of shebanging the script is great.

[SteveL-MSFT]

From @jpsnover on September 5, 2016 17:56

@GeeLaw I might have confused the discussion.

What I'm saying is that for FOO.PS1 - the NAME is always FOO and the FILENAME is always FOO.PS1. Full Stop.

From there, I'm saying that a user should be able to specify either the name or the filename for publishing, saving, updating etc and that we should be able to figure out the rest. We can do this because there is a 1 to 1 correspondence between a script package and a script file and because the cmdlet name itself is telling us that it is working with a SCRIPT and therefore can allow this shortcut.

This is not case with modules or git repos so I don't think we have the problem that you are worried about. Double check my thinking on that and if I got it wrong - give me an step-by-step where it breaks down because I'm not seeing it right now.

Thanks for the engagement @GeeLaw !

[SteveL-MSFT]

From @GeeLaw on September 6, 2016 3:34

@jpsnover You forgot dependencies. See this package on PowerShell Gallery. When you Save-Script -Name Update-Windows -Path ., you get PSWindowsUpdate folder (the module the script depends on) as well as Update-Windows.ps1 -- it's not saving a file, therefore this might cause confusion.

There is .EXTERNALSCRIPTDEPENDENCIES in script info created by New-ScriptFileInfo. Though a script package can contain only one script file, it can implicitly contain more files by adding dependencies.

I have to apologise for my example since you cannot Save-Script -Name Get-TaskmgrMeasures without getting a Get-TaskmgrMeasures.ps1. And at the same time, Unix users shouldn't be allowed to publish a script without extension name as we see all script packages in PowerShell Gallery contains (by itself) exactly one script file (named <PackageName>.ps1) and one manifest file (named <PackageName.nuspec> -- new practices shouldn't break this. But still, it's great practice to add shebang line in scripts published for cross-platform usage.

One more thing, for a new user (who might run into this problem without knowing how to fix this immediately), he could visit the repository (e.g. PowerShell gallery) and copy the line of saving/installing the package from the website. Therefore most users shouldn't have problem saving/installing a package with correct name.

[SteveL-MSFT]

From @iSazonov on October 6, 2016 13:5

We are left with the remaining hard problem:
•Since Unix allows scripts with just a NAME and not a .ps1 extension - do we allow those scripts to be published in the gallery or do we require them to have a .ps1 extension?

I'm inclined to trying and make that work but then encouraging people to adopt the best practice of always using a .PS1 extension AND putting #! in the first line.

If we require #! for the Windows world it is logical to require .PS1 for Unix world. Reciprocal convergence.

[SteveL-MSFT]

From @KirkMunro on October 6, 2016 13:49

I agree with this sentiment:

If we require #! for the Windows world it is logical to require .PS1 for Unix world. Reciprocal convergence.

Not only that, what if there is support for a .ps2 extension in future builds of PowerShell? To maintain consistency with all of PowerShell I think requiring both the shebang and the file extension is the way to go, and PSScriptAnalyzer can help make this easier for folks to learn/accept.

[SteveL-MSFT]

From @JKeithB on October 6, 2016 16:35

This is a great discussion focused on what the gallery & PowerShellGet cmdlets support.
The only hard stake in the ground that I'll put is that PowerShellGallery is the place we are establishing where users should look for stable scripts regardless of platform. That's our mission.
It seems we have consensus around avoiding user confusion that could arise around case sensitivity. I'd welcome compelling arguments for being case-insensitive.

For the file names, though, doesn't this impact what a file name can be generally in our platform across all environments? We make lots of assumptions about files based on file extension that go beyond naming a script for separate use.
For example, when Pester runs, are we going to look for and attempt to load any file in the tests folder, whether or not it's a .PS1? Script Analyzer makes a bunch of assumptions today about files based on file extension as well. It's just a script file, so shouldn't module contents follow the same rules as standalone scripts? If not, what would be a good rule set?

[SteveL-MSFT]

From @iSazonov on October 7, 2016 7:24

Extensions in Windows is allowed
Extensions in Linux is allowed

Extensions in Windows is a base.
Extensions in Linux is optional.

Windows use extensions to detect file type. High level API based on extensions to launch appropriated application.
Linux don't use extensions to detect file type. Linux always open a file and analyze a file mark to launch appropriated application.

Windows use external file type mark. Optimized for GUI.
Linux use internal file type mark. Don't optimized for GUI.

So our way is single and it is reciprocal convergence.

Interestingly, Windows can create multiple files of the same name but different types in one folder because there is a different extensions. Linux can not do like that.

@JKeithB

I'd welcome compelling arguments for being case-insensitive.

Case-insensitive is user-friendly. Linux use this too - for URL in browsers, ex. 😊

[SteveL-MSFT]

From @GeeLaw on October 7, 2016 7:41

Another perspective on being case-kept and case-insensitive: though most modern file system are case-sensitive, a lot of high-level API set, e.g. Win32, adopts case-kept and case-insensitive. AFAIK, the default setting on Mac doesn't allow two files whose names differ only by case.

Summary till now:

1. A script package named <abc> will contain (by itself) only one script named <abc>.ps1, till now;
2. It is possible to publish <abc>.ps1.ps1 to the repo, but no one has done that yet;
3. A script package can have external dependency, therefore Save-Script might give several script files, and this is a current practice;
4. The only cross-platform-compatible way is to use both extensions and shebang line, and being case-insensitive.

Because of point 3, I am against allowing the user to save Get-UpTime package by invoking Save-Script -Name Get-UpTime.ps1. This could cause confusion because you are not only saving one script file.

Point 4 arises from a broader topic on cross-platform PSGallery.