(GH-8503) Add about_Module_Manifests #8696

michaeltlombardi · 2022-03-28T18:44:42Z

PR Summary

Adds the about_Module_Manifests topic.

Resolves Add/Update sample manifest to show all fields and possible values #8503

PR Context

Check the boxes below to indicate the content affected by this PR.

Repository or docset configuration

Repo documentation and configuration (.git/.github/.vscode etc.)
Docs build files (.openpublishing.* and build scripts)
Docset configuration (docfx.json, mapping, bread, module folder)

Conceptual documentation

Files in docs-conceptual

Cmdlet reference & about_ topics
When changing cmdlet reference or about_ topics, the changes should be copied to all
relevant versions. Check the boxes below to indicate the versions affected by this change.

PR Checklist

I have read the contributors guide and followed the style and process guidelines
PR has a meaningful title
PR is targeted at the staging branch
All relevant versions updated
Includes content related to issues and PRs - see Closing issues using keywords.
This PR is ready to merge and is not Work in Progress. If the PR is work in progress,
please add the prefix WIP: or [WIP] to the beginning of the title and remove the prefix when
the PR is ready.

opbld32 · 2022-03-28T18:47:11Z

Docs Build status updates of commit 4351989:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	⚠️Warning	View (powershell-5.1)	Details

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

Line 1643, Column 1: [Warning: file-not-found - See documentation] Invalid file link: './About/about_Updatable_Help.md'.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld33 · 2022-03-28T19:05:57Z

Docs Build status updates of commit 788c607:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-5.1)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

sdwheeler

Commit my review comments and taking a break. I will add more comments later.

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

sdwheeler · 2022-03-28T20:52:20Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+a module to the PowerShell Gallery. Manifests also give you a simpler way to
+implement your module logic, handling requirements, compatibility, loading
+order, and more.


What do you mean by "simpler way"? Are you talking about separating module logic from module loading and handling? I think this needs to be clearer.

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

sdwheeler · 2022-03-28T21:43:25Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+```yaml
+Type: System.String
+Aliases: ModuleToProcess
+Required: False
+Default value: None
+Accept wildcard characters: False
+```


Convert to a table as we discussed.

Don't use colons since this is now a table.

Remove Aliases since this is the only instance.

Spell out the value of Required.

No

for Import-Module

for PowerShell Gallery

for Import-Module and PowerShell Gallery

Add Applies to for OS-specific settings

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

sdwheeler · 2022-03-28T22:12:21Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+To export members from `.psm1` or `.dll` files in a module that has a manifest,
+the names of those files must be specified in the values of the **RootModule**
+or **NestedModules** keys in the manifest. Otherwise, their members aren't
+exported.


What about cdxml and xaml types, are their values exported differently? In script-based modules, you can use the Export-ModuleMember cmdlet.

So really, you mean that for exports defined in the manifest, the files containing the items to be exported must be listed in RootModule or NestModules.

sdwheeler · 2022-03-28T22:15:19Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+#### When RootModule is an empty string
+
+This module's **ModuleType** is **Manifest**. The only module members this
+module can export are those defined in the modules specified for the
+**NestedModules** setting.
+
+```powershell
+@{
+    RootModule = ''
+}
+```
+
+#### When RootModule is a script module
+
+This module's **ModuleType** is **Script**.
+
+```powershell
+@{
+    RootModule = 'Example.psm1'
+}
+```
+
+#### When RootModule is a binary module
+
+This module's **ModuleType** is **Binary**.
+
+```powershell
+@{
+    RootModule = 'Example.dll'
+}
+```
+
+#### When RootModule is a relative path
+
+In this example, PowerShell loads `Example.psm1` from the `Files` folder
+relative to the `.psd1` manifest file.
+
+```powershell
+@{
+    RootModule = 'Files/Example.psm1'
+}
+```


I am not sure that these are needed. It seems redundant to the bullet list above.

opbld32 · 2022-03-29T13:44:19Z

Docs Build status updates of commit 03eac14:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-5.1)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

sdwheeler

more comments

sdwheeler · 2022-03-29T17:31:54Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+### ModuleVersion
+
+```yaml
+Type: System.Version


The input type is System.String. The type System.Version is not allowed in restricted language mode or a Data section.

We should be sure that we are documenting the input type. We can talk about how the type changes when imported (as you do below).

sdwheeler · 2022-03-29T17:33:47Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+PowerShellGet uses the version for module installation. You can use the
+`#Requires` statement in a script or the **RequiredModules** setting of another
+module manifest to specify minimum, maximum, and ranges of compatible versions.


I don't think we need to document this here. Module version behavior is covered in those other topics.

sdwheeler · 2022-03-29T17:55:31Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+#### When ModuleVersion is a valid string
+
+In this example, the specified string is converted automatically to a
+**System.Version** object.
+
+```powershell
+@{
+    ModuleVersion = '1.2.3'
+}
+```


I don't think we need the H4s in this section. Instead, make the description more imparitive. For example,

ModuleVersion must be a string value that that can be converted to to a System.Version type when the module is imported.

I don't think we need to show the negative example.

sdwheeler · 2022-03-29T17:59:46Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+Because PowerShell automatically converts the value for you, it is not necessary
+to cast the string to **System.Version** yourself.
+
+#### When ModuleVersion cannot be converted to System.Version
+
+Because the string `a.b.c` specified in this example cannot be converted to a
+**System.Version** object, this setting causes both `Test-ModuleManifest` and
+`Import-Module` to return an error.
+
+```powershell
+@{
+    ModuleVersion = 'a.b.c'
+}
+```
+


Strike

Suggested change

Because PowerShell automatically converts the value for you, it is not necessary

to cast the string to **System.Version** yourself.

#### When ModuleVersion cannot be converted to System.Version

Because the string `a.b.c` specified in this example cannot be converted to a

**System.Version** object, this setting causes both `Test-ModuleManifest` and

`Import-Module` to return an error.

```powershell

@{

ModuleVersion = 'a.b.c'

}

```

sdwheeler · 2022-03-29T18:06:14Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+Specifies the module's compatible PSEditions. If not set, the module is expected
+to be compatible for all PSEditions. For information about PSEdition, see
+[Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support).


Suggested change

Specifies the module's compatible PSEditions. If not set, the module is expected

to be compatible for all PSEditions. For information about PSEdition, see

[Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support).

Specifies the module's compatible PSEditions. If not set, the module is expected

to be compatible for all PSEditions. For information about PSEdition, see:

- [about_PowerShell_Editions](about_powershell_editions.md)

- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support).

sdwheeler · 2022-03-29T18:12:53Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+#### When CompatiblePSEditions is unset
+
+This module can be imported in both **Desktop Edition** and **Core Edition**
+sessions, as well as older versions of Windows PowerShell.
+
+```powershell
+@{
+    # CompatiblePSEditions = @()
+}
+```
+
+#### When CompatiblePSEditions is set to Desktop
+
+This module can only be imported in Windows PowerShell sessions where the
+`$PSEdition` automatic variable's value is `Desktop`.
+
+```powershell
+@{
+    CompatiblePSEditions = @('Desktop')
+}
+```
+
+#### When CompatiblePSEditions is set to Core
+
+This module can only be imported in sessions where the `$PSEdition` automatic
+variable's value is `Core`.
+
+```powershell
+@{
+    CompatiblePSEditions = @('Core')
+}
+```
+
+#### When CompatiblePSEditions is set to Desktop and Core
+
+This module can only be imported in sessions where the `$PSEdition` automatic
+variable exists.
+
+```powershell
+@{
+    CompatiblePSEditions = @('Desktop', 'Core')
+}
+```


Ditch the H4s. Make the description more imperative. Don't need to show all 4 possible combinations. Just explain that "Undefined is the same as @('Desktop', 'Core').

An empty array is allowed. Do we know if that is the same as both? Or what does it mean to be 'none'?

opbld30 · 2022-03-29T21:31:22Z

Docs Build status updates of commit 3f6c0f3:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	⚠️Warning	View (powershell-5.1)	Details

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

Line 207, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.
Line 1478, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld32 · 2022-03-29T21:33:42Z

Docs Build status updates of commit eac3376:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	⚠️Warning	View (powershell-5.1)	Details

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

Line 207, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.
Line 1478, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

sdwheeler

Looking much better. Try to separate consecutive alert blocks.

sdwheeler · 2022-03-29T21:24:20Z

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

+> [!NOTE]
+> This setting may also be specified in module manifests as **ModuleToProcess**.
+> While that name for this setting is valid, it is best practice to use
+> **RootModule** instead.
+


Back-to-back alerts look messy. Move this one after the example and before the next H3

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

opbld33 · 2022-03-30T13:15:07Z

Docs Build status updates of commit bea7a4e:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	⚠️Warning	View (powershell-5.1)	Details

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

Line 207, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.
Line 1478, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld30 · 2022-03-30T13:19:22Z

Docs Build status updates of commit fbe279b:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	⚠️Warning	View (powershell-5.1)	Details

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

Line 207, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.
Line 1470, Column 3: [Warning: file-not-found - See documentation] Invalid file link: 'about_powershell_editions.md'.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld32 · 2022-03-30T14:04:10Z

Docs Build status updates of commit b4804bd:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-5.1)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld32 · 2022-03-30T14:18:22Z

Docs Build status updates of commit 92d4447:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-5.1)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md

opbld33 · 2022-03-30T14:52:14Z

Docs Build status updates of commit 97c6119:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-5.1)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

opbld31 · 2022-03-30T15:29:01Z

Docs Build status updates of commit b566cee:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-5.1)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

This commit adds the `about_Module_Manifests` help topic, explaining the available settings and how to use them in detail.

opbld30 · 2022-03-30T16:14:34Z

Docs Build status updates of commit f16e7f6:

✅ Validation status: passed

File	Status	Preview URL
reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-5.1)
reference/7.0/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-7)
reference/7.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-7.1)
reference/7.2/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-7.2)
reference/7.3/Microsoft.PowerShell.Core/About/about_Module_Manifest.md	✅Succeeded	View (powershell-7.3)

For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

Try searching the docs.microsoft.com contributor guides
Post your question in the Docs support channel

michaeltlombardi force-pushed the GH-8503/staging/about_module_manifests branch from 4351989 to 788c607 Compare March 28, 2022 19:03

sdwheeler requested changes Mar 28, 2022

View reviewed changes

sdwheeler requested changes Mar 29, 2022

View reviewed changes

michaeltlombardi force-pushed the GH-8503/staging/about_module_manifests branch from bea7a4e to fbe279b Compare March 30, 2022 13:16

michaeltlombardi force-pushed the GH-8503/staging/about_module_manifests branch from fbe279b to b4804bd Compare March 30, 2022 14:01

michaeltlombardi force-pushed the GH-8503/staging/about_module_manifests branch from b4804bd to 92d4447 Compare March 30, 2022 14:16

sdwheeler requested changes Mar 30, 2022

View reviewed changes

michaeltlombardi commented Mar 30, 2022

View reviewed changes

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md Outdated Show resolved Hide resolved

reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md Outdated Show resolved Hide resolved

(MicrosoftDocsGH-8503) Add about_Module_Manifests

f16e7f6

This commit adds the `about_Module_Manifests` help topic, explaining the available settings and how to use them in detail.

michaeltlombardi force-pushed the GH-8503/staging/about_module_manifests branch from b566cee to f16e7f6 Compare March 30, 2022 16:12

michaeltlombardi changed the title ~~WIP: (GH-8503) Add about_Module_Manifests~~ (GH-8503) Add about_Module_Manifests Mar 30, 2022

sdwheeler approved these changes Mar 30, 2022

View reviewed changes

sdwheeler merged commit 74b30dc into MicrosoftDocs:staging Mar 30, 2022

michaeltlombardi deleted the GH-8503/staging/about_module_manifests branch March 30, 2022 20:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(GH-8503) Add about_Module_Manifests #8696

(GH-8503) Add about_Module_Manifests #8696

michaeltlombardi commented Mar 28, 2022 •

edited

Loading

opbld32 commented Mar 28, 2022

opbld33 commented Mar 28, 2022

sdwheeler left a comment

sdwheeler Mar 28, 2022

sdwheeler Mar 28, 2022

sdwheeler Mar 28, 2022

sdwheeler Mar 28, 2022

opbld32 commented Mar 29, 2022

sdwheeler left a comment

sdwheeler Mar 29, 2022

sdwheeler Mar 29, 2022

sdwheeler Mar 29, 2022

sdwheeler Mar 29, 2022

sdwheeler Mar 29, 2022

sdwheeler Mar 29, 2022

opbld30 commented Mar 29, 2022

opbld32 commented Mar 29, 2022

sdwheeler left a comment

sdwheeler Mar 29, 2022

opbld33 commented Mar 30, 2022

opbld30 commented Mar 30, 2022

opbld32 commented Mar 30, 2022

opbld32 commented Mar 30, 2022

opbld33 commented Mar 30, 2022

opbld31 commented Mar 30, 2022

opbld30 commented Mar 30, 2022

(GH-8503) Add about_Module_Manifests #8696

(GH-8503) Add about_Module_Manifests #8696

Conversation

michaeltlombardi commented Mar 28, 2022 • edited Loading

PR Summary

PR Context

PR Checklist

opbld32 commented Mar 28, 2022

⚠️ Validation status: warnings

opbld33 commented Mar 28, 2022

✅ Validation status: passed

sdwheeler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opbld32 commented Mar 29, 2022

✅ Validation status: passed

sdwheeler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opbld30 commented Mar 29, 2022

⚠️ Validation status: warnings

opbld32 commented Mar 29, 2022

⚠️ Validation status: warnings

sdwheeler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opbld33 commented Mar 30, 2022

⚠️ Validation status: warnings

opbld30 commented Mar 30, 2022

⚠️ Validation status: warnings

opbld32 commented Mar 30, 2022

✅ Validation status: passed

opbld32 commented Mar 30, 2022

✅ Validation status: passed

opbld33 commented Mar 30, 2022

✅ Validation status: passed

opbld31 commented Mar 30, 2022

✅ Validation status: passed

opbld30 commented Mar 30, 2022

✅ Validation status: passed

michaeltlombardi commented Mar 28, 2022 •

edited

Loading