Skip to content

Commit 4f26f4a

Browse files
sdwheelersdwheeler
committed
Add initial content
1 parent fb9f589 commit 4f26f4a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+5186
-3
lines changed

‎.openpublishing.publish.config.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
"docsets_to_publish": [
33
{
44
"docset_name": "PowerShell-Docs-Modules",
5-
"build_source_folder": "PowerShell-Docs-Modules",
6-
"build_output_subfolder": "PowerShell-Docs-Modules",
5+
"build_source_folder": "reference",
6+
"build_output_subfolder": "reference",
77
"locale": "en-us",
88
"monikers": [],
99
"moniker_ranges": [],

‎PowerShell-Docs-Modules/ps-modules/PowerShell-Docs-Modules/index.md

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎PowerShell-Docs-Modules/TOC.yml renamed to ‎reference/TOC.yml

File renamed without changes.

‎PowerShell-Docs-Modules/breadcrumb/toc.yml renamed to ‎reference/breadcrumb/toc.yml

File renamed without changes.

‎PowerShell-Docs-Modules/docfx.json renamed to ‎reference/docfx.json

File renamed without changes.

‎PowerShell-Docs-Modules/docs-conceptual/overview.md renamed to ‎reference/docs-conceptual/overview.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
11
# Overview
22

33
These are the PowerShell cmdlets for the PowerShell Utility Modules.
4+
5+
- Crescendo
6+
- PlatyPS
7+
- PSScriptAnalyzer
8+
- SecretManagement
9+
- SecretStore

‎PowerShell-Docs-Modules/docs-conceptual/toc.yml renamed to ‎reference/docs-conceptual/toc.yml

File renamed without changes.

‎PowerShell-Docs-Modules/index.md renamed to ‎reference/index.md

File renamed without changes.

‎PowerShell-Docs-Modules/mapping/monikerMapping.json renamed to ‎reference/mapping/monikerMapping.json

File renamed without changes.

‎reference/ps-modules/Crescendo/About/about_Crescendo.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Microsoft.PowerShell.Crescendo
2+
3+
## about_Microsoft.PowerShell.Crescendo
4+
5+
### SHORT DESCRIPTION
6+
7+
The PowerShell Crescendo module provides a novel way to create proxy functions
8+
for native commands via `JSON` configuration files.
9+
10+
### LONG DESCRIPTION
11+
12+
PowerShell is capable of invoking native applications like any shell. However,
13+
it would improve the experience if the native command could participate
14+
in the PowerShell pipeline and take advantage of the parameter behaviors
15+
that are part of PowerShell.
16+
17+
The PowerShell Crescendo module provides a way to more easily
18+
take advantage of the PowerShell pipeline by
19+
invoking the native executable, facilitating parameter handling,
20+
and converting text output into objects.
21+
22+
#### JSON Configuration
23+
24+
The PowerShell Crescendo module provides a way to create a small bit of json,
25+
which is then used to create a function which calls the native command.
26+
27+
An annotated schema is provided as part of the module which can improve the authoring process.
28+
29+
#### Parameter handling
30+
31+
The PowerShell Crescendo module allows you to interact with parameters of native
32+
commands in the same way you do with cmdlets.
33+
34+
#### Output Handling
35+
36+
It is also possible to provide a script block which can then be used to convert
37+
the output from the native command into objects. In case the native command
38+
emits `json` or `xml` it is as simple as:
39+
40+
```json
41+
"OutputHandler": [
42+
"ParameterSetName": "Default"
43+
"Handler": "$args[0] | ConvertFrom-Json"
44+
]
45+
```
46+
47+
However, script blocks of arbitrary complexity may also be used.
48+
49+
# EXAMPLES
50+
51+
A number of samples are provided as part of the module, you can see these in
52+
the Samples directory in the module base directory.
53+
54+
A very simple example is as follows to wrap the unix `/bin/ls` command:
55+
56+
```json
57+
{
58+
"$schema": "../src/Microsoft.PowerShell.Crescendo.Schema.json",
59+
"Verb": "Get",
60+
"Noun":"FileList",
61+
"OriginalName": "/bin/ls",
62+
"Parameters": [
63+
{"Name": "Path","OriginalName": "", "OriginalPosition": 1, "Position": 0, "DefaultValue": "." },
64+
{"Name": "Detail","OriginalName": "-l","ParameterType": "switch"}
65+
]
66+
}
67+
```
68+
69+
The name of the proxy function is `Get-FileList` and has two parameters:
70+
71+
- Path
72+
- Which is Position 0, and has a default value of "."
73+
- Detail
74+
- Which is a switch parameter and adds `-l` to the native command parameters
75+
76+
A couple of things to note about the Path parameter
77+
78+
- The `OriginalPosition` is set to 1 and the `OriginalName` is set to an empty string.
79+
This is because some native commands have a parameter which is _not_ named and must
80+
be the last parameter when executed. All parameters will be ordered by the value
81+
of `OriginalPosition` (the default is 0) and when the native command is called,
82+
those parameters (and their values) will be put in that order.
83+
84+
In this example, there is no output handler defined, so the text output of the
85+
command will be returned to the pipeline.
86+
87+
A more complicated example which wraps the linux `apt` command follows:
88+
89+
```json
90+
{
91+
"$schema": "../src/Microsoft.PowerShell.Crescendo.Schema.json",
92+
"Verb": "Get",
93+
"Noun":"InstalledPackage",
94+
"OriginalName": "apt",
95+
"OriginalCommandElements": [
96+
"-q",
97+
"list",
98+
"--installed"
99+
],
100+
"OutputHandlers": [
101+
{
102+
"ParameterSetName":"Default",
103+
"Handler": "$args[0]|select-object -skip 1|foreach-object{$n,$v,$p,$s = \"$_\" -split ' ';[pscustomobject]@{Name=$n -replace '/now';Version=$v;Architecture=$p;State = $s.Trim('[]') -split ','}}"
104+
}
105+
]
106+
}
107+
```
108+
109+
In this case, the output handler converts the text output to a `pscustomobject`
110+
to enable using other PowerShell cmdlets. When run, this provides an object
111+
which encapsulates the apt output
112+
113+
```powershell
114+
PS> get-installedpackage | ?{ $_.name -match "libc"}
115+
116+
Name Version Architecture State
117+
---- ------- ------------ -----
118+
libc-bin 2.31-0ubuntu9.1 amd64 {installed, local}
119+
libc6 2.31-0ubuntu9.1 amd64 {installed, local}
120+
libcap-ng0 0.7.9-2.1build1 amd64 {installed, local}
121+
libcom-err2 1.45.5-2ubuntu1 amd64 {installed, local}
122+
libcrypt1 1:4.4.10-10ubuntu4 amd64 {installed, local}
123+
124+
PS> get-installedpackage | Group-Object Architecture
125+
126+
Count Name Group
127+
----- ---- -----
128+
10 all {@{Name=adduser; Version=3.118ubuntu2; Architecture=all; State=System.String[]}, @{Name=debconf; V…
129+
82 amd64 {@{Name=apt; Version=2.0.2ubuntu0.1; Architecture=amd64; State=System.String[]}, @{Name=base-files…
130+
```
131+
132+
# TROUBLESHOOTING NOTE
133+
134+
The PowerShell Crescendo module is still very early in the development process, so
135+
we expect changes to be made.
136+
137+
One issue is that the output handler is currently a string, so constructing the
138+
script block may be complex; semi-colons will be required to separate statements.
139+
This may be addressed in a later version.
140+
141+
# SEE ALSO
142+
143+
The github repository may be found here: https://github.com/PowerShell/Crescendo
144+
145+
PowerShell Blog posts which present the rational and approaches for native
146+
command wrapping can be found here: [Part 1](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach/)
147+
[Part 2](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2))
148+
149+
# KEYWORDS
150+
151+
Native Command

‎reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
3+
schema: 2.0.0
4+
---
5+
6+
# Get-ScriptAnalyzerRule
7+
## SYNOPSIS
8+
Gets the script analyzer rules on the local computer.
9+
10+
## SYNTAX
11+
12+
```
13+
Get-ScriptAnalyzerRule [-CustomRulePath <String>] [-RecurseCustomRulePath] [-Name <String[]>]
14+
[-Severity <String[]>]
15+
```
16+
17+
## DESCRIPTION
18+
Gets the script analyzer rules on the local computer.
19+
You can select rules by Name, Severity, Source, or SourceType, or even particular words in the rule description.
20+
21+
Use this cmdlet to create collections of rules to include and exclude when running the Invoke-ScriptAnalyzer cmdlet.
22+
23+
To get information about the rules, see the value of the Description property of each rule.
24+
25+
The PSScriptAnalyzer module tests the Windows PowerShell code in a script, module, or DSC resource to determine whether, and to what extent, it fulfils best practice standards.
26+
27+
PSScriptAnalyzer is an open-source project.
28+
For more information about PSScriptAnalyzer, to contribute or file an issue, see GitHub.com\PowerShell\PSScriptAnalyzer.
29+
30+
## EXAMPLES
31+
32+
### -------------------------- EXAMPLE 1 --------------------------
33+
```
34+
Get-ScriptAnalyzerRule
35+
```
36+
37+
This command gets all Script Analyzer rules on the local computer.
38+
39+
### -------------------------- EXAMPLE 2 --------------------------
40+
```
41+
Get-ScriptAnalyzerRule -Severity Error
42+
```
43+
44+
This command gets only rules with the Error severity.
45+
46+
### -------------------------- EXAMPLE 3 --------------------------
47+
```
48+
$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
49+
50+
PS C:\>$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*"
51+
52+
PS C:\> Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
53+
```
54+
55+
This example runs only the DSC rules with the Error severity on the files in the MyDSCModule module.
56+
57+
Using the IncludeRule parameter of Invoke-ScriptAnalyzerRule is much more efficient than using its Severity parameter, which is applied only after using all rules to analyze all module files.
58+
59+
### -------------------------- EXAMPLE 4 --------------------------
60+
```
61+
$TestParameters = Get-ScriptAnalyzerRule -Severity Error, Warning -Name *Parameter*, *Alias*
62+
```
63+
64+
This command gets rules with "Parameter" or "Alias" in the name that generate an Error or Warning.
65+
Use this set of rules to test the parameters of your script or module.
66+
67+
### -------------------------- EXAMPLE 5 --------------------------
68+
```
69+
Get-ScriptAnalyzerRule -CustomRulePath $home\Documents\WindowsPowerShell\Modules\*StrictRules -RecurseCustomRulePath
70+
```
71+
72+
This command gets the standard rules and the rules in the VeryStrictRules and ExtremelyStrictRules modules.
73+
The command uses the RecurseCustomRulePath parameter to get rules defined in subdirectories of the matching paths.
74+
75+
## PARAMETERS
76+
77+
### -CustomRulePath
78+
Gets the Script Analyzer rules in the specified path in addition to the standard Script Analyzer rules.
79+
By default, PSScriptAnalyzer gets only the standard rules specified in the Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll file in the module.
80+
81+
Enter the path to a .NET assembly or module that contains Script Analyzer rules.
82+
You can enter only one value, but wildcards are supported.
83+
To get rules in subdirectories of the path, use the RecurseCustomRulePath parameter.
84+
85+
You can create custom rules by using a custom .NET assembly or a Windows PowerShell module, such as the Community Analyzer Rules in
86+
https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1.
87+
88+
```yaml
89+
Type: String[]
90+
Parameter Sets: (All)
91+
Aliases: CustomizedRulePath
92+
93+
Required: False
94+
Position: Named
95+
Default value: The rules in Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll.
96+
Accept pipeline input: False
97+
Accept wildcard characters: False
98+
```
99+
100+
### -RecurseCustomRulePath
101+
Searches the CustomRulePath location recursively to add rules defined in files in subdirectories of the path.
102+
By default, Get-ScriptAnalyzerRule adds only the custom rules in the specified path.
103+
104+
```yaml
105+
Type: SwitchParameter
106+
Parameter Sets: (All)
107+
Aliases:
108+
109+
Required: False
110+
Position: Named
111+
Default value:
112+
Accept pipeline input: False
113+
Accept wildcard characters: False
114+
```
115+
116+
### -Name
117+
Gets only rules with the specified names or name patterns.
118+
Wildcards are supported.
119+
If you list multiple names or patterns, it gets rules that match any of the name patterns, as though the name patterns were joined by an OR.
120+
121+
By default, Get-ScriptAnalyzerRule gets all rules.
122+
123+
```yaml
124+
Type: String[]
125+
Parameter Sets: (All)
126+
Aliases:
127+
128+
Required: False
129+
Position: Named
130+
Default value: All rules
131+
Accept pipeline input: False
132+
Accept wildcard characters: True
133+
```
134+
135+
### -Severity
136+
Gets only rules with the specified severity values.
137+
Valid values are Information, Warning, and Error.
138+
By default, Get-ScriptAnalyzerRule gets all rules.
139+
140+
```yaml
141+
Type: String[]
142+
Parameter Sets: (All)
143+
Aliases:
144+
145+
Required: False
146+
Position: Named
147+
Default value: All rules
148+
Accept pipeline input: False
149+
Accept wildcard characters: False
150+
```
151+
152+
## INPUTS
153+
154+
### None
155+
You cannot pipe input to this cmdlet.
156+
157+
## OUTPUTS
158+
159+
### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.RuleInfo
160+
The RuleInfo object is a custom object created especially for Script Analyzer. It is not documented on MSDN.
161+
162+
## NOTES
163+
164+
## RELATED LINKS
165+
166+
[Invoke-ScriptAnalyzer]()
167+
168+
[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer)

0 commit comments

Comments
 (0)