Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jdhitsolutions/psfunctioninfo
A PowerShell module for managing metadata in stand-alone functions.
https://github.com/jdhitsolutions/psfunctioninfo
powershell powershell-functions
Last synced: 3 months ago
JSON representation
A PowerShell module for managing metadata in stand-alone functions.
- Host: GitHub
- URL: https://github.com/jdhitsolutions/psfunctioninfo
- Owner: jdhitsolutions
- License: other
- Created: 2021-04-21T15:37:50.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-22T13:45:50.000Z (11 months ago)
- Last Synced: 2024-08-14T07:06:38.021Z (5 months ago)
- Topics: powershell, powershell-functions
- Language: PowerShell
- Homepage:
- Size: 1 MB
- Stars: 16
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- License: License.txt
Awesome Lists containing this project
README
# PSFunctionInfo
[](https://www.powershellgallery.com/packages/PSFunctionInfo/) 
## Synopsis
This module contains a set of PowerShell commands to add and manage metadata in stand-alone PowerShell functions.
## Installation
You can install this module from the PowerShell Gallery.
```powershell
Install-Module PSFunctionInfo -Force [-scope CurrentUser]
```
Or using `PSResourceGet`:
```powershell
Install-PSResource PSFunctionInfo [-scope CurrentUser]
```
The module should work on both Windows PowerShell and PowerShell 7, even cross-platform, except for a few PowerShell-ISE-related commands.
## Description
The purpose of this code is to provide a way to get versioning and other metadata information for functions that do not belong to a module. This is information you want to get after the function has been loaded into your PowerShell session. I have numerous stand-alone functions. These functions don't belong to a module, so there is no version or source information. However, I'd like to have that type of information for non-module functions.
The code in this module isn't concerned with loading, running, or finding functions. By default, [Get-PSFunctionInfo](docs/Get-PSFunctionInfo.md) queries whatever is in the `Function:` PSDrive. If the PowerShell function belongs to a module, then you'll get the module version and source. Otherwise, the command will use the function metadata.
The default behavior is to show all functions that __don't__ belong to a module.
You can also get currently loaded functions by tag. Use `Get-PSFunctionInfoTag` to get a list of tags currently in use.
The PSFunctionInfo object includes a PropertySet called `AuthorInfo`.
```dos
PS C:\> Get-PSFunctionInfo -Tag modules | Select-Object -property AuthorInfo
Name : Test-HelpLink
Version : 0.9.0
Source : C:\scripts\update-helplinks.ps1
CompanyName : JDH IT Solutions, Inc.
Copyright : (c) JDH IT Solutions, Inc.
Description : Test if help file is missing the online link
LastUpdate : 4/23/2021 9:21:00 AM
```
Or you can use the `TagInfo` property set. This gives you the same result as using the `tag` named view with `Format-Table`.,
```powershell
Get-PSFunctionInfo | Select-Object taginfo
```
Finally, you can also search .ps1 files for PSFunctionInfo metadata.
## Creating PSFunctionInfo
Use the [New-PSFunctionInfo](docs/New-PSFunctionInfo.md) command to insert the metadata tag into your script file.
```powershell
New-PSFunctionInfo -Path c:\scripts\Test-ConsoleColors.ps1 -Description "show console color combinations" -Name Test-ConsoleColor -Author "Jeff Hicks" -CompanyName "JDH IT Solutions" -Copyright "2023 JDH IT Solutions, Inc." -Tags "scripting","console"
```
The default behavior is to insert the metadata tag immediately after the opening brace (`{`) into the file. __This command will update the file__. Or you can use the `ToClipBoard` parameter which will copy the metadata to the clipboard. You can then manually insert it into your script file that defines the function. You should avoid changing the formatting of the comment block.
You should get something like this:
```text
<# PSFunctionInfo
Version 1.0.0
Author Jeff Hicks
CompanyName JDH IT Solutions
Copyright 2023 JDH IT Solutions, Inc.
Description show console color combinations
Guid 8e43a9d9-1df6-48c7-8595-7363087aba43
Tags scripting,console
LastUpdate 2/22/2023 10:43 AM
Source C:\scripts\Test-ConsoleColors.ps1
#>
```
This command will __not work__ with functions defined in a single line like:
```powershell
Function Get-Foo { Get-Date }
```
However, you could run `New-PSFunctionInfo` with the `ToClipboard` parameter and manually edit your function to insert the metadata.
```powershell
Function Get-Foo {
<# PSFunctionInfo
Version 1.0.0
Author Jeff Hicks
CompanyName JDH IT Solutions
Copyright 2023 JDH IT Solutions, Inc.
Description Get Foo Stuff
Guid 490595c6-6a0c-4572-baf4-f808c010de70
Tags scripting,console
LastUpdate 2/21/2023 10:41 AM
Source C:\scripts\FooStuff.ps1
#>
Get-Date
}
```
### Backup
Because creating a PSFunctionInfo metadata comment block modifies the file, you might feel safer with a file backup. `New-PSFunctionInfo` has a `-BackupParameter` which will create a backup copy of the source file before inserting the metadata comment block. The file will be created in the same directory, appending an extension of .bak1. If there are previous backups, the number will increment, i.e. .bak2. You have to manually delete the backup files.
The `-Backup` parameter has no effect if you use `-Clipboard`.
## PSFunctionInfo Defaults
Because you might define function metadata often and want to maintain consistency, you can define a set of default values for `New-PSFunctionInfo`. Use the command, [Set-PSFunctionInfoDefaults](docs/Set-PSFunctionInfoDefaults):
```powershell
Set-PSFunctionInfoDefaults -Tags "stand-alone" -Copyright "(c) JDH IT Solutions, Inc." -author "Jeff Hicks" -company "JDH IT Solutions, Inc."
```
The defaults will be stored in a JSON file (`$HOME\psfunctioninfo-defaults.json`). When you import this module, the values from this file will be used to define entries in `$PSDefaultParameterValues`. Or, run [Update-PSFunctionInfoDefaults](docs/Update-PSFunctionInfoDefaults) to update parameter defaults.
You can use [Get-PSFunctionInfoDefaults](docs/Get-PSFunctionInfoDefaults.md) to see the current values.
```powershell
PS C:\> Get-PSFunctionInfoDefaults
Version : 0.9.0
CompanyName : JDH IT Solutions, Inc.
Author : Jeffery Hicks
Tags : {stand-alone}
Copyright : (c) JDH IT Solutions, Inc.
```
## Editor Integration
When you import the module into an editor, you will get additional features to make it easier to insert PSFunctionInfo metadata into your file. It is recommended that you explicitly import the module into the editor's integrated console session. You could add an `Import-Module PSFunctionInfo` command into the editor's PowerShell profile script.
### Visual Studio Code
If you have an open file, in the integrated PowerShell console, you can run `New-PSFunctionInfo` and press TAB to tab-complete the detected functions in the current file. The file path will automatically be detected. You can enter other values such as version, or simply press ENTER to insert the metadata, which you can then edit.
This example is taking advantage of saved defaults. See [`Set-PSFunctionInfoDefaults`](docs/Set-PSFunctionInfoDefaults.md)
### PowerShell ISE
When you import the module in the PowerShell ISE, it will add a menu shortcut.
With a loaded file, you could run `New-PSFunctionInfo` in the console specifying the function name. The Path will be auto-detected. Or use the menu shortcut which will give you a graphical "function picker"
Select a function and click OK. The metadata block will be inserted into the file. This will not work with a file that has unsaved changes. When you insert new function metadata, the file in the ISE will be closed, re-opened and focus should jump to the function.
### Editing Source Files
The module has a command called [Edit-PSFunctionInfo](docs/Edit-PSFunctionInfo.md) which will open a source file in your preferred editor. The command has an alias of `epfi`. The default editor selection is VS Code, but you can specify the PowerShell ISE or Notepad.
You can either specify a loaded function by name:
```powershell
Edit-PSFunctionInfo Get-QOTD
```
Or pipe to it.
```powershell
Get-PSFunctionInfo Get-QOTD | Edit-PSFunctionInfo -editor ise
```
Once opened, you will need to navigate to the appropriate function and metadata section.
It is assumed you will normally edit function metadata when editing the script file. But you can use [`Set-PSFunctionInfo](docs/Set-PSFunctionInfo.md) to make changes from the console.
```powershell
PS C:\> Set-PSFunctionInfo -Name Get-EventlogInfo -Path c:\work\LogTools.ps1 -Tags "profile,eventlog" -Version "1.2.1"
```
If you want to clear an existing value, set the parameter value to `$null`.
```powershell
PS C:\> Set-PSFunctionInfo -Name Get-EventlogInfo -Path c:\work\LogTools.ps1 -Source $null
```
## Background
This code is a prototype for a [suggestion](https://github.com/PowerShell/PowerShell/issues/11667) I made for PowerShell 7. Early versions of this code were published as [https://gist.github.com/jdhitsolutions/65070cd51b5cfb572bc6375f67bcbc3d](https://gist.github.com/jdhitsolutions/65070cd51b5cfb572bc6375f67bcbc3d "view the Github gist")
This module was first described at .
## Roadmap
+ Add function metadata by file, auto-detecting the function name.
+ Consider a bulk removal command to clean PSFunctionInfo metadata from files.