ModuleTools

1.7.1

en-US/ModuleTools-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh">
  <command:command>
    <command:details>
      <command:name>Get-MTProjectInfo</command:name>
      <maml:description>
        <maml:para>Retrieves information about a project by reading data from a project.json file in ModuleTools project folder.</maml:para>
      </maml:description>
      <command:verb>Get</command:verb>
      <command:noun>MTProjectInfo</command:noun>
    </command:details>
    <maml:description>
      <maml:para>The Get-MTProjectInfo function retrieves information about a project by reading data from a project.json file located in the current directory. Ensure you navigate to a module directory which has project.json in root directory. Most variables are already defined in output of this command which can be used in pester tests and other configs.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Get-MTProjectInfo</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Path</maml:name>
          <maml:description>
            <maml:para>Provide path to root folder of the ModuleTool based project</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Path</maml:name>
        <maml:description>
          <maml:para>Provide path to root folder of the ModuleTool based project</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <dev:name>hastable with all project data.</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>{{ Fill in the Description }}</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Get-MTProjectInfo
Retrieves project information from the project.json file in the current directory. Useful for debuggin and writing pester tests.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Invoke-MTBuild</command:name>
      <maml:description>
        <maml:para>Build a ModuleTool project to generate ready to import PowerShell Module.</maml:para>
      </maml:description>
      <command:verb>Invoke</command:verb>
      <command:noun>MTBuild</command:noun>
    </command:details>
    <maml:description>
      <maml:para>This function is used to build a module, dist folder is cleaned up and whole module is build from scracth. copies all necessary resource files.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Invoke-MTBuild</maml:name>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters />
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1: Builds module from the project files. ---------</maml:title>
        <maml:introduction>
          <maml:para>Invoke-MTBuild</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2: Builds module and outputs verbose details during entire workflow. ---------</maml:title>
        <maml:introduction>
          <maml:para>Invoke-MTBuild -Verbose</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Invoke-MTTest</command:name>
      <maml:description>
        <maml:para>Runs Pester tests using settings from project.json</maml:para>
      </maml:description>
      <command:verb>Invoke</command:verb>
      <command:noun>MTTest</command:noun>
    </command:details>
    <maml:description>
      <maml:para>Run Pester tests using the specified configuration and settings as defined in project.json. Place all your tests in "tests" folder</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Invoke-MTTest</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
          <maml:name>ExcludeTagFilter</maml:name>
          <maml:description>
            <maml:para>Array of tags to exclude, Provide the tag Pester should exclude</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>TagFilter</maml:name>
          <maml:description>
            <maml:para>Array of tags to run, Provide the tag Pester should run</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">
        <maml:name>ExcludeTagFilter</maml:name>
        <maml:description>
          <maml:para>Array of tags to exclude, Provide the tag Pester should exclude</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>TagFilter</maml:name>
        <maml:description>
          <maml:para>Array of tags to run, Provide the tag Pester should run</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para />
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Invoke-MTTest
Runs the Pester tests for the project.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>Invoke-MTTest -TagFilter "unit","integrate"
Runs the Pester tests for the project, that has tag unit or integrate</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 3 ---------</maml:title>
        <maml:introduction>
          <maml:para>Invoke-MTTest -ExcludeTagFilter "unit"
Runs the Pester tests for the project, excludes any test with tag unit</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>New-MTModule</command:name>
      <maml:description>
        <maml:para>Create module scaffolding along with project.json file to easily build and manage modules in ModuleTools opinionated format</maml:para>
      </maml:description>
      <command:verb>New</command:verb>
      <command:noun>MTModule</command:noun>
    </command:details>
    <maml:description>
      <maml:para>This command creates folder structure and project.json file easily. Use this to quikcly setup a ModuleTools compatible module. Provide all the paramters to command or enter details in the interactive prompts with sane defaults.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>New-MTModule</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Confirm</maml:name>
          <maml:description>
            <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Path</maml:name>
          <maml:description>
            <maml:para>Path where module will be created.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>WhatIf</maml:name>
          <maml:description>
            <maml:para>Runs the command in a mode that only reports what would happen without performing the actions.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Confirm</maml:name>
        <maml:description>
          <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Path</maml:name>
        <maml:description>
          <maml:para>Path where module will be created.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>WhatIf</maml:name>
        <maml:description>
          <maml:para>Runs the command in a mode that only reports what would happen without performing the actions.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para>The structure of the ModuleTools module is meticulously designed according to PowerShell best practices for module development.
While some design decisions may seem unconventional, they are made to ensure that ModuleTools and the process of building modules remain straightforward and easy to manage.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>New-MTModule -Path c:\work
Creates module inside c:\work folder</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Publish-MTLocal</command:name>
      <maml:description>
        <maml:para>Copy built module to local PSModulePath.</maml:para>
      </maml:description>
      <command:verb>Publish</command:verb>
      <command:noun>MTLocal</command:noun>
    </command:details>
    <maml:description>
      <maml:para>Useful quick testing and private modules which don't get hosted in PSGallery or other repository. This command publishes the generated module to local PSModulePath location which gets autoimported when porfile loads.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Publish-MTLocal</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>ModuleDirectoryPath</maml:name>
          <maml:description>
            <maml:para>Path to save the built module.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>ModuleDirectoryPath</maml:name>
        <maml:description>
          <maml:para>Path to save the built module.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <dev:name>System.Object</dev:name>
        </dev:type>
        <maml:description>
          <maml:para>{{ Fill in the Description }}</maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para>{{ Fill in the Notes }}</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- Example 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Publish-MTLocal
Publishes to local $PSModulePath</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- Example 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>Publish-MTLocal -ModuleDirectoryPath \\Some\Path
Publishes/Copies to path provided</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
  <command:command>
    <command:details>
      <command:name>Update-MTModuleVersion</command:name>
      <maml:description>
        <maml:para>Updates the version number of a module in project.json file. Uses [semver] object type.</maml:para>
      </maml:description>
      <command:verb>Update</command:verb>
      <command:noun>MTModuleVersion</command:noun>
    </command:details>
    <maml:description>
      <maml:para>This script updates the version number of a PowerShell module by modifying the project.json file, which gets written into module manifest file (.psd1). [semver] is supported only powershell 7 and above. It increments the version number based on the specified version part (Major, Minor, Patch). Can also attach preview/stable release to Release property</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Update-MTModuleVersion</maml:name>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>Confirm</maml:name>
          <maml:description>
            <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
          <maml:name>Label</maml:name>
          <maml:description>
            <maml:para>The part of the version number to increment (Major, Minor, Patch).
Default is patch.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>PreviewRelease</maml:name>
          <maml:description>
            <maml:para>Use this to use semantic version and attach release name as 'preview' which is supported by PowerShell gallery, to remove it use stable release parameter</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>StableRelease</maml:name>
          <maml:description>
            <maml:para>Use this to use semantic version and removes 'preview' release name converting it to stable release</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
          <maml:name>WhatIf</maml:name>
          <maml:description>
            <maml:para>Runs the command in a mode that only reports what would happen without performing the actions.</maml:para>
          </maml:description>
          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>Confirm</maml:name>
        <maml:description>
          <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">
        <maml:name>Label</maml:name>
        <maml:description>
          <maml:para>The part of the version number to increment (Major, Minor, Patch).
Default is patch.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>PreviewRelease</maml:name>
        <maml:description>
          <maml:para>Use this to use semantic version and attach release name as 'preview' which is supported by PowerShell gallery, to remove it use stable release parameter</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>StableRelease</maml:name>
        <maml:description>
          <maml:para>Use this to use semantic version and removes 'preview' release name converting it to stable release</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">
        <maml:name>WhatIf</maml:name>
        <maml:description>
          <maml:para>Runs the command in a mode that only reports what would happen without performing the actions.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para>Ensure you are in project directory when you run this command.</maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>--------- EXAMPLE 1 ---------</maml:title>
        <maml:introduction>
          <maml:para>Update-MTModuleVersion -Label Major
Updates the Major version part of the module. Version 2.1.3 will become 3.0.0.</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 2 ---------</maml:title>
        <maml:introduction>
          <maml:para>Update-MTModuleVersion
Updates the Patch version part of the module. Version 2.1.3 will become 2.1.4</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
      <command:example>
        <maml:title>--------- EXAMPLE 3 ---------</maml:title>
        <maml:introduction>
          <maml:para>Update-MTModuleVersion -PreviewRelease
Updates the Patch version part of the module. Version 2.1.6 will become 2.1.7-preview</maml:para>
        </maml:introduction>
        <dev:code />
        <dev:remarks />
      </command:example>
    </command:examples>
    <command:relatedLinks>
      <maml:navigationLink>
        <maml:linkText>Online Version</maml:linkText>
        <command:uri />
      </maml:navigationLink>
    </command:relatedLinks>
  </command:command>
</helpItems>