Skip to content

Commit fd17f5b

Browse files
SteveL-MSFTSteveL-MSFT
authored
Merge pull request #188 from KirkMunro/simplify-module-manifests
Flatten the module manifest structure
2 parents 7bf4136 + eb5add9 commit fd17f5b

File tree

1 file changed

+353
-0
lines changed

1 file changed

+353
-0
lines changed

‎X-Rejected/RFC0039-Simplify-Module-Manifests.md

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
---
2+
RFC: RFC0039
3+
Author: Kirk Munro
4+
Status: Rejected
5+
SupercededBy:
6+
Version: 1.0
7+
Area: Module Manifests
8+
Comments Due: July 15, 2019
9+
Plan to implement: Yes
10+
---
11+
12+
# Deprecate PSData and flatten the module manifest structure
13+
14+
When PowerShell module support first came out in PowerShell 2.0, module manifests had a specific list of keys that could be used to define the manifest. Additional keys were added in PowerShell 3.0, but that hurt the end user experience because at the time, if you loaded a module with a manifest containing keys that were not recognized/supported in your version of PowerShell, PowerShell would return an unhelpful error about the module keys being invalid instead of checking for the minimum required version of PowerShell and returning an error indicating that the module only supports that version or later.
15+
16+
Beyond PowerShell 3.0, keys started being added to a `PSData` subsection of the `PrivateData` area of modules. Up to this point, all of the keys that have been added there are used by the PowerShell Gallery. That approach has its own challenges, because now keys are defined in a hierarchy which adds complexity and should not be necessary. Here is an example manifest showing the PSData subsection in a module in the gallery:
17+
18+
```PowerShell
19+
@{
20+
ModuleToProcess = 'HistoryPx.psm1'
21+
22+
ModuleVersion = '1.0.6.15'
23+
24+
GUID = '1ceaf4bf-dc01-4790-a06d-c8224daa7027'
25+
26+
Author = 'Kirk Munro'
27+
28+
# <snip>
29+
30+
PrivateData = @{
31+
PSData = @{
32+
ExternalModuleDependencies = @(
33+
'Microsoft.PowerShell.Utility'
34+
)
35+
Tags = 'history','Clear-History','Get-History','Out-Default'
36+
LicenseUri = 'http://apache.org/licenses/LICENSE-2.0.txt'
37+
ProjectUri = 'https://github.com/KirkMunro/HistoryPx'
38+
IconUri = ''
39+
ReleaseNotes = 'This module will not automatically load by invoking a *-History command because the native *-History cmdlets are loaded first in PowerShell. To start using HistoryPx, you should explicitly import the module either at the command line or as part of your profile by invoking "Import-Module HistoryPx".'
40+
}
41+
}
42+
}
43+
```
44+
45+
Fast forward to today, and things have changed enough that we can reconsider how we set up a module manifest. `Import-Module` has been checking the required version of PowerShell before validating key names for several years now, at least since PowerShell 5.1, and earlier versions of Windows PowerShell are no longer on mainstream support.
46+
47+
With all of this in mind, this proposal is to accomplish two things:
48+
49+
1. To flatten the module manifest structure for the current version of PowerShell (whichever version this gets implemented in), reading values for keys at the root first, and then if they are not set at the root, looking in the `PSData` section under `PrivateData` for backwards compatibility support. Future keys added to the manifest as part of PowerShell should all be added to the root, leaving `PrivateData` for 3rd party or user information in a manifest, as originally intended.
50+
1. To make the current version of PowerShell a default value for `-PowerShellVersion`, and update `New-ModuleManifest` such that it generates an appropriate manifest for the version of PowerShell indicated in the `-PowerShellVersion` parameter, so that scripters can create manifests for modules on newer versions of PowerShell that are properly structured to support older versions of PowerShell as well.
51+
52+
## Motivation
53+
54+
As a scripter,
55+
I can generate manifests using `New-ModuleManifest` for any supported version of PowerShell,
56+
so that I can work with module manifests more easily in the current version without letting go of compatibilty support for downlevel versions.
57+
58+
## User Experience
59+
60+
Here's an example showing how `New-ModuleManifest` would work with the default value of `-PowerShellVersion` after this change:
61+
62+
```powershell
63+
New-ModuleManifest .\test.psd1 -PassThru | Get-Content
64+
```
65+
66+
```output
67+
#
68+
# Module manifest for module 'test'
69+
#
70+
# Generated by: kirka
71+
#
72+
# Generated on: 2019-06-09
73+
#
74+
75+
@{
76+
77+
# Script module or binary module file associated with this manifest.
78+
# RootModule = ''
79+
80+
# Version number of this module.
81+
ModuleVersion = '1.0'
82+
83+
# Supported PSEditions
84+
# CompatiblePSEditions = @()
85+
86+
# ID used to uniquely identify this module
87+
GUID = '3de89b66-9e70-4f7a-822b-87a8feb94694'
88+
89+
# Author of this module
90+
Author = 'kirka'
91+
92+
# Company or vendor of this module
93+
CompanyName = 'Unknown'
94+
95+
# Copyright statement for this module
96+
Copyright = '(c) 2019 kirka. All rights reserved.'
97+
98+
# Description of the functionality provided by this module
99+
# Description = ''
100+
101+
# Minimum version of the Windows PowerShell engine required by this module
102+
PowerShellVersion = '7.0'
103+
104+
# Name of the Windows PowerShell host required by this module
105+
# PowerShellHostName = ''
106+
107+
# Minimum version of the Windows PowerShell host required by this module
108+
# PowerShellHostVersion = ''
109+
110+
# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
111+
# DotNetFrameworkVersion = ''
112+
113+
# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
114+
# CLRVersion = ''
115+
116+
# Processor architecture (None, X86, Amd64) required by this module
117+
# ProcessorArchitecture = ''
118+
119+
# Modules that must be imported into the global environment prior to importing this module
120+
# RequiredModules = @()
121+
122+
# Assemblies that must be loaded prior to importing this module
123+
# RequiredAssemblies = @()
124+
125+
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
126+
# ScriptsToProcess = @()
127+
128+
# Type files (.ps1xml) to be loaded when importing this module
129+
# TypesToProcess = @()
130+
131+
# Format files (.ps1xml) to be loaded when importing this module
132+
# FormatsToProcess = @()
133+
134+
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
135+
# NestedModules = @()
136+
137+
# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
138+
FunctionsToExport = @()
139+
140+
# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
141+
CmdletsToExport = @()
142+
143+
# Variables to export from this module
144+
VariablesToExport = '*'
145+
146+
# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
147+
AliasesToExport = @()
148+
149+
# DSC resources to export from this module
150+
# DscResourcesToExport = @()
151+
152+
# List of all modules packaged with this module
153+
# ModuleList = @()
154+
155+
# List of all files packaged with this module
156+
# FileList = @()
157+
158+
# Private data to pass to the module specified in RootModule.
159+
PrivateData = @{}
160+
161+
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
162+
# DefaultCommandPrefix = ''
163+
164+
# Tags applied to this module. These help with module discovery in online galleries.
165+
# Tags = @()
166+
167+
# A URL to the license for this module.
168+
# LicenseUri = ''
169+
170+
# A URL to the main website for this project.
171+
# ProjectUri = ''
172+
173+
# A URL to an icon representing this module.
174+
# IconUri = ''
175+
176+
# ReleaseNotes of this module
177+
# ReleaseNotes = ''
178+
179+
# The names of required or nested modules that are not packaged with this module.
180+
# ExternalModuleDependencies = @()
181+
182+
}
183+
```
184+
185+
Here's an example showing how `New-ModuleManifest` would work with the a specific `-PowerShellVersion` after this change:
186+
187+
```powershell
188+
New-ModuleManifest .\test.psd1 -PowerShellVersion 2 -PassThru | Get-Content
189+
```
190+
191+
```output
192+
#
193+
# Module manifest for module 'test'
194+
#
195+
# Generated by: kirka
196+
#
197+
# Generated on: 2019-06-09
198+
#
199+
200+
@{
201+
202+
# Script module or binary module file associated with this manifest.
203+
# ModuleToProcess = ''
204+
205+
# Version number of this module.
206+
ModuleVersion = '1.0'
207+
208+
# ID used to uniquely identify this module
209+
GUID = '47179120-0bcb-4f14-8d80-f4560107f85c'
210+
211+
# Author of this module
212+
Author = 'kirka'
213+
214+
# Company or vendor of this module
215+
CompanyName = 'Unknown'
216+
217+
# Copyright statement for this module
218+
Copyright = '(c) 2019 kirka. All rights reserved.'
219+
220+
# Description of the functionality provided by this module
221+
# Description = ''
222+
223+
# Minimum version of the Windows PowerShell engine required by this module
224+
PowerShellVersion = '2.0'
225+
226+
# Name of the Windows PowerShell host required by this module
227+
# PowerShellHostName = ''
228+
229+
# Minimum version of the Windows PowerShell host required by this module
230+
# PowerShellHostVersion = ''
231+
232+
# Minimum version of the .NET Framework required by this module
233+
# DotNetFrameworkVersion = ''
234+
235+
# Minimum version of the common language runtime (CLR) required by this module
236+
# CLRVersion = ''
237+
238+
# Processor architecture (None, X86, Amd64) required by this module
239+
# ProcessorArchitecture = ''
240+
241+
# Modules that must be imported into the global environment prior to importing this module
242+
# RequiredModules = @()
243+
244+
# Assemblies that must be loaded prior to importing this module
245+
# RequiredAssemblies = @()
246+
247+
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
248+
# ScriptsToProcess = @()
249+
250+
# Type files (.ps1xml) to be loaded when importing this module
251+
# TypesToProcess = @()
252+
253+
# Format files (.ps1xml) to be loaded when importing this module
254+
# FormatsToProcess = @()
255+
256+
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
257+
# NestedModules = @()
258+
259+
# Functions to export from this module
260+
FunctionsToExport = @()
261+
262+
# Cmdlets to export from this module
263+
CmdletsToExport = @()
264+
265+
# Variables to export from this module
266+
VariablesToExport = @()
267+
268+
# Aliases to export from this module
269+
AliasesToExport = @()
270+
271+
# List of all modules packaged with this module.
272+
# ModuleList = @()
273+
274+
# List of all files packaged with this module
275+
# FileList = @()
276+
277+
# Private data to pass to the module specified in ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
278+
PrivateData = @{
279+
280+
PSData = @{
281+
282+
# Tags applied to this module. These help with module discovery in online galleries.
283+
# Tags = @()
284+
285+
# A URL to the license for this module.
286+
# LicenseUri = ''
287+
288+
# A URL to the main website for this project.
289+
# ProjectUri = ''
290+
291+
# A URL to an icon representing this module.
292+
# IconUri = ''
293+
294+
# ReleaseNotes of this module
295+
# ReleaseNotes = ''
296+
297+
# The names of required or nested modules that are not packaged with this module.
298+
# ExternalModuleDependencies = @()
299+
300+
} # End of PSData hashtable
301+
302+
} # End of PrivateData hashtable
303+
304+
# HelpInfo URI of this module
305+
# HelpInfoURI = ''
306+
307+
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
308+
# DefaultCommandPrefix = ''
309+
310+
}
311+
```
312+
313+
## Specification
314+
315+
The changes required for this RFC are relatively straightforward, and as follows:
316+
317+
1. `New-ModuleManifest` would generate a template like what is shown above, omitting any details about the `PSData` section for the latest version, but including them for manifests with a downlevel version as the value of `-PowerShellVersion`.
318+
1. Module import logic would read the manifest and pull the values for `Tags`, `LicenseUri`, `ProjectUri`, `IconUri` and `ReleaseNotes` from the top-level keys in current plus future versions of PowerShell. If top-level keys were not defined with these values, it would look for values in a `PSData` section for backward compatibility (in cases where module versions are upgraded from older modules, we don't want users to be forced to change their manifest structure).
319+
1. If values are defined in both locations, an error would occur informing the module author that they need to remove one of the two keys.
320+
1. Add `-ExternalModuleDependencies` parameter to `New-ModuleManifest` (this is the only PowerShell Gallery value that is missing as a parameter).
321+
1. Update `New-ModuleManifest`'s `-PowerShellVersion` handling, such that it uses a default version of the latest version of PowerShell, with support for structuring a manifest properly for downlevel versions.
322+
1. Update `New-ModuleManifest` documentation (examples are missing PowerShell Gallery keys).
323+
1. Update `Test-ModuleManifest` to validate the keys in the new locations.
324+
1. Update `Update-ModuleManifest` to set the keys in the existing location if it is in use, or in the new location otherwise.
325+
1. Update `Import-Module` such that it allows import when a top-level key that it does not recognize is discovered. This is important and necessary to allow future versions of PowerShell to add keys to the top level while still allowing modules to be created for downlevel versions that also support the functionality identified by the new keys when loaded in a newer version.
326+
327+
## Alternate Proposals and Considerations
328+
329+
### Co-locate the `*-ModuleManifest` cmdlets
330+
331+
`Update-ModuleManifest` is part of PowerShellGet and not in the Microsoft.PowerShell.Core module. Presumably this is to offer the functionality to downlevel versions of PowerShell, but that separates it from the other `*-ModuleManifest` cmdlets, which is an update challenge (these commands need to be updated together as a whole, not independently, because otherwise downlevel systems may have an Update-ModuleManifest command with parameters that aren't appropriate for that version of PowerShell). If `Update-ModuleManifest` is moved into Microsoft.PowerShell.Core, users lose downlevel updates, but downlevel updates for that command, aside from bug fixes, don't really make sense. I believe it would be better for `Update-ModuleManifest` to be moved out of PowerShellGet and into Microsoft.PowerShell.Core.
332+
333+
### Keep `PSData` section in `New-ModuleManifest` output, but commented out with explanation
334+
335+
@iSazonov proposed it may be clearer if the `PSData` section in `New-ModuleManifest` output, but commented out with a note indicating the keys have been moved to top level. I'm not convinced that would add clarity: it may confuse users as well. I think it would be better to identify the location change in the remarks section of the documentation for `New-ModuleManifest`, keeping `New-ModuleManifest` output clean, but I wanted to share the thought here for comment.
336+
337+
### Isolate version-specific metadata and extension metadata into separate psd1 files
338+
339+
If the `psd1` top-level key set is considered complete, when new keys are needed, where do they go? The current answer of placing new keys as subkeys under `PrivateData` in the `PSData` hashtable works, but it's just dealing with the problem by not dealing with the problem right now, and creating manifests that are more complicated than necessary. Instead, modules could have multiple `psd1` files, where files are created with a name in the format _moduleName_._extensionNameOrVersionNumber_.psd1. For example, we could have _moduleName_.PSGallery.psd1 as a manifest that stores PowerShell Gallery information. We could also have _moduleName_.7.psd1 as a manifest that stores new keys added to PowerShell 7.
340+
341+
On the plus side, this strategy allows for new metadata to be defined in manifests today without breaking downlevel versions of PowerShell. This enables scenarios where modules can be defined for a minimum downlevel version of PowerShell while having functionality that lights up when those modules are loaded on a newer version.
342+
343+
On the down side, it requires the management of additional files when working on manifests, which isn't necessarily simplifying manifest management.
344+
345+
### Add a `-BackwardCompatible` parameter to `New-ModuleManifest`
346+
347+
@iSazonov proposed we consider adding a `-BackwardCompatible` switch parameter to `New-ModuleManifest`. When that parameter is used, the manifest would be generated in a 3.0 compatible format with new values being stored in `PrivateData`. Otherwise, it would generate the manifest in the latest format with new values stored at the root.
348+
349+
My main question about this approach is, is it easier to follow than using the value of `-PowerShellVersion` to generate the right manifest? I don't feel that it is. Further, if one or more new keys are added to PowerShell 7, and then more added to 7.x or 8 or 9, etc. would generation of manifests that work with each of those versions be possible this way? Unless I'm mistaken, this would require `-PowerShellVersion` anyway, so that is probably a better approach to take.
350+
351+
### General consideration to keep in mind
352+
353+
While some people may find it difficult to justify these changes, at a minimum we need to have a clearly defined strategy for module manifest creation/consumption going forward that isn't held back by downlevel versions of PowerShell. In particular, we need to know where new keys should be stored, ideally in a way that makes sense to end users and is easy to manage. Please keep that in mind while considering the options presented here.

0 commit comments

Comments
 (0)