Skip to content

Commit e57cec3

Browse files
FriedrichWeinmannFriedrichWeinmann
authored
Merge pull request #2 from PowershellFrameworkCollective/development
Help Update
2 parents 9585dbc + 5b4e5f6 commit e57cec3

File tree

1 file changed

+205
-58
lines changed

1 file changed

+205
-58
lines changed

‎PSModuleDevelopment/en-us/about_psmoduledevelopment.help.txt

Lines changed: 205 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,214 @@
11
TOPIC
2-
about_psmoduledevelopment
2+
about_psmoduledevelopment
33

44
SHORT DESCRIPTION
5-
Explains how the PSModuleDevelopment module can enhance your module development
5+
Explains how the PSModuleDevelopment module can enhance your module
6+
development experience
67

78
LONG DESCRIPTION
8-
This module enhances module development by adding simple debugging configuration and tools to your console.
9-
10-
To get the best mileage out of this, add its import to your profile. See this article if you wonder how to do that:
11-
http://allthingspowershell.blogspot.de/2015/01/about-profiles.html
12-
13-
During import it will automatically import all modules that you configure it to import, allowing you to specify ...
14-
- Whether they should be imported in debug mode
15-
- Any action that should be taken before importing
16-
- Any action that should be taken after importing
17-
18-
To configure this, use Set-ModuleDebug
19-
To check the configuration, use Get-ModuleDebug
20-
To remove configurations, use Remove-ModuleDebug
21-
22-
You can also configure a module to NOT be automatically imported and still store debugmode, preimportaction and postimportaction for it. In that case you can use Import-ModuleDebug to import it manually at a later time.
23-
24-
Also, to further simplify your module testing, you can use the function Restart-Shell (or its alias "rss") to swiftly restart a powershell console, reinitializing a clean environment (and auto-importing all modules configured for auto-import).
25-
26-
| Debug Mode:
27-
It was said, that modules may be configured to launch in debug mode. However, debug mode is something that must be configured within the module to be thus imported.
28-
As a general good practice, each module should ship with its own tests. These however should not always be actually executed, thus a trigger must be configured. This module assumes that one such trigger is a variable named "<modulename>_DebugMode" and will write this variable on the global scope, if a configuration is set to debug mode. The module to be tested should then recognize this variable and run its tests. However, this can only ever be configured on the module to be tested.
29-
30-
Example for debug mode:
31-
The module "cPSNetwork" has its own tests file. Its content looks like this:
32-
33-
if ($cPSNetwork_DebugMOde)
34-
{
35-
#region Tests
36-
# Test 1
37-
# Test 2
38-
# Test 3
39-
#endregion Tests
40-
}
41-
42-
43-
| Module configurations:
44-
All this configuration is stored in an xml file. By default, it is stored in this path:
45-
"$($env:APPDATA)\InfernalAssociates\PowerShell\PSModuleDevelopment\config.xml"
46-
47-
However, this behavior can be overridden, by configuring a different path (including the file name) in this variable:
48-
$global:PSModuleDevelopment_ModuleConfigPath
49-
(Yes, on the global scope, since module management is a global matter as far as the console is concerned)
9+
Welcome to the introductory guide of the PSModuleDevelopment module.
10+
11+
This module is designed to help you develop PowerShell modules faster,
12+
easier and more reliably, than would otherwise be possible.
13+
14+
For brevity's sake, the module shall henceforth be abbreviated to "PSMD"
15+
16+
17+
#-------------------------------------------------------------------------#
18+
# Index #
19+
#-------------------------------------------------------------------------#
20+
21+
- The Little Helpers
22+
- Refactoring
23+
- Gaming the Type System
24+
- Multilingual Help
25+
- The Need for Speed
26+
- Optimizing the debugging cycle
27+
- Changelog
28+
29+
30+
#-------------------------------------------------------------------------#
31+
# The Little Helpers #
32+
#-------------------------------------------------------------------------#
33+
34+
Often it is the small things that make all the difference. PSMD provides a
35+
few small helpers, that can make all the difference:
36+
37+
# find (Find-PSMDFileContent) #
38+
#-----------------------------#
39+
40+
"find" allows you to swiftly search the module you are working on. For
41+
example, the following line:
42+
43+
find "Get-Test"
44+
45+
Will search the entire module for all instances of "Get-Test"
46+
47+
In order to set this up, you need to point the command to where your module
48+
is being stored:
49+
50+
Set-PSMDModulePath -Path "<path to module folder>"
51+
52+
If you want that path to persist across multiple sessions, you can register
53+
it, which will set the same path again each time you import PSMD:
54+
55+
Register-PSFConfig -FullName 'PSModuleDevelopment.Module.Path'
56+
57+
# rss (Restart-PSMDShell #
58+
#------------------------#
59+
60+
The best we to reset your test environment is to start a new console. This
61+
can be cumbersome though ... unless you use PSMD, in which case it is a
62+
matter of typing "rss" and sending the command.
63+
You can further use one (or multiple) of its parameters for extra benefit:
64+
- NoExit: Instead of closing the old console, you clone it
65+
- Admin: The new console will be started with elevation
66+
- NoProfile: The new console will not load the user profile
67+
68+
69+
#-------------------------------------------------------------------------#
70+
# Refactoring #
71+
#-------------------------------------------------------------------------#
72+
73+
Sometimes you need to fix something at scale. Globally rename a parameter
74+
maybe? Change the help text for the same parameter across all commands?
75+
This is where the refactoring suite of commands of PSMD comes into play:
76+
77+
- Rename-PSMDParameter
78+
- Set-PSMDCmdletBinding
79+
- Set-PSMDParameterHelp
80+
- Split-PSMDScriptFile
81+
82+
More detailed guidance on how to use them shall follow in a dedicated
83+
article, but they already have full Comment Based Help (with examples).
84+
85+
86+
#-------------------------------------------------------------------------#
87+
# Gaming the Type System #
88+
#-------------------------------------------------------------------------#
89+
90+
Sometimes we need to look beneath the hood of C# and .NET. This is when the
91+
suite of commands dealing with assemblies, types at all come in handy.
92+
93+
# New-PSMDFormatTableDefinition
94+
Give this command any type of object, it will create an XML definition you
95+
can use in your module to style the layout of your objects.
96+
97+
# Expand-PSMDTypeName
98+
Returns the full name of the input object's type, as well as the name of
99+
the types it inherits from, recursively until System.Object.
100+
101+
# Find-PSMDType
102+
Searches assemblies for types.
103+
104+
# Get-PSMDAssembly
105+
Returns the assemblies currently loaded.
106+
107+
# Get-PSMDConstructor
108+
Returns information on the available constructors of a type.
109+
110+
111+
#-------------------------------------------------------------------------#
112+
# Multilingual Help #
113+
#-------------------------------------------------------------------------#
114+
115+
In some instances, you may want to provide multilingual help for your
116+
module. If you're wondering how to do that, here's a guide that will walk
117+
you through the details:
118+
119+
https://allthingspowershell.blogspot.com/2016/08/powershell-modules-multilingual-help.html
120+
121+
That said, the PSMD module ships with a command that lets you test out help
122+
text on commands in multiple languages:
123+
124+
Get-PSMDHelpEx (Alias: hex)
125+
126+
It comes with a few gotchas (the main one being that PowerShell caches the
127+
first help retrieved for a command. Testing help in another language
128+
requires a restart of the console).
129+
130+
131+
#-------------------------------------------------------------------------#
132+
# The Need for Speed #
133+
#-------------------------------------------------------------------------#
134+
135+
Speed matters.
136+
In order to develop high performance code however, you need to have the
137+
tools to measure speed accurately. PowerShell has out of the box a tool
138+
that helps with that: 'Measure-Command'
139+
However, while Measure-Command is powerful (and you really should master it
140+
if you haven't already), sometimes you need to measure many repetitions of
141+
code in deeper details. This is where PSMD comes into play with:
142+
143+
Measure-PSMDCommandEx
144+
145+
It's basically a Measure-Command, but can run the same snippet dozens or
146+
hundreds of time in a row and measure duration statistics (total, average,
147+
minimum, ...).
148+
149+
150+
#-------------------------------------------------------------------------#
151+
# Optimizing the debugging cycle #
152+
#-------------------------------------------------------------------------#
153+
154+
The module provides, using its *-PSMDModuleDebug commands, a system to
155+
automatedly perform tests. It can reduce the test workflow in your console
156+
window to the simple act of restarting the shell.
157+
158+
For more details on how to set up your computer and module for this
159+
automated testing cycle, see the following blog post:
160+
161+
https://allthingspowershell.blogspot.com/2016/08/module-development-optimizing-test-and.html
162+
50163

51-
VERSIONS
52-
1.3.0.0 (October 19th, 2016):
53-
- New function: Measure-CommandEx
54-
Measures the executiontime of a scriptblock any number of time and presents the average execution time.
55-
This provides better statistics, as a single run can easily be influenced by outside factors, while an average over a thousand executions will be more reliable.
56-
- Renamed function: Get-ExHelp --> Get-HelpEx
57-
Introduces constistent naming across functions and prevents confusing the "ex" (for Extended) to be confused with a module prefix.
58-
- New Alias: Get-ExHelp --> Get-HelpEx
59-
So that users who still like the old naming can still use it
60-
- New Alias: hex --> Get-HelpEx
61-
Because getting help should be simple.
164+
#-------------------------------------------------------------------------#
165+
# Changelog #
166+
#-------------------------------------------------------------------------#
167+
168+
2.0.0.0 (December 18th, 2017)
169+
- Breaking change: Renamed all commands to include the PSMD prefix
170+
- New function: Find-PSMDFileContent (alias: find), to swiftly search in
171+
your current project
172+
- New function: New-PSMDHeader, to create headers for documentation
173+
- New function: Set-PSMDModulePath, to define the project currently being
174+
worked on
175+
- Suite of new functions that refactor a project:
176+
Rename-PSMDParameter: Renames a parameter, then updates the function's
177+
internal use, then updates the parameter usage
178+
across the entire module.
179+
Set-PSMDCmdletBinding: Inserts a CmdletBinding-Attribute into all
180+
functions that need one
181+
Set-PSMDParameterHelp: Globally updates parameter help for all commands
182+
that share a parameter across the project
183+
Split-PSMDScriptFile: Exports all functions in a file and creates new
184+
files, one per function, named after the function
185+
- New function: New-PSMDFormatTableDefinition, creates format xml for
186+
input types that will present it by default as a table
187+
- New function: Expand-PSMDTypeName, returns a list of all type-names an
188+
object has (by default, the entire inheritance chain)
189+
- New function: Find-PSMDType, search currently imported assemblies for
190+
types
191+
- New function: Get-PSMDAssembly, return the currently imported assemblies
192+
- New function: Get-PSMDConstructor, return the constructor definitions
193+
for a type or the type of an input object
194+
1.3.0.0 (October 19th, 2016):
195+
- New function: Measure-CommandEx
196+
Measures the executiontime of a scriptblock any number of time and
197+
presents the average execution time.
198+
This provides better statistics, as a single run can easily be
199+
influenced by outside factors, while an average over a thousand
200+
executions will be more reliable.
201+
- Renamed function: Get-ExHelp --> Get-HelpEx
202+
Introduces constistent naming across functions and prevents confusing
203+
the "ex" (for Extended) with a module prefix.
204+
- New Alias: Get-ExHelp --> Get-HelpEx
205+
So that users who still like the old naming can still use it
206+
- New Alias: hex --> Get-HelpEx
207+
Because getting help should be simple.
62208

63-
1.2.0.0 (August 15th, 2016):
64-
- New function: Get-ExHelp
65-
Provides localized help to better test modules with localized help content.
209+
1.2.0.0 (August 15th, 2016):
210+
- New function: Get-ExHelp
211+
Provides localized help to better test modules with localized help
212+
content.
66213
KEYWORDS
67214
module development debugging

0 commit comments

Comments
 (0)