PowerShell / PowerShell/PSResourceGet

Cmdlets do not produce (or work on?) scripts with usable help

Open
#1,461 1 comment 0 reactions 1 assignee View on GitHub

@anamnavi is already working on this.

Since Oct 30, 2023.

Area-InfoFile Issue-Bug
Dominant language
C#
Stars
576
Forks
114
Avg merge
1d 2h
Merged PRs (30d)
7

Description

Prerequisites
  • Write a descriptive title.
  • Make sure you are able to repro it on the latest released version
  • Search the existing issues.
Steps to reproduce

In order for a script to have help, the help has to be FIRST in the file.

This works:

@'
<#PSScriptInfo
    .VERSION 1.0.1
    .GUID 802367c6-654a-450b-94db-87e1d52e020a
    .AUTHOR Joel Bennett
#>

<#
    .DESCRIPTION
        A cross-platform script to download, check the file hash, and make sure the binary is on your PATH.
    .SYNOPSIS
        Install a binary from a github release.
    .EXAMPLE
        Install-GithubRelease FluxCD Flux2

        Install `Flux` from the https://github.com/FluxCD/Flux2 repository
#>
'@ > File.ps1

Get-Help ./File.ps1

But if I use the commands, They leave off the empty line between the comments and Get-Help breaks:

Update-PSScriptFileInfo -path File.ps1 -CompanyName "HuddledMasses.org"
Get-Help ./File.ps1

image

On top of that, all of these commands are unnecessaryily picky about the order. In order to publish it with Publish-PSResource or validate it with Test-PSScriptFileInfo or Get-PSScriptFileInfo or update it with Update-PSScriptFileInfo ... I can't put the help at the top, I have to put the <#PSScriptInfo first.

IMPORTANT: That was NOT a problem with the old Test-ScriptFileInfo and Update-ScriptFileInfo and Publish-Script commands

Expected behavior
@'
<#
    .DESCRIPTION
        A cross-platform script to download, check the file hash, and make sure the binary is on your PATH.
    .SYNOPSIS
        Install a binary from a github release.
    .EXAMPLE
        Install-GithubRelease FluxCD Flux2

        Install `Flux` from the https://github.com/FluxCD/Flux2 repository
#>

<#PSScriptInfo
    .VERSION 1.0.1

    .GUID 802367c6-654a-450b-94db-87e1d52e020a

    .AUTHOR Joel Bennett
#>
'@ > File.ps1

# This would work:
# Test-ScriptFileInfo -Path File.ps1
Get-PSScriptFileInfo -Path File.ps1

Version              Name                      Author               Description
-------              ----                      ------               -----------
1.0.1                Install-GithubRelease     Joel Bennett         A cross-platform script to download, check the file hash, and make sure the binary is on your PATH.
Actual behavior
Get-PSScriptFileInfo -Path File.ps1

Get-PSScriptFileInfo: Error: 'File.ps1' script file is invalid. The script file must include Version, Guid, Description and Author properties.
Could not parse 'File.ps1' as a PowerShell script due to it missing '<#PSScriptInfo #> block
Error details

No response

Environment data
Get-Module Microsoft.PowerShell.PSResourceGet; $PSVersionTable | Format-Table

ModuleType Version    PreRelease Name                                ExportedCommands
---------- -------    ---------- ----                                ----------------
Binary     1.0.0                 Microsoft.PowerShell.PSResourceGet  {Find-PSResource, Get-InstalledPSResource, Get-PSResourceRepository, Get-PSScriptFileInfo…}


Name                           Value
----                           -----
PSVersion                      7.4.0-preview.6
PSEdition                      Core
GitCommitId                    7.4.0-preview.6
OS                             Microsoft Windows 10.0.22621
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0
Visuals

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.