diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 09a2f5b..d196268 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -2,12 +2,12 @@ "docsets_to_publish": [ { "docset_name": "PowerShell-Docs-Modules", - "build_source_folder": "PowerShell-Docs-Modules", - "build_output_subfolder": "PowerShell-Docs-Modules", + "build_source_folder": "reference", + "build_output_subfolder": "reference", "locale": "en-us", "monikers": [], "moniker_ranges": [], - "open_to_public_contributors": true, + "open_to_public_contributors": false, "type_mapping": { "Conceptual": "Content", "PowershellModule": "Content", diff --git a/PowerShell-Docs-Modules b/PowerShell-Docs-Modules deleted file mode 160000 index dfd5c5b..0000000 --- a/PowerShell-Docs-Modules +++ /dev/null @@ -1 +0,0 @@ -Subproject commit dfd5c5b25822fe9bcdc451efe61e0fc45ef1bba1 diff --git a/breadcrumb/toc.yml b/breadcrumb/toc.yml deleted file mode 100644 index 61d8fca..0000000 --- a/breadcrumb/toc.yml +++ /dev/null @@ -1,3 +0,0 @@ -- name: Docs - tocHref: / - topicHref: / \ No newline at end of file diff --git a/docfx.json b/docfx.json deleted file mode 100644 index fe30844..0000000 --- a/docfx.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "build": { - "content": [ - { - "files": [ "**/*.md", "**/*.yml"], - "src": "docs-conceptual", - "dest": "docs-conceptual", - "version": "samples-v1.0" - }, - { - "files": [ "**/*.yml", "**/About/*.md"], - "src":"samples-v1.0", - "dest": "module", - "version": "samples-v1.0" - }, - { - "files":["toc.yml"], - "src": "breadcrumb", - "dest": "samples/breadcrumb" - } - ], - "versions": { - "samples-v1.0": { "dest": "samples-v1.0" } - }, - "overwrite": [], - "externalReference": [], - "globalMetadata": { - "breadcrumb_path": "/powershell/samples/breadcrumb/toc.json", - "extendBreadcrumb": true, - "feedback_system": "None" - }, - "template": [], - "markdownEngineName": "markdig", - "exportRawModel": true, - "exportViewModel": true - } -} \ No newline at end of file diff --git a/docs-conceptual/index.md b/docs-conceptual/index.md deleted file mode 100644 index c9b8454..0000000 --- a/docs-conceptual/index.md +++ /dev/null @@ -1 +0,0 @@ -# Welcome to MAML2Yaml Sample \ No newline at end of file diff --git a/docs-conceptual/toc.yml b/docs-conceptual/toc.yml deleted file mode 100644 index 9cf78c6..0000000 --- a/docs-conceptual/toc.yml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Overview - items: - - name: Welcome - href: index.md \ No newline at end of file diff --git a/mapping/monikerMapping.json b/mapping/monikerMapping.json deleted file mode 100644 index 5f3f7d5..0000000 --- a/mapping/monikerMapping.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "samples-v1.0": { - "packageRoot": "samples-v1.0", - "conceptualToc": "docs-conceptual/toc.yml", - "conceptualTocUrl": "/powershell/docs-conceptual/toc.json", - "referenceTocUrl": "/powershell/module/toc.json", - "serviceMap": "mapping/serviceMapping.json" - } -} diff --git a/mapping/serviceMapping.json b/mapping/serviceMapping.json deleted file mode 100644 index 2ed4ddf..0000000 --- a/mapping/serviceMapping.json +++ /dev/null @@ -1,263 +0,0 @@ -{ - "Add-AzContainerServiceAgentPoolProfile": "Container Service", - "Add-AzImageDataDisk": "VM Images", - "Add-AzVhd": "VM VHDs", - "Add-AzVMAdditionalUnattendContent": "Virtual Machines", - "Add-AzVMDataDisk": "VM Disks", - "Add-AzVMNetworkInterface": "Virtual Machines", - "Add-AzVMSecret": "Virtual Machines", - "Add-AzVmssAdditionalUnattendContent": "VM Scale Sets", - "Add-AzVmssDataDisk": "VM Scale Sets", - "Add-AzVmssDiagnosticsExtension": "VM Scale Sets", - "Add-AzVmssExtension": "VM Scale Sets", - "Add-AzVMSshPublicKey": "Virtual Machines", - "Add-AzVmssNetworkInterfaceConfiguration": "VM Scale Sets", - "Add-AzVmssSecret": "VM Scale Sets", - "Add-AzVmssSshPublicKey": "VM Scale Sets", - "Add-AzVmssVMDataDisk": "VM Scale Sets", - "Add-AzVmssWinRMListener": "VM Scale Sets", - "Az.Compute": "Az.Compute", - "ConvertTo-AzVMManagedDisk": "VM Disks", - "Disable-AzVMDiskEncryption": "VM Disks", - "Disable-AzVmssDiskEncryption": "VM Scale Sets", - "Export-AzLogAnalyticRequestRateByInterval": "Virtual Machines", - "Export-AzLogAnalyticThrottledRequest": "Virtual Machines", - "Get-AzAvailabilitySet": "Virtual Machines", - "Get-AzComputeResourceSku": "Virtual Machines", - "Get-AzContainerService": "Container Service", - "Get-AzDisk": "VM Disks", - "Get-AzDiskEncryptionSet": "VM Disks", - "Get-AzGallery": "Virtual Machines", - "Get-AzGalleryImageDefinition": "VM Images", - "Get-AzGalleryImageVersion": "VM Images", - "Get-AzHost": "Virtual Machines", - "Get-AzHostGroup": "Virtual Machines", - "Get-AzImage": "VM Images", - "Get-AzProximityPlacementGroup": "Virtual Machines", - "Get-AzRemoteDesktopFile": "Virtual Machines", - "Get-AzSnapshot": "VM Snapshots", - "Get-AzVM": "Virtual Machines", - "Get-AzVMAccessExtension": "VM Extensions", - "Get-AzVMADDomainExtension": "VM Extensions", - "Get-AzVMAEMExtension": "VM Extensions", - "Get-AzVMBootDiagnosticsData": "Virtual Machines", - "Get-AzVMChefExtension": "VM Extensions", - "Get-AzVMCustomScriptExtension": "VM Extensions", - "Get-AzVMDiagnosticsExtension": "VM Extensions", - "Get-AzVMDiskEncryptionStatus": "VM Disks", - "Get-AzVMDscExtension": "VM Extensions", - "Get-AzVMDscExtensionStatus": "VM Extensions", - "Get-AzVMExtension": "VM Extensions", - "Get-AzVMExtensionImage": "VM Images", - "Get-AzVMExtensionImageType": "VM Images", - "Get-AzVMImage": "VM Images", - "Get-AzVMImageOffer": "VM Images", - "Get-AzVMImagePublisher": "VM Images", - "Get-AzVMImageSku": "VM Images", - "Get-AzVMRunCommandDocument": "Virtual Machines", - "Get-AzVMSize": "Virtual Machines", - "Get-AzVMSqlServerExtension": "VM Extensions", - "Get-AzVmss": "VM Scale Sets", - "Get-AzVmssDiskEncryption": "VM Scale Sets", - "Get-AzVmssRollingUpgrade": "VM Scale Sets", - "Get-AzVmssSku": "VM Scale Sets", - "Get-AzVmssVM": "VM Scale Sets", - "Get-AzVmssVMDiskEncryption": "VM Scale Sets", - "Get-AzVMUsage": "Virtual Machines", - "Grant-AzDiskAccess": "VM Disks", - "Grant-AzSnapshotAccess": "VM Snapshots", - "Invoke-AzVMReimage": "Virtual Machines", - "Invoke-AzVMRunCommand": "Virtual Machines", - "Invoke-AzVmssVMRunCommand": "VM Scale Sets", - "New-AzAvailabilitySet": "Virtual Machines", - "New-AzContainerService": "Container Service", - "New-AzContainerServiceConfig": "Container Service", - "New-AzDisk": "VM Disks", - "New-AzDiskConfig": "VM Disks", - "New-AzDiskEncryptionSet": "VM Disks", - "New-AzDiskEncryptionSetConfig": "VM Disks", - "New-AzDiskUpdateConfig": "VM Disks", - "New-AzGallery": "Virtual Machines", - "New-AzGalleryImageDefinition": "VM Images", - "New-AzGalleryImageVersion": "VM Images", - "New-AzHost": "Virtual Machines", - "New-AzHostGroup": "Virtual Machines", - "New-AzImage": "VM Images", - "New-AzImageConfig": "VM Images", - "New-AzProximityPlacementGroup": "Virtual Machines", - "New-AzSnapshot": "VM Snapshots", - "New-AzSnapshotConfig": "VM Snapshots", - "New-AzSnapshotUpdateConfig": "VM Snapshots", - "New-AzVM": "Virtual Machines", - "New-AzVMConfig": "Virtual Machines", - "New-AzVMDataDisk": "VM Disks", - "New-AzVMSqlServerAutoBackupConfig": "Virtual Machines", - "New-AzVMSqlServerAutoPatchingConfig": "Virtual Machines", - "New-AzVMSqlServerKeyVaultCredentialConfig": "Virtual Machines", - "New-AzVmss": "VM Scale Sets", - "New-AzVmssConfig": "VM Scale Sets", - "New-AzVmssIpConfig": "VM Scale Sets", - "New-AzVmssIpTagConfig": "VM Scale Sets", - "New-AzVmssVaultCertificateConfig": "VM Scale Sets", - "Publish-AzVMDscConfiguration": "Virtual Machines", - "Remove-AzAvailabilitySet": "Virtual Machines", - "Remove-AzContainerService": "Container Service", - "Remove-AzContainerServiceAgentPoolProfile": "Container Service", - "Remove-AzDisk": "VM Disks", - "Remove-AzDiskEncryptionSet": "VM Disks", - "Remove-AzGallery": "Virtual Machines", - "Remove-AzGalleryImageDefinition": "VM Images", - "Remove-AzGalleryImageVersion": "VM Images", - "Remove-AzHost": "Virtual Machines", - "Remove-AzHostGroup": "Virtual Machines", - "Remove-AzImage": "VM Images", - "Remove-AzImageDataDisk": "VM Images", - "Remove-AzProximityPlacementGroup": "Virtual Machines", - "Remove-AzSnapshot": "VM Snapshots", - "Remove-AzVM": "Virtual Machines", - "Remove-AzVMAccessExtension": "VM Extensions", - "Remove-AzVMAEMExtension": "VM Extensions", - "Remove-AzVMBackup": "Virtual Machines", - "Remove-AzVMChefExtension": "VM Extensions", - "Remove-AzVMCustomScriptExtension": "VM Extensions", - "Remove-AzVMDataDisk": "VM Disks", - "Remove-AzVMDiagnosticsExtension": "VM Extensions", - "Remove-AzVMDiskEncryptionExtension": "VM Disks", - "Remove-AzVMDscExtension": "VM Extensions", - "Remove-AzVMExtension": "VM Extensions", - "Remove-AzVMNetworkInterface": "Virtual Machines", - "Remove-AzVMSecret": "Virtual Machines", - "Remove-AzVMSqlServerExtension": "VM Extensions", - "Remove-AzVmss": "VM Scale Sets", - "Remove-AzVmssDataDisk": "VM Scale Sets", - "Remove-AzVmssDiagnosticsExtension": "VM Scale Sets", - "Remove-AzVmssExtension": "VM Scale Sets", - "Remove-AzVmssNetworkInterfaceConfiguration": "VM Scale Sets", - "Remove-AzVmssVMDataDisk": "VM Scale Sets", - "Repair-AzVmssServiceFabricUpdateDomain": "VM Scale Sets", - "Restart-AzVM": "Virtual Machines", - "Restart-AzVmss": "VM Scale Sets", - "Revoke-AzDiskAccess": "VM Disks", - "Revoke-AzSnapshotAccess": "VM Snapshots", - "Save-AzVhd": "VM VHDs", - "Save-AzVMImage": "VM Images", - "Set-AzDiskDiskEncryptionKey": "VM Disks", - "Set-AzDiskImageReference": "VM Images", - "Set-AzDiskKeyEncryptionKey": "VM Disks", - "Set-AzDiskUpdateDiskEncryptionKey": "VM Disks", - "Set-AzDiskUpdateKeyEncryptionKey": "VM Disks", - "Set-AzImageOsDisk": "VM Images", - "Set-AzSnapshotDiskEncryptionKey": "VM Snapshots", - "Set-AzSnapshotImageReference": "VM Snapshots", - "Set-AzSnapshotKeyEncryptionKey": "VM Snapshots", - "Set-AzSnapshotUpdateDiskEncryptionKey": "VM Snapshots", - "Set-AzSnapshotUpdateKeyEncryptionKey": "VM Snapshots", - "Set-AzVM": "Virtual Machines", - "Set-AzVMAccessExtension": "VM Extensions", - "Set-AzVMADDomainExtension": "VM Extensions", - "Set-AzVMAEMExtension": "VM Extensions", - "Set-AzVMBackupExtension": "VM Extensions", - "Set-AzVMBginfoExtension": "VM Extensions", - "Set-AzVMBootDiagnostic": "Virtual Machines", - "Set-AzVMChefExtension": "VM Extensions", - "Set-AzVMCustomScriptExtension": "VM Extensions", - "Set-AzVMDataDisk": "VM Disks", - "Set-AzVMDiagnosticsExtension": "VM Extensions", - "Set-AzVMDiskEncryptionExtension": "VM Disks", - "Set-AzVMDscExtension": "VM Extensions", - "Set-AzVMExtension": "VM Extensions", - "Set-AzVMOperatingSystem": "Virtual Machines", - "Set-AzVMOSDisk": "VM Disks", - "Set-AzVMPlan": "Virtual Machines", - "Set-AzVMSourceImage": "VM Images", - "Set-AzVMSqlServerExtension": "VM Extensions", - "Set-AzVmss": "VM Scale Sets", - "Set-AzVmssBootDiagnostic": "VM Scale Sets", - "Set-AzVmssDiskEncryptionExtension": "VM Scale Sets", - "Set-AzVmssOrchestrationServiceState": "VM Scale Sets", - "Set-AzVmssOsProfile": "VM Scale Sets", - "Set-AzVmssRollingUpgradePolicy": "VM Scale Sets", - "Set-AzVmssStorageProfile": "VM Scale Sets", - "Set-AzVmssVM": "VM Scale Sets", - "Start-AzVM": "Virtual Machines", - "Start-AzVmss": "VM Scale Sets", - "Start-AzVmssRollingOSUpgrade": "VM Scale Sets", - "Stop-AzVM": "Virtual Machines", - "Stop-AzVmss": "VM Scale Sets", - "Stop-AzVmssRollingUpgrade": "VM Scale Sets", - "Test-AzVMAEMExtension": "VM Extensions", - "Update-AzAvailabilitySet": "Virtual Machines", - "Update-AzContainerService": "Container Service", - "Update-AzDisk": "VM Disks", - "Update-AzDiskEncryptionSet": "VM Disks", - "Update-AzGallery": "Virtual Machines", - "Update-AzGalleryImageDefinition": "VM Images", - "Update-AzGalleryImageVersion": "VM Images", - "Update-AzImage": "VM Images", - "Update-AzSnapshot": "VM Snapshots", - "Update-AzVM": "Virtual Machines", - "Update-AzVmss": "VM Scale Sets", - "Update-AzVmssInstance": "VM Scale Sets", - "Update-AzVmssVM": "VM Scale Sets", - "Add-History": "Microsoft.PowerShell.Core", - "Clear-History": "Microsoft.PowerShell.Core", - "Clear-Host": "Microsoft.PowerShell.Core", - "Connect-PSSession": "Microsoft.PowerShell.Core", - "Debug-Job": "Microsoft.PowerShell.Core", - "Disable-ExperimentalFeature": "Microsoft.PowerShell.Core", - "Disable-PSRemoting": "Microsoft.PowerShell.Core", - "Disable-PSSessionConfiguration": "Microsoft.PowerShell.Core", - "Disconnect-PSSession": "Microsoft.PowerShell.Core", - "Enable-ExperimentalFeature": "Microsoft.PowerShell.Core", - "Enable-PSRemoting": "Microsoft.PowerShell.Core", - "Enable-PSSessionConfiguration": "Microsoft.PowerShell.Core", - "Enter-PSHostProcess": "Microsoft.PowerShell.Core", - "Enter-PSSession": "Microsoft.PowerShell.Core", - "Exit-PSHostProcess": "Microsoft.PowerShell.Core", - "Exit-PSSession": "Microsoft.PowerShell.Core", - "Export-ModuleMember": "Microsoft.PowerShell.Core", - "ForEach-Object": "Microsoft.PowerShell.Core", - "Get-Command": "Microsoft.PowerShell.Core", - "Get-ExperimentalFeature": "Microsoft.PowerShell.Core", - "Get-Help": "Microsoft.PowerShell.Core", - "Get-History": "Microsoft.PowerShell.Core", - "Get-Job": "Microsoft.PowerShell.Core", - "Get-Module": "Microsoft.PowerShell.Core", - "Get-PSHostProcessInfo": "Microsoft.PowerShell.Core", - "Get-PSSession": "Microsoft.PowerShell.Core", - "Get-PSSessionCapability": "Microsoft.PowerShell.Core", - "Get-PSSessionConfiguration": "Microsoft.PowerShell.Core", - "Import-Module": "Microsoft.PowerShell.Core", - "Invoke-Command": "Microsoft.PowerShell.Core", - "Invoke-History": "Microsoft.PowerShell.Core", - "Microsoft.PowerShell.Core": "Microsoft.PowerShell.Core", - "New-Module": "Microsoft.PowerShell.Core", - "New-ModuleManifest": "Microsoft.PowerShell.Core", - "New-PSRoleCapabilityFile": "Microsoft.PowerShell.Core", - "New-PSSession": "Microsoft.PowerShell.Core", - "New-PSSessionConfigurationFile": "Microsoft.PowerShell.Core", - "New-PSSessionOption": "Microsoft.PowerShell.Core", - "New-PSTransportOption": "Microsoft.PowerShell.Core", - "Out-Default": "Microsoft.PowerShell.Core", - "Out-Host": "Microsoft.PowerShell.Core", - "Out-Null": "Microsoft.PowerShell.Core", - "Receive-Job": "Microsoft.PowerShell.Core", - "Receive-PSSession": "Microsoft.PowerShell.Core", - "Register-ArgumentCompleter": "Microsoft.PowerShell.Core", - "Register-PSSessionConfiguration": "Microsoft.PowerShell.Core", - "Remove-Job": "Microsoft.PowerShell.Core", - "Remove-Module": "Microsoft.PowerShell.Core", - "Remove-PSSession": "Microsoft.PowerShell.Core", - "Save-Help": "Microsoft.PowerShell.Core", - "Set-PSDebug": "Microsoft.PowerShell.Core", - "Set-PSSessionConfiguration": "Microsoft.PowerShell.Core", - "Set-StrictMode": "Microsoft.PowerShell.Core", - "Start-Job": "Microsoft.PowerShell.Core", - "Stop-Job": "Microsoft.PowerShell.Core", - "Test-ModuleManifest": "Microsoft.PowerShell.Core", - "Test-PSSessionConfigurationFile": "Microsoft.PowerShell.Core", - "Unregister-PSSessionConfiguration": "Microsoft.PowerShell.Core", - "Update-Help": "Microsoft.PowerShell.Core", - "Wait-Job": "Microsoft.PowerShell.Core", - "Where-Object": "Microsoft.PowerShell.Core" -} \ No newline at end of file diff --git a/reference/TOC.yml b/reference/TOC.yml new file mode 100644 index 0000000..b5ef71a --- /dev/null +++ b/reference/TOC.yml @@ -0,0 +1,2 @@ +- name: Index + href: index.md \ No newline at end of file diff --git a/reference/breadcrumb/toc.yml b/reference/breadcrumb/toc.yml new file mode 100644 index 0000000..33f3f77 --- /dev/null +++ b/reference/breadcrumb/toc.yml @@ -0,0 +1,14 @@ +- name: Docs + tocHref: / + topicHref: / + items: + - name: PowerShell Utility Modules + tocHref: /powerShell-docs-modules/ + topicHref: /powerShell-docs-modules/index + items: + - name: PowerShell Utility Modules + tocHref: /powershell/powerShell-docs-modules/ + topicHref: /powershell/powerShell-docs-modules/overview + - name: PowerShell Utility Modules + tocHref: /powershell/module/powerShell-docs-modules + topicHref: /powershell/module/powerShell-docs-modules/powerShell-docs-modules diff --git a/reference/docfx.json b/reference/docfx.json new file mode 100644 index 0000000..5feab8b --- /dev/null +++ b/reference/docfx.json @@ -0,0 +1,83 @@ +{ + "build": { + "content": [ + { + "files": [ + "**/*.md" + ], + "src": "docs-conceptual", + "version": "ps-modules", + "dest": "PowerShell-Docs-Modules" + }, + { + "files": [ + "toc.yml" + ], + "src": "docs-conceptual", + "version": "ps-modules", + "dest": "PowerShell-Docs-Modules/ce" + }, + { + "files": [ + "**/*.yml" + ], + "exclude": [ + "toc.yml" + ], + "src": "ps-modules", + "version": "ps-modules", + "dest": "module" + }, + { + "files": [ + "toc.yml" + ], + "src": "ps-modules", + "version": "ps-modules", + "dest": "module/ps-modules" + }, + { + "files":[ + "toc.yml" + ], + "src": "breadcrumb", + "dest": "PowerShell-Docs-Modules/breadcrumb" + }, + { + "files": [ + "**/*.md" + ], + "src": "virtual-folder", + "dest": "module" + } + ], + "resource": [ + { + "files": [ + "**/*.png", + "**/*.jpg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ] + } + ], + "versions": { + "ps-modules": { + "dest": "ps-modules" + } + }, + "overwrite": [], + "externalReference": [], + "globalMetadata": { + "apiPlatform": "powershell", + "breadcrumb_path": "/powershell/PowerShell-Docs-Modules/breadcrumb/toc.json", + "ms.prod": "powershell" + }, + "fileMetadata": {}, + "template": [], + "dest": "PowerShell-Docs-Modules", + "markdownEngineName": "markdig" + } +} diff --git a/reference/docs-conceptual/overview.md b/reference/docs-conceptual/overview.md new file mode 100644 index 0000000..68673d4 --- /dev/null +++ b/reference/docs-conceptual/overview.md @@ -0,0 +1,9 @@ +# Overview + +These are the PowerShell cmdlets for the PowerShell Utility Modules. + +- Crescendo +- PlatyPS +- PSScriptAnalyzer +- SecretManagement +- SecretStore diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml new file mode 100644 index 0000000..e5b5555 --- /dev/null +++ b/reference/docs-conceptual/toc.yml @@ -0,0 +1,2 @@ +- name: Overview + href: overview.md diff --git a/reference/index.md b/reference/index.md new file mode 100644 index 0000000..8f4ae03 --- /dev/null +++ b/reference/index.md @@ -0,0 +1 @@ +# Welcome to PowerShell-Docs-Modules! \ No newline at end of file diff --git a/reference/mapping/monikerMapping.json b/reference/mapping/monikerMapping.json new file mode 100644 index 0000000..05c2dc9 --- /dev/null +++ b/reference/mapping/monikerMapping.json @@ -0,0 +1,8 @@ +{ + "ps-modules": { + "conceptualToc": "docs-conceptual/toc.yml", + "conceptualTocUrl": "/powershell/PowerShell-Docs-Modules/ce/toc.json", + "referenceTocUrl": "/powershell/module/ps-modules/toc.json", + "packageRoot": "ps-modules" + } + } \ No newline at end of file diff --git a/reference/ps-modules/Crescendo/About/about_Crescendo.md b/reference/ps-modules/Crescendo/About/about_Crescendo.md new file mode 100644 index 0000000..b481535 --- /dev/null +++ b/reference/ps-modules/Crescendo/About/about_Crescendo.md @@ -0,0 +1,151 @@ +# Microsoft.PowerShell.Crescendo + +## about_Microsoft.PowerShell.Crescendo + +### SHORT DESCRIPTION + +The PowerShell Crescendo module provides a novel way to create proxy functions +for native commands via `JSON` configuration files. + +### LONG DESCRIPTION + +PowerShell is capable of invoking native applications like any shell. However, +it would improve the experience if the native command could participate +in the PowerShell pipeline and take advantage of the parameter behaviors +that are part of PowerShell. + +The PowerShell Crescendo module provides a way to more easily +take advantage of the PowerShell pipeline by +invoking the native executable, facilitating parameter handling, +and converting text output into objects. + +#### JSON Configuration + +The PowerShell Crescendo module provides a way to create a small bit of json, +which is then used to create a function which calls the native command. + +An annotated schema is provided as part of the module which can improve the authoring process. + +#### Parameter handling + +The PowerShell Crescendo module allows you to interact with parameters of native +commands in the same way you do with cmdlets. + +#### Output Handling + +It is also possible to provide a script block which can then be used to convert +the output from the native command into objects. In case the native command +emits `json` or `xml` it is as simple as: + +```json + "OutputHandler": [ + "ParameterSetName": "Default" + "Handler": "$args[0] | ConvertFrom-Json" + ] +``` + +However, script blocks of arbitrary complexity may also be used. + +# EXAMPLES + +A number of samples are provided as part of the module, you can see these in +the Samples directory in the module base directory. + +A very simple example is as follows to wrap the unix `/bin/ls` command: + +```json +{ + "$schema": "../src/Microsoft.PowerShell.Crescendo.Schema.json", + "Verb": "Get", + "Noun":"FileList", + "OriginalName": "/bin/ls", + "Parameters": [ + {"Name": "Path","OriginalName": "", "OriginalPosition": 1, "Position": 0, "DefaultValue": "." }, + {"Name": "Detail","OriginalName": "-l","ParameterType": "switch"} + ] +} +``` + +The name of the proxy function is `Get-FileList` and has two parameters: + +- Path + - Which is Position 0, and has a default value of "." +- Detail + - Which is a switch parameter and adds `-l` to the native command parameters + +A couple of things to note about the Path parameter + +- The `OriginalPosition` is set to 1 and the `OriginalName` is set to an empty string. + This is because some native commands have a parameter which is _not_ named and must + be the last parameter when executed. All parameters will be ordered by the value + of `OriginalPosition` (the default is 0) and when the native command is called, + those parameters (and their values) will be put in that order. + +In this example, there is no output handler defined, so the text output of the +command will be returned to the pipeline. + +A more complicated example which wraps the linux `apt` command follows: + +```json +{ + "$schema": "../src/Microsoft.PowerShell.Crescendo.Schema.json", + "Verb": "Get", + "Noun":"InstalledPackage", + "OriginalName": "apt", + "OriginalCommandElements": [ + "-q", + "list", + "--installed" + ], + "OutputHandlers": [ + { + "ParameterSetName":"Default", + "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 ','}}" + } + ] +} +``` + +In this case, the output handler converts the text output to a `pscustomobject` +to enable using other PowerShell cmdlets. When run, this provides an object +which encapsulates the apt output + +```powershell +PS> get-installedpackage | ?{ $_.name -match "libc"} + +Name Version Architecture State +---- ------- ------------ ----- +libc-bin 2.31-0ubuntu9.1 amd64 {installed, local} +libc6 2.31-0ubuntu9.1 amd64 {installed, local} +libcap-ng0 0.7.9-2.1build1 amd64 {installed, local} +libcom-err2 1.45.5-2ubuntu1 amd64 {installed, local} +libcrypt1 1:4.4.10-10ubuntu4 amd64 {installed, local} + +PS> get-installedpackage | Group-Object Architecture + +Count Name Group +----- ---- ----- + 10 all {@{Name=adduser; Version=3.118ubuntu2; Architecture=all; State=System.String[]}, @{Name=debconf; V… + 82 amd64 {@{Name=apt; Version=2.0.2ubuntu0.1; Architecture=amd64; State=System.String[]}, @{Name=base-files… +``` + +# TROUBLESHOOTING NOTE + +The PowerShell Crescendo module is still very early in the development process, so +we expect changes to be made. + +One issue is that the output handler is currently a string, so constructing the +script block may be complex; semi-colons will be required to separate statements. +This may be addressed in a later version. + +# SEE ALSO + +The github repository may be found here: https://github.com/PowerShell/Crescendo + +PowerShell Blog posts which present the rational and approaches for native +command wrapping can be found here: [Part 1](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach/) +[Part 2](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2)) + +# KEYWORDS + +Native Command diff --git a/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md new file mode 100644 index 0000000..285529e --- /dev/null +++ b/reference/ps-modules/PSScriptAnalyzer/Get-ScriptAnalyzerRule.md @@ -0,0 +1,168 @@ +--- +external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +schema: 2.0.0 +--- + +# Get-ScriptAnalyzerRule +## SYNOPSIS +Gets the script analyzer rules on the local computer. + +## SYNTAX + +``` +Get-ScriptAnalyzerRule [-CustomRulePath ] [-RecurseCustomRulePath] [-Name ] + [-Severity ] +``` + +## DESCRIPTION +Gets the script analyzer rules on the local computer. +You can select rules by Name, Severity, Source, or SourceType, or even particular words in the rule description. + +Use this cmdlet to create collections of rules to include and exclude when running the Invoke-ScriptAnalyzer cmdlet. + +To get information about the rules, see the value of the Description property of each rule. + +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. + +PSScriptAnalyzer is an open-source project. +For more information about PSScriptAnalyzer, to contribute or file an issue, see GitHub.com\PowerShell\PSScriptAnalyzer. + +## EXAMPLES + +### -------------------------- EXAMPLE 1 -------------------------- +``` +Get-ScriptAnalyzerRule +``` + +This command gets all Script Analyzer rules on the local computer. + +### -------------------------- EXAMPLE 2 -------------------------- +``` +Get-ScriptAnalyzerRule -Severity Error +``` + +This command gets only rules with the Error severity. + +### -------------------------- EXAMPLE 3 -------------------------- +``` +$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC + +PS C:\>$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule\*" + +PS C:\> Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse +``` + +This example runs only the DSC rules with the Error severity on the files in the MyDSCModule module. + +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. + +### -------------------------- EXAMPLE 4 -------------------------- +``` +$TestParameters = Get-ScriptAnalyzerRule -Severity Error, Warning -Name *Parameter*, *Alias* +``` + +This command gets rules with "Parameter" or "Alias" in the name that generate an Error or Warning. +Use this set of rules to test the parameters of your script or module. + +### -------------------------- EXAMPLE 5 -------------------------- +``` +Get-ScriptAnalyzerRule -CustomRulePath $home\Documents\WindowsPowerShell\Modules\*StrictRules -RecurseCustomRulePath +``` + +This command gets the standard rules and the rules in the VeryStrictRules and ExtremelyStrictRules modules. +The command uses the RecurseCustomRulePath parameter to get rules defined in subdirectories of the matching paths. + +## PARAMETERS + +### -CustomRulePath +Gets the Script Analyzer rules in the specified path in addition to the standard Script Analyzer rules. +By default, PSScriptAnalyzer gets only the standard rules specified in the Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll file in the module. + +Enter the path to a .NET assembly or module that contains Script Analyzer rules. +You can enter only one value, but wildcards are supported. +To get rules in subdirectories of the path, use the RecurseCustomRulePath parameter. + +You can create custom rules by using a custom .NET assembly or a Windows PowerShell module, such as the Community Analyzer Rules in +https://github.com/PowerShell/PSScriptAnalyzer/blob/development/Tests/Engine/CommunityAnalyzerRules/CommunityAnalyzerRules.psm1. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: CustomizedRulePath + +Required: False +Position: Named +Default value: The rules in Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll. +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RecurseCustomRulePath +Searches the CustomRulePath location recursively to add rules defined in files in subdirectories of the path. +By default, Get-ScriptAnalyzerRule adds only the custom rules in the specified path. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +Gets only rules with the specified names or name patterns. +Wildcards are supported. +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. + +By default, Get-ScriptAnalyzerRule gets all rules. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules +Accept pipeline input: False +Accept wildcard characters: True +``` + +### -Severity +Gets only rules with the specified severity values. +Valid values are Information, Warning, and Error. +By default, Get-ScriptAnalyzerRule gets all rules. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules +Accept pipeline input: False +Accept wildcard characters: False +``` + +## INPUTS + +### None +You cannot pipe input to this cmdlet. + +## OUTPUTS + +### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.RuleInfo +The RuleInfo object is a custom object created especially for Script Analyzer. It is not documented on MSDN. + +## NOTES + +## RELATED LINKS + +[Invoke-ScriptAnalyzer]() + +[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md new file mode 100644 index 0000000..acbacc0 --- /dev/null +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-Formatter.md @@ -0,0 +1,118 @@ +--- +external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +schema: 2.0.0 +--- + +# Invoke-Formatter +## SYNOPSIS +Formats a script text based on the input settings or default settings. + +## SYNTAX + +``` +Invoke-Formatter [-ScriptDefinition] [-Settings ] [-Range ] +``` + +## DESCRIPTION + +The Invoke-Formatter cmdlet takes a string parameter named ScriptDefinition and formats it according to the input settings parameter Settings. If no Settings parameter is provided, the cmdlet assumes the default code formatting settings as defined in Settings/CodeFormatting.psd1. + +## EXAMPLES + +### -------------------------- EXAMPLE 1 -------------------------- +``` +$scriptDefinition = @' +function foo { +"hello" + } +'@ + +Invoke-Formatter -ScriptDefinition $scriptDefinition +``` + +This command formats the input script text using the default settings. + +### -------------------------- EXAMPLE 2 -------------------------- +``` +$scriptDefinition = @' +function foo { +"hello" +} +'@ + +$settings = @{ + IncludeRules = @("PSPlaceOpenBrace", "PSUseConsistentIndentation") + Rules = @{ + PSPlaceOpenBrace = @{ + Enable = $true + OnSameLine = $false + } + PSUseConsistentIndentation = @{ + Enable = $true + } + } +} + +Invoke-Formatter -ScriptDefinition $scriptDefinition -Settings $settings +``` + +This command formats the input script text using the settings defined in the $settings hashtable. + +### -------------------------- EXAMPLE 3 -------------------------- +``` +Invoke-Formatter -ScriptDefinition $scriptDefinition -Settings /path/to/settings.psd1 +``` + +This command formats the input script text using the settings defined in the settings.psd1 file. + +## PARAMETERS + +### -ScriptDefinition +The script text to be formated. + +*NOTE*: Unlike ScriptBlock parameter, the ScriptDefinition parameter require a string value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Settings +A settings hashtable or a path to a PowerShell data file (.psd1) file that contains the settings. + +```yaml +Type: Object +Parameter Sets: (All) + +Required: False +Position: 2 +Default value: CodeFormatting +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Range +The range within which formatting should take place. The parameter is an array of integers of length 4 such that the first, second, third and last elements correspond to the start line number, start column number, end line number and end column number. These numbers must be greater than 0. + +```yaml +Type: Int32[] +Parameter Sets: (All) + +Required: False +Position: 3 +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +## OUTPUTS + +### System.String +The formatted string result. diff --git a/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md new file mode 100644 index 0000000..4150da0 --- /dev/null +++ b/reference/ps-modules/PSScriptAnalyzer/Invoke-ScriptAnalyzer.md @@ -0,0 +1,539 @@ +--- +external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml +schema: 2.0.0 +--- + +# Invoke-ScriptAnalyzer +## SYNOPSIS +Evaluates a script or module based on selected best practice rules + +## SYNTAX + +### UNNAMED_PARAMETER_SET_1 +``` +Invoke-ScriptAnalyzer [-Path] [-CustomRulePath ] [-RecurseCustomRulePath] + [-ExcludeRule ] [-IncludeRule ] [-Severity ] [-Recurse] [-SuppressedOnly] [-Fix] [-EnableExit] [-ReportSummary] + [-Settings ] +``` + +### UNNAMED_PARAMETER_SET_2 +``` +Invoke-ScriptAnalyzer [-ScriptDefinition] [-CustomRulePath ] [-RecurseCustomRulePath] + [-ExcludeRule ] [-IncludeRule ] [-Severity ] [-Recurse] [-SuppressedOnly] [-EnableExit] [-ReportSummary] + [-Settings ] +``` + +## DESCRIPTION +Invoke-ScriptAnalyzer evaluates a script or module files (.ps1, .psm1 and .psd1 files) based on a collection of best practice rules and returns objects +that represent rule violations. It also includes special rules to analyze DSC resources. + +In each evaluation, you can run either all rules or just a specific set using the -IncludeRule parameter and also exclude rules using the -ExcludeRule parameter. +Invoke-ScriptAnalyzer comes with a set of built-in rules, but you can also use customized rules that you write in +Windows PowerShell scripts, or compile in assemblies by using C#. This is possible by using the -CustomRulePath parameter and it will then only run those custom rules, if the built-in rules should still be run, then also specify the -IncludeDefaultRules parameter. Custom rules are also supported together with the -IncludeRule and -ExcludeRule parameters. To include multiple custom rules, the -RecurseCustomRulePath parameter can be used. + +To analyze your script or module, begin by using the Get-ScriptAnalyzerRule cmdlet to examine and select the rules you +want to include and/or exclude from the evaluation. + +You can also include a rule in the analysis, but suppress the output of that rule for selected functions or scripts. +This feature should be used only when absolutely necessary. +To get rules that were suppressed, run Invoke-ScriptAnalyzer with the -SuppressedOnly parameter. +For instructions on suppressing a rule, see the description of the SuppressedOnly parameter. + +For usage in CI systems, the -EnableExit exits the shell with an exit code equal to the number of error records. + +PSScriptAnalyzer is an open-source project. +For more information about PSScriptAnalyzer, to contribute or file an issue, see GitHub.com\PowerShell\PSScriptAnalyzer. + +## EXAMPLES + +### -------------------------- EXAMPLE 1 -------------------------- +``` +Invoke-ScriptAnalyzer -Path C:\Scripts\Get-LogData.ps1 +``` + +This command runs all Script Analyzer rules on the Get-LogData.ps1 script. + +### -------------------------- EXAMPLE 2 -------------------------- +``` +Invoke-ScriptAnalyzer -Path $home\Documents\WindowsPowerShell\Modules -Recurse +``` + +This command runs all Script Analyzer rules on all .ps1 and .psm1 files in the Modules directory and its +subdirectories. + +### -------------------------- EXAMPLE 3 -------------------------- +``` +Invoke-ScriptAnalyzer -Path C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDiagnostics -IncludeRule PSAvoidUsingPositionalParameters +``` + +This command runs only the PSAvoidUsingPositionalParameters rule on the files in the PSDiagnostics module. +You might use a command like this to find all instances of a particular rule violation while working to eliminate it. + +### -------------------------- EXAMPLE 4 -------------------------- +``` +Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs +``` + +This command runs Script Analyzer on the .ps1 and .psm1 files in the MyModules directory, including the scripts in its subdirectories, with all rules except for PSAvoidUsingCmdletAliases and PSAvoidUsingInternalURLs. + +### -------------------------- EXAMPLE 5 -------------------------- +``` +Invoke-ScriptAnalyzer -Path D:\test_scripts\Test-Script.ps1 -CustomRulePath C:\CommunityAnalyzerRules +``` + +This command runs Script Analyzer on Test-Script.ps1 with the standard rules and rules in the C:\CommunityAnalyzerRules path. + +### -------------------------- EXAMPLE 6 -------------------------- +``` +$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC + +PS C:\>$Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule" + +PS C:\> Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse +``` + +This example runs only the rules that are Error severity and have the PSDSC source name. + +### -------------------------- EXAMPLE 7 -------------------------- +``` +function Get-Widgets +{ + [CmdletBinding()] + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")] + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "", Justification="Resolution in progress.")] + Param() + + dir $pshome + ... +} + +PS C:\> Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 + +RuleName Severity FileName Line Message +-------- -------- -------- ---- ------- +PSProvideCommentHelp Information ManageProf 14 The cmdlet 'Get-Widget' does not have a help comment. + iles.psm1 + +PS C:\> Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly + +Rule Name Severity File Name Line Justification +--------- -------- --------- ---- ------------- +PSAvoidUsingCmdletAliases Warning ManageProf 21 Resolution in progress. + iles.psm1 +PSUseSingularNouns Warning ManageProf 14 + iles.psm1 +``` + +This example shows how to suppress the reporting of rule violations in a function and how to discover rule violations +that are suppressed. + +The example uses the SuppressMessageAttribute attribute to suppress the PSUseSingularNouns and +PSAvoidUsingCmdletAliases rules for the Get-Widgets function in the Get-Widgets.ps1 script. +You can use this attribute +to suppress a rule for a module, script, class, function, parameter, or line. + +The first command runs Script Analyzer on the script that contains the Get-Widgets function. +The output reports a rule +violation, but neither of the suppressed rules is listed, even though they are violated. + +The second command uses the SuppressedOnly parameter to discover the rules that are supressed in the Get-Widgets.ps1 +file. +The output reports the suppressed rules. + +### -------------------------- EXAMPLE 8 -------------------------- +``` +# In .\ScriptAnalyzerProfile.txt +@{ + Severity = @('Error', 'Warning') + IncludeRules = 'PSAvoid*' + ExcludeRules = '*WriteHost' +} + +PS C:\> Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Profile .\ScriptAnalyzerProfile.txt +``` + +In this example, we create a Script Analyzer profile and save it in the ScriptAnalyzerProfile.txt file in the local +directory. + +Next, we run Invoke-ScriptAnalyzer on the BitLocker module files. +The value of the Profile parameter is the path to the +Script Analyzer profile. + +If you include a conflicting parameter in the Invoke-ScriptAnalyzer command, such as '-Severity Error', +Invoke-ScriptAnalyzer uses the profile value and ignores the parameter. + +### -------------------------- EXAMPLE 9 -------------------------- +``` +Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello'}" + +RuleName Severity FileName Line Message +-------- -------- -------- ---- ------- +PSAvoidUsingWriteHost Warning 1 Script + because + there i + suppres + Write-O +PSUseSingularNouns Warning 1 The cmd + noun sh +``` + +This command uses the ScriptDefinition parameter to analyze a function at the command line. +The function string is enclosed in quotation marks. + +When you use the ScriptDefinition parameter, the FileName property of the DiagnosticRecord object is $null. + +## PARAMETERS + +### -Path +Specifies the path to the scripts or module to be analyzed. +Wildcard characters are supported. + +Enter the path to a script (.ps1) or module file (.psm1) or to a directory that contains scripts or modules. +If the directory contains other types of files, they are ignored. + +To analyze files that are not in the root directory of the specified path, use a wildcard character +(C:\Modules\MyModule\*) or the Recurse parameter. + +```yaml +Type: String +Parameter Sets: UNNAMED_PARAMETER_SET_1 +Aliases: PSPath + +Required: True +Position: 0 +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CustomRulePath +Uses only the custom rules defined in the specified paths to the analysis. To still use the built-in rules, add the -IncludeDefaultRules switch. + +Enter the path to a file that defines rules or a directory that contains files that define rules. +Wildcard characters are supported. +To add rules defined in subdirectories of the path, use the RecurseCustomRulePath parameter. + +By default, Invoke-ScriptAnalyzer uses only rules defined in the Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules.dll file in the PSScriptAnalyzer module. + +If Invoke-ScriptAnalyzer cannot find rules in the CustomRulePath, it runs the standard rules without notice. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: CustomizedRulePath + +Required: False +Position: Named +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RecurseCustomRulePath +Adds rules defined in subdirectories of the CustomRulePath location. +By default, Invoke-ScriptAnalyzer uses only the custom rules defined in the specified file or directory. +To still use the built-in rules, additionally use the -IncludeDefaultRules switch. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExcludeRule +Omits the specified rules from the Script Analyzer test. +Wildcard characters are supported. + +Enter a comma-separated list of rule names, a variable that contains rule names, or a command that gets rule names. +You can also specify a list of excluded rules in a Script Analyzer profile file. +You can exclude standard rules and rules in a custom rule path. + +When you exclude a rule, the rule does not run on any of the files in the path. +To exclude a rule on a particular line, parameter, function, script, or class, adjust the Path parameter or suppress the rule. +For information about suppressing a rule, see the examples. + +If a rule is specified in both the ExcludeRule and IncludeRule collections, the rule is excluded. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules are included. +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeDefaultRules +Invoke default rules along with Custom rules + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeRule +Runs only the specified rules in the Script Analyzer test. +By default, PSScriptAnalyzer runs all rules. + +Enter a comma-separated list of rule names, a variable that contains rule names, or a command that gets rule names. +Wildcard characters are supported. +You can also specify rule names in a Script Analyzer profile file. + +When you use the CustomizedRulePath parameter, you can use this parameter to include standard rules and rules in the +custom rule paths. + +If a rule is specified in both the ExcludeRule and IncludeRule collections, the rule is excluded. + +Also, Severity takes precedence over IncludeRule. +For example, if Severity is Error, you cannot use IncludeRule to include a Warning rule. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rules are included. +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Severity +After running Script Analyzer with all rules, this parameter selects rule violations with the specified severity. + +Valid values are: Error, Warning, and Information. +You can specify one ore more severity values. + +Because this parameter filters the rules only after running with all rules, it is not an efficient filter. +To filter rules efficiently, use Get-ScriptAnalyzer rule to get the rules you want to run or exclude and +then use the ExcludeRule or IncludeRule parameters. + +Also, Severity takes precedence over IncludeRule. +For example, if Severity is Error, you cannot use IncludeRule to include a Warning rule. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: All rule violations +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Recurse +Runs Script Analyzer on the files in the Path directory and all subdirectories recursively. + +Recurse applies only to the Path parameter value. +To search the CustomRulePath recursively, use the RecurseCustomRulePath parameter. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SuppressedOnly +Returns rules that are suppressed, instead of analyzing the files in the path. + +When you used SuppressedOnly, Invoke-ScriptAnalyzer returns a SuppressedRecord object +(Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord). + +To suppress a rule, use the SuppressMessageAttribute. +For help, see the examples. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Fix +Fixes certain warnings which contain a fix in their DiagnosticRecord. + +When you used Fix, Invoke-ScriptAnalyzer runs as usual but will apply the fixes before running the analysis. +Please make sure that you have a backup of your files when using this switch. +It tries to preserve the file encoding but there are still some cases where the encoding can change. + +```yaml +Type: SwitchParameter +Parameter Sets: UNNAMED_PARAMETER_SET_1 +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -EnableExit +Exits PowerShell and returns an exit code equal to the number of error records. This can be useful in CI systems. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ReportSummary +Writes a report summary of the found warnings to the host. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Settings +File path that contains user profile or hash table for ScriptAnalyzer + +Runs Invoke-ScriptAnalyzer with the parameters and values specified in a Script Analyzer profile file or hash table + +If the path, the file's or hashtable's content are invalid, it is ignored. +The parameters and values in the profile take precedence over the same parameter and values specified at the command line. + +A Script Analyzer profile file is a text file that contains a hash table with one or more of the following keys: + +-- CustomRulePath +-- ExcludeRules +-- IncludeDefaultRules +-- IncludeRules +-- RecurseCustomRulePath +-- Rules +-- Severity + +The keys and values in the profile are interpreted as if they were standard parameters and parameter values of Invoke-ScriptAnalyzer. + +To specify a single value, enclose the value in quotation marks. +For example: + + @{ Severity = 'Error'} + +To specify multiple values, enclose the values in an array. +For example: + + @{ Severity = 'Error', 'Warning'} + +A more sophisticated example is: + + @{ + CustomRulePath='path\to\CustomRuleModule.psm1' + IncludeDefaultRules=$true + ExcludeRules = @( + 'PSAvoidUsingWriteHost', + 'MyCustomRuleName' + ) + } + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: Profile + +Required: False +Position: Named +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ScriptDefinition +Runs Invoke-ScriptAnalyzer on commands, functions, or expressions in a string. +You can use this feature to analyze statements, expressions, and functions, independent of their script context. + +Unlike ScriptBlock parameters, the ScriptDefinition parameter requires a string value. + +```yaml +Type: String +Parameter Sets: UNNAMED_PARAMETER_SET_2 +Aliases: + +Required: True +Position: 0 +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SaveDscDependency +Resolve DSC resource dependency + +Whenever Invoke-ScriptAnalyzer is run on a script having the dynamic keyword "Import-DSCResource -ModuleName ", if is not present in any of the PSModulePath, Invoke-ScriptAnalyzer gives parse error. This error is caused by the powershell parser not being able to find the symbol for . If Invoke-ScriptAnalyzer finds the module in the PowerShell Gallery (www.powershellgallery.com) then it downloads the missing module to a temp path. The temp path is then added to PSModulePath only for duration of the scan. The temp location can be found in $LOCALAPPDATA/PSScriptAnalyzer/TempModuleDir. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + + +## INPUTS + +### None +You cannot pipe input to this cmdlet. + +## OUTPUTS + +### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord +By default, Invoke-ScriptAnalyzer returns one DiagnosticRecord object to report a rule violation. + +### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.SuppressedRecord +If you use the SuppressedOnly parameter, Invoke-ScriptAnalyzer instead returns a SuppressedRecord object. + +## NOTES + +## RELATED LINKS + +[Get-ScriptAnalyzerRule]() + +[PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer) diff --git a/reference/ps-modules/PlatyPS/About/about_platyPS.md b/reference/ps-modules/PlatyPS/About/about_platyPS.md new file mode 100644 index 0000000..397ddea --- /dev/null +++ b/reference/ps-modules/PlatyPS/About/about_platyPS.md @@ -0,0 +1,18 @@ +# platyPS +## about_platyPS + +# SHORT DESCRIPTION +Write PowerShell External Help in Markdown. + +# LONG DESCRIPTION + +PlatyPS provides a way to + +- Write PowerShell External Help in Markdown +- Generate markdown help (example) for your existing modules +- Keep markdown help up-to-date with your code + +Markdown help docs can be generated from old external help files (also known as MAML-xml help), +the command objects (reflection), or both. + +PlatyPS can also generate cab files for Update-Help. diff --git a/reference/ps-modules/PlatyPS/Get-HelpPreview.md b/reference/ps-modules/PlatyPS/Get-HelpPreview.md new file mode 100644 index 0000000..651db8f --- /dev/null +++ b/reference/ps-modules/PlatyPS/Get-HelpPreview.md @@ -0,0 +1,111 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/Get-HelpPreview.md +schema: 2.0.0 +--- + +# Get-HelpPreview + +## SYNOPSIS +Displays your generated external help as **Get-Help** output. + +## SYNTAX + +``` +Get-HelpPreview -Path [-ConvertNotesToList] [-ConvertDoubleDashLists] [] +``` + +## DESCRIPTION +The **Get-HelpPreview** cmdlet displays your generated external help as **Get-Help** output. +Specify one or more files in Microsoft Assistance Markup Language (MAML) format. + +## EXAMPLES + +### Example 1: Preview the PlatyPS help +``` +PS C:\> $Help = Get-HelpPreview -Path ".\out\platyPS\en-US\PlatyPS-help.xml" + +PS C:\> $Help.Name + +Get-HelpPreview +Get-MarkdownMetadata +New-ExternalHelp +New-ExternalHelpCab +New-MarkdownHelp +Update-MarkdownHelp +Update-MarkdownHelpModule +Update-MarkdownHelpSchema +``` + +The first command creates a **Help** object for the the specified MAML file. +The command stores it in the $Help variable. + +The second command displays the **Name** property for each of the objects in $Help. + +## PARAMETERS + +### -Path +Specifies an array of paths of MAML external help files. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: True +``` + +### -ConvertNotesToList +Indicates that this cmldet formats multiple paragraph items in the **NOTES** section as single list items. +This output follows TechNet formatting. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ConvertDoubleDashLists +Indicates that this cmldet converts double-hyphen list bullets into single-hyphen bullets. +Double-hyphen lists are common in Windows PowerShell documentation. +Markdown accepts single-hyphens for lists. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### Help Object +This cmdlet returns a **Help** object, which is the same output as **Get-Help**. + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/PlatyPS/Get-MarkdownMetadata.md b/reference/ps-modules/PlatyPS/Get-MarkdownMetadata.md new file mode 100644 index 0000000..dad4e87 --- /dev/null +++ b/reference/ps-modules/PlatyPS/Get-MarkdownMetadata.md @@ -0,0 +1,138 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/Get-MarkdownMetadata.md +schema: 2.0.0 +--- + +# Get-MarkdownMetadata + +## SYNOPSIS +Gets metadata from the header of a markdown file. + +## SYNTAX + +### FromPath (Default) +``` +Get-MarkdownMetadata -Path [] +``` + +### FromMarkdownString +``` +Get-MarkdownMetadata -Markdown [] +``` + +## DESCRIPTION +The **Get-MarkdownMetadata** cmdlet gets the metadata from the header of a markdown file that is supported by PlatyPS. +The command returns the metadata as a hash table. + +PlatyPS stores metadata in the header block of a markdown file as key-value pairs of strings. +By default, PlatyPS stores help file name and markdown schema version. + +Metadata section can contain user-provided values for use with external tools. +The [New-ExternalHelp](New-ExternalHelp.md) cmdlet ignores this metadata. + +## EXAMPLES + +### Example 1: Get metadata from a file +``` +PS C:\> Get-MarkdownMetadata -Path ".\docs\Get-MarkdownMetadata.md" + +Key Value +--- ----- +external help file platyPS-help.xml +schema 2.0.0 +``` + +This command retrieves metadata from a markdown file. + +### Example 2: Get metadata from a markdown string +``` +PS C:\> $Markdown = Get-Content -Path ".\docs\Get-MarkdownMetadata.md" -Raw +PS C:\> Get-MarkdownMetadata -Markdown $Markdown + +Key Value +--- ----- +external help file platyPS-help.xml +schema 2.0.0 +``` + +The first command gets the contents of a file, and stores them in the $Markdown variable. + +The second command retrieves metadata from the string in $Metadata. + +### Example 3: Get metadata from all files in a folder +``` +PS C:\> Get-MarkdownMetadata -Path ".\docs" + +Key Value +--- ----- +external help file platyPS-help.xml +schema 2.0.0 +external help file platyPS-help.xml +schema 2.0.0 +external help file platyPS-help.xml +schema 2.0.0 +external help file platyPS-help.xml +schema 2.0.0 +external help file platyPS-help.xml +schema 2.0.0 +external help file platyPS-help.xml +schema 2.0.0 +external help file platyPS-help.xml +schema 2.0.0 +external help file platyPS-help.xml +schema 2.0.0 +``` + +This command gets metadata from each of the markdown files in the .\docs folder. + +## PARAMETERS + +### -Path +Specifies an array of paths of markdown files or folders. + +```yaml +Type: String[] +Parameter Sets: FromPath +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: True +``` + +### -Markdown +Specifies a string that contains markdown formatted text. + +```yaml +Type: String +Parameter Sets: FromMarkdownString +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### Dictionary[String, String] +The cmdlet returns a **Dictionary\[String, String\]** object. +The dictionary contains key-value pairs found in the markdown metadata block. + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/PlatyPS/Merge-MarkdownHelp.md b/reference/ps-modules/PlatyPS/Merge-MarkdownHelp.md new file mode 100644 index 0000000..dbb8e8c --- /dev/null +++ b/reference/ps-modules/PlatyPS/Merge-MarkdownHelp.md @@ -0,0 +1,157 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: +schema: 2.0.0 +--- + +# Merge-MarkdownHelp + +## SYNOPSIS +Merge multiple markdown versions of the same cmdlet into a single markdown file. + +## SYNTAX + +``` +Merge-MarkdownHelp [-Path] [-OutputPath] [-Encoding ] [-ExplicitApplicableIfAll] + [-Force] [[-MergeMarker] ] [] +``` + +## DESCRIPTION +Similar modules, or different versions of the same module, often contain duplicate content. + +Merge-MarkdownHelp merges the multiple markdown files into a single markdown file. +It uses the `applicable:` yaml metadata field to identify what versions or tags are applicable. +It acts on two levels: for the whole cmdlet and for individual parameters. + +The resulting markdown contains the `applicable:` tags as well as all of the content of the original markdown files. +Duplicate content is simply ignored. +Content that is unique to each file is merged using **merge markers**, followed by a comma-separated list of applicable tags. +A **merge marker** is a string of text that acts as a marker to describe the content that was merged. +The default **merge marker** text consists of three exclamation points !!! however this can be changed to any relevant text using the **-MergeMarker** flag. + +## EXAMPLES + +### Example 1 +The Test-CsPhoneBootstrap.md cmdlet is included in both Lync Server 2010 and Lync Server 2013. +Much of the content is duplicated and thus we want to have a single file for the cmdlet with unique content merged from each individual file. + +``` +PS C:\> Merge-MarkdownHelp -Path @('Lync Server 2010\Test-CsPhoneBootstrap.md', 'Lync Server 2013\Test-CsPhoneBootstrap.md') -OutputPath lync +``` + +The resulting file will be located at lync\Test-CsPhoneBootstrap.md + +## PARAMETERS + +### -Encoding +Specifies the character encoding for your external help file. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: UTF8 without BOM +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExplicitApplicableIfAll +Always write out full list of applicable tags. +By default cmdlets and parameters that are present in all variations don't get an application tag. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Indicates that this cmdlet overwrites an existing file that has the same name. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MergeMarker +String to be used as a merge text indicator. +Applicable tag list would be included after the marker + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: '!!! ' +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputPath +Specifies the path of the folder where this cmdlet creates the combined markdown help files. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specifies an array of paths of markdown files or folders. +This cmdlet creates combined markdown help based on these files and folders. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: True +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String[] + +## OUTPUTS + +### System.IO.FileInfo[] + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/PlatyPS/New-ExternalHelp.md b/reference/ps-modules/PlatyPS/New-ExternalHelp.md new file mode 100644 index 0000000..1490e13 --- /dev/null +++ b/reference/ps-modules/PlatyPS/New-ExternalHelp.md @@ -0,0 +1,241 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelp.md +schema: 2.0.0 +--- + +# New-ExternalHelp + +## SYNOPSIS +Creates external help file based on markdown supported by PlatyPS. + +## SYNTAX + +``` +New-ExternalHelp -Path -OutputPath [-ApplicableTag ] [-Encoding ] + [-MaxAboutWidth ] [-ErrorLogFile ] [-Force] [-ShowProgress] [] +``` + +## DESCRIPTION +The **New-ExternalHelp** cmdlet creates an external help file based on markdown help files supported by PlatyPS. +You can ship this with a module to provide help by using the **Get-Help** cmdlet. + +If the markdown files that you specify do not follow the PlatyPS [Schema](https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md), this cmdlet returns error messages. + +## EXAMPLES + +### Example 1: Create external help based on the contents of a folder +``` +PS C:\> New-ExternalHelp -Path ".\docs" -OutputPath "out\platyPS\en-US" + + Directory: D:\Working\PlatyPS\out\platyPS\en-US + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/19/2016 12:32 PM 46776 platyPS-help.xml +``` + +This command creates an external help file in the specified location. +This command uses the best practice that the folder name includes the locale. + +### Example 2: Create help that uses custom encoding +``` +PS C:\> New-ExternalHelp -Path ".\docs" -OutputPath "out\PlatyPS\en-US" -Force -Encoding ([System.Text.Encoding]::Unicode) + + + Directory: D:\Working\PlatyPS\out\PlatyPS\en-US + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 6:34 PM 132942 platyPS-help.xml +``` + +This command creates an external help file in the specified location. +This command specifies the *Force* parameter, therefore, it overwrites an existing file. +The command specifies Unicode encoding for the created file. + +### Example 3: Write warnings and errors to file +``` +PS C:\> New-ExternalHelp -Path ".\docs" -OutputPath "out\platyPS\en-US" -ErrorLogFile ".\WarningsAndErrors.json" + + Directory: D:\Working\PlatyPS\out\platyPS\en-US + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/19/2016 12:32 PM 46776 platyPS-help.xml +``` + +This command creates an external help file in the specified location. +This command uses the best practice that the folder name includes the locale. +This command writes the warnings and errors to the WarningsAndErrors.json file. + +## PARAMETERS + +### -OutputPath +Specifies the path of a folder where this cmdlet saves your external help file. +The folder name should end with a locale folder, as in the following example: `.\out\PlatyPS\en-US\`. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Encoding +Specifies the character encoding for your external help file. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: UTF8 without BOM +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Indicates that this cmdlet overwrites an existing file that has the same name. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specifies an array of paths of markdown files or folders. +This cmdlet creates external help based on these files and folders. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: True +``` + +### -ApplicableTag +Specify array of tags to use as a filter. +If cmdlet has `applicable` in the yaml metadata and none of the passed tags is +mentioned there, cmdlet would be ignored in the generated help. +Same applies to the Parameter level `applicable` yaml metadata. +If `applicable` is ommited, cmdlet or parameter would be always present. +See [design issue](https://github.com/PowerShell/platyPS/issues/273) for more details. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaxAboutWidth +Specifies the maximimum line length when generating "about" help text files. +(See New-MarkdownAboutHelp.) Other help file types are not affected by this +parameter. + +Lines inside code blocks are not wrapped at all and are not affected by the +MaxAboutWidth parameter. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 80 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ErrorLogFile +The path where this cmdlet will save formatted results log file. + +The path must include the location and name of the folder and file name with +the json extension. The JSON object contains three properties, Message, FilePath, +and Severity (Warning or Error). + +If this path is not provided, no log will be generated. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ShowProgress +Display progress bars under parsing existing markdown files. + +If this is used generating of help is much slower. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### System.IO.FileInfo[] +This cmdlet returns a **FileInfo[]** object for created files. + +## NOTES + +## RELATED LINKS + +[PowerShell V2 External MAML Help](https://blogs.msdn.microsoft.com/powershell/2008/12/24/powershell-v2-external-maml-help/) + +[Schema](https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md) diff --git a/reference/ps-modules/PlatyPS/New-ExternalHelpCab.md b/reference/ps-modules/PlatyPS/New-ExternalHelpCab.md new file mode 100644 index 0000000..4422773 --- /dev/null +++ b/reference/ps-modules/PlatyPS/New-ExternalHelpCab.md @@ -0,0 +1,126 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelpCab.md +schema: 2.0.0 +--- + +# New-ExternalHelpCab + +## SYNOPSIS +Generates a .cab file. + +## SYNTAX + +``` +New-ExternalHelpCab -CabFilesFolder -LandingPagePath -OutputFolder + [-IncrementHelpVersion] [] +``` + +## DESCRIPTION +The **New-ExternalHelpCab** cmdlet generates a .cab file that contains all the non-recursive content in a folder. +This cmdlet compresses the provided files. + +We recommend that you provide as content only about_ topics and the output from the [New-ExternalHelp](New-ExternalHelp.md) cmdlet to this cmdlet. + +This cmdlet uses metadata stored in the module markdown file to name your .cab file. +This naming matches the pattern that the Windows PowerShell help system requires for use as updatable help. +This metadata is part of the module file created by using the [New-MarkdownHelp](New-MarkdownHelp.md) cmdlet with the *WithModulePage* parameter. + +This cmdlet also generates or updates an existing helpinfo.xml file. +That file provides versioning and locale details to the Windows PowerShell help system. + +## EXAMPLES + +### Example 1: Create a CAB file +``` +PS C:\> New-ExternalHelpCab -CabFilesFolder 'C:\Module\ExternalHelpContent' -LandingPagePath 'C:\Module\ModuleName.md' -OutputPath 'C:\Module\Cab\' +``` + +This commmand creates a .cab file that contains the content folder files. +The .cab file is named for updatable help based on metadata. +The command places the .cab file in the output folder. + +## PARAMETERS + +### -CabFilesFolder +Specifies the folder that contains the help content that this cmdlet packages into a .cab file. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LandingPagePath +Specifies the full path of the Module Markdown file that contains all the metadata required to name the .cab file. +For the required metadata, run **New-MarkdownHelp** with the *WithLandingPage* parameter. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputFolder +Specifies the location of the .cab file and helpinfo.xml file that this cmdlet creates. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncrementHelpVersion +Automatically increment the help version in the module markdown file. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None +You cannot pipe values to this cmdlet. + +## OUTPUTS + +### None +This cmdlet does not generate output. +The cmldet saves its results in the output folder that the *OutputPath* parameter specifies. + +## NOTES + +## RELATED LINKS + +[New-ExternalHelp](New-ExternalHelp.md) +[New-MarkdownAboutHelp](New-MarkdownAboutHelp.md) diff --git a/reference/ps-modules/PlatyPS/New-MarkdownAboutHelp.md b/reference/ps-modules/PlatyPS/New-MarkdownAboutHelp.md new file mode 100644 index 0000000..70b82aa --- /dev/null +++ b/reference/ps-modules/PlatyPS/New-MarkdownAboutHelp.md @@ -0,0 +1,111 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownAboutHelp.md +schema: 2.0.0 +--- + +# New-MarkdownAboutHelp + +## SYNOPSIS +Generates a new About Topic MD file from template. + +## SYNTAX + +``` +New-MarkdownAboutHelp [-OutputFolder] [[-AboutName] ] [] +``` + +## DESCRIPTION +The **New-MarkdownAboutHelp** cmdlet generates a Markdown file that is prepopulated with the standard elements of an About Topic. +The cmdlet copies the template MD, renames headers and file name according to the **AboutName** parameter, +and deposits the file in the directory designated by the **OutputFoler** parameter. + +The About Topic can be converted to Txt format. +About topics must be in txt format or the PowerShell Help engine will not be able to parse the document. +Use the [New-ExternalHelp](New-ExternalHelp.md) cmdlet to convert About Topic markdown files into About Topic txt files. + +## EXAMPLES + +### Example 1 +``` +PS C:\> New-MarkdownAboutHelp -OutputFolder C:\Test -AboutName +PS C:\> Get-ChildItem C:\Test + + Directory: C:\Test + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 7/13/2016 2:12 PM 1491 TestAboutTopic.md +``` + +Create and display file info for PowerShell About Topic Markdown File. + +### Example 2 +``` +PS C:\> New-ExternalHelp -Path C:\Test\ -OutputPath C:\Test + + + Directory: C:\Test + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 7/13/2016 2:15 PM 1550 TestAboutTopic.txt +``` + +Create PowerShell About Topic Txt file from existing Markdown About file. + +## PARAMETERS + +### -AboutName +The name of the about topic. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputFolder +The directory to create the about topic in. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object +This cmdlet returns a object for created files. + +## NOTES +The about topics will need to be added to a cab file to leverage updatable help. + +## RELATED LINKS + +[New-ExternalHelp](New-ExternalHelp.md) + +[New-ExternalHelpCab](New-ExternalHelpCab.md) diff --git a/reference/ps-modules/PlatyPS/New-MarkdownHelp.md b/reference/ps-modules/PlatyPS/New-MarkdownHelp.md new file mode 100644 index 0000000..e83e327 --- /dev/null +++ b/reference/ps-modules/PlatyPS/New-MarkdownHelp.md @@ -0,0 +1,513 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownHelp.md +schema: 2.0.0 +--- + +# New-MarkdownHelp + +## SYNOPSIS +Creates help in markdown format. + +## SYNTAX + +### FromModule +``` +New-MarkdownHelp -Module [-Session ] [-Force] [-AlphabeticParamsOrder] + [-Metadata ] -OutputFolder [-NoMetadata] [-UseFullTypeName] [-Encoding ] + [-WithModulePage] [-ModulePagePath ] [-Locale ] [-HelpVersion ] [-FwLink ] + [-ExcludeDontShow] [] +``` + +### FromCommand +``` +New-MarkdownHelp -Command [-Session ] [-Force] [-AlphabeticParamsOrder] + [-Metadata ] [-OnlineVersionUrl ] -OutputFolder [-NoMetadata] [-UseFullTypeName] + [-Encoding ] [-ExcludeDontShow] [] +``` + +### FromMaml +``` +New-MarkdownHelp -MamlFile [-ConvertNotesToList] [-ConvertDoubleDashLists] [-Force] + [-AlphabeticParamsOrder] [-Metadata ] -OutputFolder [-NoMetadata] [-UseFullTypeName] + [-Encoding ] [-WithModulePage] [-ModulePagePath ] [-Locale ] [-HelpVersion ] + [-FwLink ] [-ModuleName ] [-ModuleGuid ] [-ExcludeDontShow] [] +``` + +## DESCRIPTION +The **New-MarkdownHelp** cmdlet creates help in markdown format based on a module, a command, or a file in Microsoft Assistance Markup Language (MAML) format. + +## EXAMPLES + +### Example 1: Create help from a command +``` +PS C:\> function Command03 {param([string]$Value)} +PS C:\> New-MarkdownHelp -Command "Command03" -OutputFolder ".\docs" + + + Directory: D:\Working\docs + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 6:53 PM 664 Command03.md +``` + +The first command creates a function named Command03 by using standard Windows PowerShell syntax. + +The second command creates help for that stub function in the .\docs folder. + +### Example 2: Create help from a module +``` +PS C:\> Import-Module -Module "PlatyPS" +PS C:\> New-MarkdownHelp -Module "PlatyPS" -OutputFolder ".\docs" -Force + + + Directory: D:\Working\PlatyPS\docs + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 6:54 PM 1496 Get-HelpPreview.md +-a---- 5/22/2016 6:54 PM 3208 Get-MarkdownMetadata.md +-a---- 5/22/2016 6:54 PM 3059 New-ExternalHelp.md +-a---- 5/22/2016 6:54 PM 2702 New-ExternalHelpCab.md +-a---- 5/22/2016 6:54 PM 6234 New-MarkdownHelp.md +-a---- 5/22/2016 6:54 PM 2346 Update-MarkdownHelp.md +-a---- 5/22/2016 6:54 PM 1633 Update-MarkdownHelpModule.md +-a---- 5/22/2016 6:54 PM 1630 Update-MarkdownHelpSchema.md +``` + +The first command loads the PlatyPS module into the current session by using the **Import-Module** cmdlet. + +The second command creates help for all the cmdlets in the PlatyPS module. +It stores them in the .\docs folder. +This command specifies the *Force* parameter. +Therefore, it overwrites existing help markdown files that have the same name. + +### Example 3: Create help from an existing MAML file +``` +PS C:\> New-MarkdownHelp -OutputFolder "D:\PSReadline\docs" -MamlFile 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml' + + Directory: D:\PSReadline\docs + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 6:56 PM 7443 Get-PSReadlineKeyHandler.md +-a---- 5/22/2016 6:56 PM 3586 Get-PSReadlineOption.md +-a---- 5/22/2016 6:56 PM 1549 Remove-PSReadlineKeyHandler.md +-a---- 5/22/2016 6:56 PM 5947 Set-PSReadlineKeyHandler.md +-a---- 5/22/2016 6:56 PM 15320 Set-PSReadlineOption.md +``` + +This command creates help in markdown format for the specified help MAML file. +You do not have to load the module, as in the previous example. +If the module is already loaded, this command creates help based on the MAML file, not on the currently installed module. + +### Example 4: Create help from an existing MAML file for use in a CAB file +``` +PS C:\> New-MarkdownHelp -OutputFolder "D:\PSReadline\docs" -MamlFile 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml' -WithModulePage -Force -ModuleName "PSReadLine" + + + Directory: D:\PSReadline\docs + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 6:59 PM 7443 Get-PSReadlineKeyHandler.md +-a---- 5/22/2016 6:59 PM 3586 Get-PSReadlineOption.md +-a---- 5/22/2016 6:59 PM 1549 Remove-PSReadlineKeyHandler.md +-a---- 5/22/2016 6:59 PM 5947 Set-PSReadlineKeyHandler.md +-a---- 5/22/2016 6:59 PM 15320 Set-PSReadlineOption.md +-a---- 5/22/2016 6:59 PM 942 PSReadLine.md +``` + +This command creates help in markdown format for the specified help MAML file, as in the previous example. +This command also specifies the *WithModulePage* parameter and the *ModuleName* parameter. +The command creates a file named PSReadLine.md that contains links to the other markdown files in this module and metadata that can be used to create .cab files. + +## PARAMETERS + +### -Command +Specifies the name of a command in your current session. +This can be any command supported by Windows PowerShell help, such as a cmdlet or a function. + +```yaml +Type: String[] +Parameter Sets: FromCommand +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Encoding +Specifies the character encoding for your markdown help files. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: UTF8 without BOM +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Indicates that this cmdlet overwrites existing files that have the same names. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FwLink +Specifies the forward link for the module page. +This value is required for .cab file creation. +This value is used as markdown header metadata in the module page. + +```yaml +Type: String +Parameter Sets: FromModule, FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HelpVersion +Specifies the version of your help. +This value is required for .cab file creation. +This value is used as markdown header metadata in the module page. + +```yaml +Type: String +Parameter Sets: FromModule, FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Locale +Specifies the locale of your help. +This value is required for .cab file creation. +This value is used as markdown header metadata in the module page. + +```yaml +Type: String +Parameter Sets: FromModule, FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MamlFile +Specifies an array of paths path of MAML .xml help files. + +```yaml +Type: String[] +Parameter Sets: FromMaml +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Metadata +Specifies metadata that this cmdlet includes in the help markdown files as a hash table of string-to-sting key-value pairs. +This cmdlet writes the metadata in the header of each markdown help file. + +The **New-ExternalHelp** cmdlet does not use this metadata. +External tools can use this metadata. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Module +Specifies an array of names of modules for which this cmdlet creates help in markdown format. + +```yaml +Type: String[] +Parameter Sets: FromModule +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -ModuleGuid +Specifies the GUID of the module of your help. +This value is required for .cab file creation. +This value is used as markdown header metadata in the module page. + +```yaml +Type: String +Parameter Sets: FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ModuleName +Specifies the name of the module of your help. +This value is required for .cab file creation. +This value is used as markdown header metadata in the module page. + +```yaml +Type: String +Parameter Sets: FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoMetadata +Indicates that this cmdlet does not write any metadata in the generated markdown. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OnlineVersionUrl +Specifies the URL where the updatable help function downloads updated help. +If you do not specify a value, the cmdlet uses an empty string. + +```yaml +Type: String +Parameter Sets: FromCommand +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputFolder +Specifies the path of the folder where this cmdlet creates the markdown help files. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WithModulePage +Indicates that this cmdlet creates a module page in the output folder. +This file has the name that the *ModuleName* parameter specifies. +If you did not specify that parameter, the cmdlet supplies the default name MamlModule. +You can overwrite this setting by using *ModulePagePath* which allows you to define different path for module page + +```yaml +Type: SwitchParameter +Parameter Sets: FromModule, FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ConvertNotesToList +Indicates that this cmldet formats multiple paragraph items in the **NOTES** section as single list items. +This output follows TechNet formatting. + +```yaml +Type: SwitchParameter +Parameter Sets: FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ConvertDoubleDashLists +Indicates that this cmldet converts double-hyphen list bullets into single-hyphen bullets. +Double-hyphen lists are common in Windows PowerShell documentation. +Markdown accepts single-hyphens for lists. + +```yaml +Type: SwitchParameter +Parameter Sets: FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AlphabeticParamsOrder +Order parameters alphabetically by name in PARAMETERS section. +There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. +These parameters are common and hence have well-defined behavior. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseFullTypeName +Indicates that the target document will use a full type name instead of a short name for parameters. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Session +Provides support for remote commands. +Pass the session that you used to create the commands with `Import-PSSession`. +This is required to get accurate parameters metadata from the remote session. + +```yaml +Type: PSSession +Parameter Sets: FromModule, FromCommand +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ModulePagePath +When *WithModule* parameter is used by default it puts .md file in same location as all other docs. With this parameter you can specify new name/location providing better placement options. + +```yaml +Type: String +Parameter Sets: FromModule, FromMaml +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExcludeDontShow +Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### String[] +You can pipe module names to this cmdlet. +These are the modules from which this cmdlet creates help markdown. + +## OUTPUTS + +### System.IO.FileInfo[] +This cmdlet returns a **FileInfo[]** object for created files. + +## NOTES + +## RELATED LINKS + +[Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) + +[Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) diff --git a/reference/ps-modules/PlatyPS/New-YamlHelp.md b/reference/ps-modules/PlatyPS/New-YamlHelp.md new file mode 100644 index 0000000..019e300 --- /dev/null +++ b/reference/ps-modules/PlatyPS/New-YamlHelp.md @@ -0,0 +1,153 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-YamlHelp.md +schema: 2.0.0 +--- + +# New-YamlHelp + +## SYNOPSIS +Converts Markdown help into YAML to be read easily by external tools + +## SYNTAX + +``` +New-YamlHelp [-Path] -OutputFolder [-Encoding ] [-Force] [] +``` + +## DESCRIPTION +The **New-YamlHelp** cmdlet works similarly to the **New-ExternalHelp** cmdlet but rather than creating a MAML file to support **Get-Help**, it creates a set of YAML files that can be read by external tools to provide custom rendering of help pages. + +## EXAMPLES + +### Example 1: Create YAML files +``` +PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml + + Directory: D:\Working\PlatyPS\out\yaml + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml +-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml +-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml +-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml +-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml +-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml +-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml +-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml +``` + +This creates one YAML file for each cmdlet so external tools can read the structured data for each cmdlet. + +### Example 2: Create YAML files with specific encoding +``` +PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml -Force -Encoding ([System.Text.Encoding]::Unicode) + + Directory: D:\Working\PlatyPS\out\yaml + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml +-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml +-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml +-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml +-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml +-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml +-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml +-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml +``` + +This will both read and write the files in the specified -Encoding. +The -Force parameter will overwrite files that already exist. + +## PARAMETERS + +### -Encoding +Specifies the character encoding for your external help file. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Indicates that this cmdlet overwrites an existing file that has the same name. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specifies an array of paths of markdown files or folders. +This cmdlet creates external help based on these files and folders. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -OutputFolder +Specifies the folder to create the YAML files in + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### System.IO.FileInfo[] +This cmdlet returns a **FileInfo[]** object for created files. + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/PlatyPS/Update-MarkdownHelp.md b/reference/ps-modules/PlatyPS/Update-MarkdownHelp.md new file mode 100644 index 0000000..ea3b755 --- /dev/null +++ b/reference/ps-modules/PlatyPS/Update-MarkdownHelp.md @@ -0,0 +1,256 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelp.md +schema: 2.0.0 +--- + +# Update-MarkdownHelp + +## SYNOPSIS +Update PlatyPS markdown help files. + +## SYNTAX + +``` +Update-MarkdownHelp [-Path] [[-Encoding] ] [[-LogPath] ] [-LogAppend] + [-AlphabeticParamsOrder] [-UseFullTypeName] [-UpdateInputOutput] [-Force] [-Session ] + [-ExcludeDontShow] [] +``` + +## DESCRIPTION +The **Update-MarkdownHelp** cmdlet updates PlatyPS markdown help files without completely replacing the content of the files. + +Some parameter attributes change over time. +For instance, parameter sets, types, default value, and required. +This cmdlet updates markdown help to reflect those changes. +It also adds placeholder text to the markdown file for any new parameter. + +To propagate changes to your markdown help files, do the following: + +- Load the new version of the module into your Windows PowerShell session. +- Run the **Update-MarkdownHelp** cmdlet to update the files. +- Check new parameters metadata in the markdown files. + +## EXAMPLES + +### Example 1: Update all files in a folder +``` +PS C:\> Update-MarkdownHelp -Path ".\docs" + + Directory: D:\working\PlatyPS\docs + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 6:54 PM 1496 Get-HelpPreview.md +-a---- 5/22/2016 6:54 PM 3208 Get-MarkdownMetadata.md +-a---- 5/22/2016 6:54 PM 3059 New-ExternalHelp.md +-a---- 5/22/2016 6:54 PM 2702 New-ExternalHelpCab.md +-a---- 5/22/2016 6:54 PM 6234 New-MarkdownHelp.md +-a---- 5/22/2016 6:54 PM 2346 Update-MarkdownHelp.md +-a---- 5/22/2016 6:54 PM 1633 Update-MarkdownHelpModule.md +-a---- 5/22/2016 6:54 PM 1630 Update-MarkdownHelpSchema.md +``` + +This command updates all markdown help files in the specified path to match the current cmdlets. + +### Example 2: Update one file and capture log +``` +PS C:\> Update-MarkdownHelp -Path ".\docs\Update-MarkdownHelp.md" -LogPath ".\markdown.log" + + Directory: D:\Working\PlatyPS\docs + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 8:20 PM 9993 New-MarkdownHelp.md +``` + +This command updates a markdown help file. +It writes log information to the markdown.log file. + +## PARAMETERS + +### -Encoding +Specifies the character encoding for your markdown help files. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: UTF8 without BOM +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LogAppend +Indicates that this cmdlet appends information to the log instead overwriting it. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LogPath +Specifies a file path for log information. +The cmdlet writes the VERBOSE stream to the log. +If you specify the *Verbose* parameter, this cmdlet also writes that information to the console. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specifies an array of paths of markdown files and folders to update. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: True +``` + +### -AlphabeticParamsOrder +Order parameters alphabetically by name in PARAMETERS section. +There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. +These parameters are common and hence have well-defined behavior. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseFullTypeName +Indicates that the target document will use a full type name instead of a short name for parameters. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Session +Provides support for remote commands. +Pass the session that you used to create the commands with `Import-PSSession`. +This is required to get accurate parameters metadata from the remote session. + +```yaml +Type: PSSession +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UpdateInputOutput +Refreshes the Input and Output section to reflect the current state of the cmdlet. WARNING: this parameter will remove any manual additions to these sections. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Remove help files that no longer exists within sessions (for example if function was deleted) + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExcludeDontShow +Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### System.IO.FileInfo[] +This cmdlet returns a **FileInfo[]** object for updated files. + +## NOTES +The module for which you want to update the help should first be imported from the location containing the previous version of the help. +If this condition is not met, the parameter order will be alphabetical in the updated help, even if the parameter *AlphabeticParamsOrder* has not been used. + +## RELATED LINKS + +[Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) + +[Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) diff --git a/reference/ps-modules/PlatyPS/Update-MarkdownHelpModule.md b/reference/ps-modules/PlatyPS/Update-MarkdownHelpModule.md new file mode 100644 index 0000000..02791a2 --- /dev/null +++ b/reference/ps-modules/PlatyPS/Update-MarkdownHelpModule.md @@ -0,0 +1,263 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelpModule.md +schema: 2.0.0 +--- + +# Update-MarkdownHelpModule + +## SYNOPSIS +Update all files in a markdown help module folder. + +## SYNTAX + +``` +Update-MarkdownHelpModule [-Path] [[-Encoding] ] [-RefreshModulePage] + [-ModulePagePath ] [[-LogPath] ] [-LogAppend] [-AlphabeticParamsOrder] [-UseFullTypeName] + [-UpdateInputOutput] [-Force] [-Session ] [-ExcludeDontShow] [] +``` + +## DESCRIPTION +The **Update-MarkdownHelpModule** cmdlet updates existing help markdown files and creates markdown files for new cmdlets in a module. +This cmdlet combines functionality of the [Update-MarkdownHelp](Update-MarkdownHelp.md) and [New-MarkdownHelp](New-MarkdownHelp.md) cmdlets to perform a bulk update. + +## EXAMPLES + +### Example 1: Update a markdown help module +``` +PS C:\> Update-MarkdownHelpModule -Path ".\docs" + + Directory: D:\Working\PlatyPS\docs + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 5/22/2016 6:54 PM 1496 Get-HelpPreview.md +-a---- 5/22/2016 6:54 PM 3208 Get-MarkdownMetadata.md +-a---- 5/22/2016 6:54 PM 3059 New-ExternalHelp.md +-a---- 5/22/2016 6:54 PM 2702 New-ExternalHelpCab.md +-a---- 5/22/2016 6:54 PM 6234 New-MarkdownHelp.md +-a---- 5/22/2016 6:54 PM 2346 Update-MarkdownHelp.md +-a---- 5/22/2016 6:54 PM 1633 Update-MarkdownHelpModule.md +-a---- 5/22/2016 6:54 PM 1630 Update-MarkdownHelpSchema.md +``` + +This command updates all the files in the specified folder based on the cmdlets as loaded into your current session. +The command creates markdown help topics for any cmdlets that are not already included in the .\docs folder. + +## PARAMETERS + +### -Encoding +Specifies the character encoding for your markdown help files. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: UTF8 without BOM +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LogAppend +Indicates that this cmdlet appends information to the log instead overwriting it. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LogPath +Specifies a file path for log information. +The cmdlet writes the VERBOSE stream to the log. +If you specify the *Verbose* parameter, this cmdlet also writes that information to the console. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specifies an array of paths of markdown folders to update. +The folder must contain a module page from which this cmdlet can get the module name. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: True +``` + +### -RefreshModulePage +Update module page when updating the help module. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AlphabeticParamsOrder +Order parameters alphabetically by name in PARAMETERS section. +There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. +These parameters are common and hence have well-defined behavior. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Session +Provides support for remote commands. +Pass the session that you used to create the commands with `Import-PSSession`. +This is required to get accurate parameters metadata from the remote session. + +```yaml +Type: PSSession +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseFullTypeName +Indicates that the target document will use a full type name instead of a short name for parameters. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UpdateInputOutput +Refreshes the Input and Output sections to reflect the current state of the cmdlet. WARNING: this parameter will remove any manual additions to these sections. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ModulePagePath +When -RefreshModulePage is used by default it puts .md file in same location as all other docs. With this parameter you can specify new name/location providing better placement options. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Remove help files that no longer exists within sessions (for example if function was deleted) + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExcludeDontShow +Exclude the parameters marked with `DontShow` in the parameter attribute from the help content. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### System.IO.FileInfo[] +This cmdlet returns a **FileInfo[]** object for updated and new files. + +## NOTES +The module for which you want to update the help should first be imported from the location containing the previous version of the help. + If this condition is not met, the parameter order will be alphabetical in the updated help, even if the parameter *AlphabeticParamsOrder* has not been used. + +## RELATED LINKS + +[Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) + +[Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) diff --git a/reference/ps-modules/SecretManagement/About/about_Microsoft.PowerShell.SecretManagement.md b/reference/ps-modules/SecretManagement/About/about_Microsoft.PowerShell.SecretManagement.md new file mode 100644 index 0000000..1d7eeb1 --- /dev/null +++ b/reference/ps-modules/SecretManagement/About/about_Microsoft.PowerShell.SecretManagement.md @@ -0,0 +1,57 @@ +# Microsoft.PowerShell.SecretManagement +## about_Microsoft.PowerShell.SecretManagement + +``` +ABOUT TOPIC NOTE: +The first header of the about topic should be the topic name. +The second header contains the lookup name used by the help system. + +IE: +# Some Help Topic Name +## SomeHelpTopicFileName + +This will be transformed into the text file +as `about_SomeHelpTopicFileName`. +Do not include file extensions. +The second header should have no spaces. +``` + +# SHORT DESCRIPTION +{{ Short Description Placeholder }} + +``` +ABOUT TOPIC NOTE: +About topics can be no longer than 80 characters wide when rendered to text. +Any topics greater than 80 characters will be automatically wrapped. +The generated about topic will be encoded UTF-8. +``` + +# LONG DESCRIPTION +{{ Long Description Placeholder }} + +## Optional Subtopics +{{ Optional Subtopic Placeholder }} + +# EXAMPLES +{{ Code or descriptive examples of how to leverage the functions described. }} + +# NOTE +{{ Note Placeholder - Additional information that a user needs to know.}} + +# TROUBLESHOOTING NOTE +{{ Troubleshooting Placeholder - Warns users of bugs}} + +{{ Explains behavior that is likely to change with fixes }} + +# SEE ALSO +{{ See also placeholder }} + +{{ You can also list related articles, blogs, and video URLs. }} + +# KEYWORDS +{{List alternate names or titles for this topic that readers might use.}} + +- {{ Keyword Placeholder }} +- {{ Keyword Placeholder }} +- {{ Keyword Placeholder }} +- {{ Keyword Placeholder }} diff --git a/reference/ps-modules/SecretManagement/Get-Secret.md b/reference/ps-modules/SecretManagement/Get-Secret.md new file mode 100644 index 0000000..d080932 --- /dev/null +++ b/reference/ps-modules/SecretManagement/Get-Secret.md @@ -0,0 +1,136 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Get-Secret + +## SYNOPSIS +Finds and returns a secret by name from registered vaults. + +## SYNTAX + +### NameParameterSet (Default) +``` +Remove-Secret [-Name] [-Vault] [-WhatIf] [-Confirm] [] +``` + +### InfoParameterSet +``` +Remove-Secret [-InputObject] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This cmdlet finds and returns the first secret that matches the provided name. +If a vault name is specified, then only that vault will be searched. +Otherwise, all vaults are searched and the first found result is returned. +If a 'Default' vault is specified, then that vault is searched before any other registered vault. +Secrets that are string or SecureString types are returned as SecureString objects by default. +Unless the '-AsPlainText' parameter switch is used, in which case the secret is returned as a String type in plain text. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Get-Secret -Name Secret1 -Vault CredMan +System.Security.SecureString + +PS C:\> Get-Secret -Name Secret1 -Vault CredMan -AsPlainText +PlainTextSecretString +``` + +This example searches for a secret with the name 'Secret1', which is a String type secret. +The first time returns the secret as a SecureString object. +The second time uses the '-AsPlainText' and so the secret string is returned as a string object, and is displayed in plain text. + +### Example 2 +```powershell +PS C:\> Get-SecretInfo -Name Secret2 -Vault SecretStore | Get-Secret -AsPlainText +``` + +This example retrieves secret information for the secret named 'Secret2' and then pipe the result to `Get-Secret`. +The secret is then looked up in the SecretStore vault and returned as plain text. + +## PARAMETERS + +### -AsPlainText +Switch parameter that when used returns either a string or SecureString secret type as a String type (in plain text). +If the secret being retrieved is not of string or SecureString type, this switch parameter has no effect. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject +SecretInformation object that describes a vault secret. + +```yaml +Type: SecretInformation +Parameter Sets: InfoParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name +Name of the secret to be retrieved. +Wild card characters are not allowed. + +```yaml +Type: String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Vault +Optional name of the registered vault to retrieve the secret from. +If no vault name is specified, then all registered vaults are searched. + +```yaml +Type: String +Parameter Sets: NameParameterSet +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +### Microsoft.PowerShell.SecretManagement.SecretInformation + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Get-SecretInfo.md b/reference/ps-modules/SecretManagement/Get-SecretInfo.md new file mode 100644 index 0000000..083c5bb --- /dev/null +++ b/reference/ps-modules/SecretManagement/Get-SecretInfo.md @@ -0,0 +1,94 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Get-SecretInfo + +## SYNOPSIS +Finds and returns secret metadata information of one or more secrets. + +## SYNTAX + +``` +Get-SecretInfo [[-Name] ] [[-Vault] ] [] +``` + +## DESCRIPTION +This cmdlet finds and returns secret metadata for secrets with names that match the provided 'Name'. +The 'Name' parameter argument can include wildcards for the search. +If no 'Name' parameter argument is provided then metadata for all secrets is returned. +The search is performed over all registered vaults, unless a specific vault name is specified. +Secret metadata consists of the secret name, secret type, and vault name. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Get-SecretInfo -Name * + +Name Type VaultName +---- ---- --------- +Secret1 String LocalStore +Secret2 ByteArray LocalStore +Secret3 SecureString LocalStore +Secret4 PSCredential LocalStore +Secret5 Hashtable LocalStore +Secret6 ByteArray CredMan +``` + +This example runs the command with the 'Name' parameter argument being a single wildcard character. +So all metadata for all stored secrets is returned. +There are two registered vaults, LocalStore and CredMan. +There are six secrets metadata information returned over the two vaults. + +## PARAMETERS + +### -Name +This parameter takes a String argument, including wildcard characters. +It is used to filter the search results that match on secret names the provided name pattern. +If no 'Name' parameter argument is provided, then all stored secret metadata is returned. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` + +### -Vault +Optional parameter which takes a String argument that specifies a single vault to search. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.SecretManagement.SecretInformation + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Get-SecretVault.md b/reference/ps-modules/SecretManagement/Get-SecretVault.md new file mode 100644 index 0000000..2ffff44 --- /dev/null +++ b/reference/ps-modules/SecretManagement/Get-SecretVault.md @@ -0,0 +1,71 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Get-SecretVault + +## SYNOPSIS +Finds and returns registered vault information. + +## SYNTAX + +``` +Get-SecretVault [[-Name] ] [] +``` + +## DESCRIPTION +This cmdlet finds and returns information of registered vaults. +It takes an array of vault name strings, which can contain wildcard characters. +If no 'Name' parameter is specified, all registered vault information is returned. +The registered vault information includes the vault name, vault implementing module name, and optional default parameters. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True +``` + +This example runs the command without any parameter arguments, and so returns information on all registered vaults. +The 'LocalStore' vault is shown to be set as the default vault. + +## PARAMETERS + +### -Name +This parameter takes a String argument, including wildcard characters. +It is used to filter the search results on vault names that match the provided name pattern. + +```yaml +Type: string[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.SecretManagement.SecretVaultInfo + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Register-SecretVault.md b/reference/ps-modules/SecretManagement/Register-SecretVault.md new file mode 100644 index 0000000..d1b8aa4 --- /dev/null +++ b/reference/ps-modules/SecretManagement/Register-SecretVault.md @@ -0,0 +1,197 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Register-SecretVault + +## SYNOPSIS +Registers a SecretManagement extension vault module for the current user. + +## SYNTAX + +``` +Register-SecretVault [-ModuleName] [[-Name] ] [-VaultParameters ] [-DefaultVault] +[-AllowClobber] [-PassThru] [-Description ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This cmdlet adds a provided SecretManagement extension vault module to the current user vault registry. +An extension vault module is a PowerShell module that conforms to the required extension vault format. +This cmdlet will first verify that the provided module meets conformance requirements, and then add it to the extension vault registry. +Extension vaults are registered to the current user and do not affect other user vault registrations. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Register-SecretVault -Name LocalStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True +``` + +This example registers the Microsoft.PowerShell.SecretStore extension vault module for the current user. +The 'Microsoft.PowerShell.SecretStore' is installed in a known PowerShell module path, so just the module name is needed. +It uses the 'DefaultVault' parameter switch to make it the default module for the user. +The 'Get-SecretVault' command is run next to list all registered vaults for the user, and verifies the vault was registered and set as the default vault. + +## PARAMETERS + +### -AllowClobber +When used this parameter will overwrite an existing registered extension vault with the same name. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DefaultVault +This parameter switch makes the new extension vault the default vault for the current user. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Description +This parameter takes a description string that is included in the vault registry information. + +```yaml +Type: string +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ModuleName +Name of the PowerShell module that implements the extension vault. +It can be a simple name, in which case PowerShell will search for it in its known module paths. +Alternatively, a pathname can be provided and PowerShell will look in the specific path for the module. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +Name of the extension vault to be registered. +If no name is provide, the module name will be used. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru +When used this parameter will return the SecretVaultInfo object for the successfully registered extension vault. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VaultParameters +This takes a hashtable object that contains optional parameter name-value pairs needed by the extension vault. +These optional parameters are provided to the extension vault when invoked. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Remove-Secret.md b/reference/ps-modules/SecretManagement/Remove-Secret.md new file mode 100644 index 0000000..2d922d7 --- /dev/null +++ b/reference/ps-modules/SecretManagement/Remove-Secret.md @@ -0,0 +1,111 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Remove-Secret + +## SYNOPSIS +Removes a secret from a specified registered extension vault. + +## SYNTAX + +### NameParameterSet (Default) +``` +Remove-Secret [-Name] [-Vault] [-WhatIf] [-Confirm] [] +``` + +### InfoParameterSet +``` +Remove-Secret [-InputObject] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This cmdlet will remove a secret by name from a registered extension vault. +Both the secret name and extension vault name must be provided. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Remove-Secret -Name secretTest -Vault CredMan +PS C:\> Get-Secret -Name secretTest -Vault CredMan +Get-Secret: The secret secretTest was not found. +``` + +This example runs the command to remove the secret 'secretTest' from the CredMan vault. +The 'Get-Secret' command is next run to verify the secret no longer exists in the vault. + +### Example 2 +```powershell +PS C:\> Get-SecretInfo -Name Secret2 -Vault CredMan | Remove-Secret +PS C:\> Get-Secret -Name Secret2 -Vault CredMan +Get-Secret: The secret Secret2 was not found. +``` + +This example first obtains secret information for the 'Secret2' secret and pipes the results to this command. +`Remove-Secret` then removes the secret from the vault using the piped in secret information. + +## PARAMETERS + +### -InputObject +SecretInformation object that describes a vault secret. + +```yaml +Type: SecretInformation +Parameter Sets: InfoParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name +Name of the secret to remove. + +```yaml +Type: String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Vault +Name of the vault from which the secret is to be removed. + +```yaml +Type: String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +### Microsoft.PowerShell.SecretManagement.SecretInformation + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Set-Secret.md b/reference/ps-modules/SecretManagement/Set-Secret.md new file mode 100644 index 0000000..10b029a --- /dev/null +++ b/reference/ps-modules/SecretManagement/Set-Secret.md @@ -0,0 +1,232 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Set-Secret + +## SYNOPSIS +Adds a secret to a SecretManagement registered vault. + +## SYNTAX + +### SecureStringParameterSet (Default) +``` +Set-Secret [-Name] [-SecureStringSecret] [[-Vault] ] +[[-Metadata] ] [-NoClobber] [-WhatIf] [-Confirm] [] +``` + +### ObjectParameterSet +``` +Set-Secret [-Name] [-Secret] [[-Vault] ] [[-Metadata] ] +[-NoClobber] [-WhatIf] [-Confirm] [] +``` + +### SecretInfoParameterSet +``` +Set-Secret [-SecretInfo] -Vault [-NoClobber] [-WhatIf] [-Confirm] +[] +``` + +## DESCRIPTION +This cmdlet adds a secret value by name to SecretManagement. +If no vault name is specified, then the secret will be added to the default vault. +If an existing secret by the same name exists, it will be overwritten with the new value unless the 'NoClobber' parameter switch is used. +Additional data can be included with the secret through the `-Metadata` parameter, if supported by the extension vault. +If the extension vault does not support metadata then an error will be generated and the operation will fail. +Metadata is not required to be stored securely, and should not contain sensitive information. + +The secret value must be one of five supported types: + +- byte[] +- String +- SecureString +- PSCredential +- Hashtable + +The default parameter set takes a SecureString object. +So if the command is run without specifying the secret value, the user will be safely prompted to enter a SecureString which cannot be seen on the console. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Set-Secret -Name Secret1 -Secret "SecretValue" +PS C:\> Get-Secret -Name Secret1 +System.Security.SecureString +``` + +This example adds a secret named 'Secret1' with a plain text value of 'SecretValue'. +Since no vault name was specified, the secret is added to the current default vault. +Next, the 'Get-Secret' command is run to verify the added secret. + +### Example 2 +```powershell +PS C:\> Set-Secret -Name Secret2 -Vault LocalStore + +cmdlet Set-Secret at command pipeline position 1 +Supply values for the following parameters: +SecureStringSecret: *********** + +PS C:\> Get-Secret -Name Secret2 +System.Security.SecureString +``` + +This example adds a secret named 'Secret2' to the LocalStore vault. +Since no secret value was provided, the user is prompted for a SecureString value. +The console hides the string value as it is typed. +Next, the 'Get-Secret' command is run to verify the secret was added. + +### Example 3 +```powershell +PS C:\> Set-Secret -Name TargetSecret -Secret $targetToken -Vault LocalStore -Metadata @{ Expiration = ([datetime]::new(2022, 5, 1)) } +PS C:\> Get-SecretInfo -Name TargetSecret | Select-Object Name,Metadata + +Name Metadata +---- -------- +TargetSecret {[Expiration, 5/1/2022 12:00:00 AM]} +``` + +This example adds a secret named 'TargetSecret' to the LocalStore vault, along with extra metadata indicating the secret expiration date. +The metadata is retrieved using the `Get-SecretInfo` cmdlet. + +### Example 4 +```powershell +PS C:\> Set-Secret -Name PublishSecret -Secret $targetToken -Vault LocalStore2 -Metadata @{ Expiration = ([datetime]::new(2022, 5, 1)) } +Set-Secret: Cannot store secret PublishSecret. Vault LocalStore2 does not support secret metadata. +``` + +This example adds a secret named 'PublishSecret' to the LocalStore2 vault, along with extra metadata. +However, vault LocalStore2 does not support secret metadata and the operation fails with error. + +## PARAMETERS + +### -Metadata +Hashtable containing Name/Value pair that are stored in the vault. +The specified extension vault may not support secret metadata, in which case the `Set-Secret` operation will fail. +The metadata Name/Value value type must be one of the following: +- string +- int +- DateTime + +```yaml +Type: Hashtable +Parameter Sets: SecureStringParameterSet,ObjectParameterSet +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +Name of secret to add. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoClobber +When used this parameter will cause an error if the secret name already exists. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Secret +A secret value to be added. +The object type must be one of the supported types. + +```yaml +Type: Object +Parameter Sets: ObjectParameterSet +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -SecretInfo +A SecretInformation object describing a stored secret returned by `Get-SecretInfo`. +This allows moving secrets from one extension vault to another. + +```yaml +Type: SecretInformation +Parameter Sets: SecretInfoParameterSet +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -SecureStringSecret +A secret SecretString object to be added. + +```yaml +Type: SecureString +Parameter Sets: SecureStringParameterSet +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Vault +Optional name of vault to which the secret is added. +If omitted, the secret will be added to the default vault. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Object + +### System.Security.SecureString + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Set-SecretInfo.md b/reference/ps-modules/SecretManagement/Set-SecretInfo.md new file mode 100644 index 0000000..be7e79e --- /dev/null +++ b/reference/ps-modules/SecretManagement/Set-SecretInfo.md @@ -0,0 +1,123 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Set-Secret + +## SYNOPSIS +Adds or replaces additional secret metadata to a secret currently stored in a vault. + +## SYNTAX + +``` +Set-SecretInfo [-Name] [-Metadata] [[-Vault] ] [-WhatIf] [-Confirm] +[] +``` + +## DESCRIPTION +This cmdlet adds additional secret metadata to a currently store secret. +Metadata support is an optional feature for an extension vault. +An error will be thrown if a vault does not support secret metadata. + +Metadata is a Hashtable object containing Name/Value pairs. +The value type is restricted to the following: + +- string +- int +- DateTime + +Metadata is not stored securely in a vault. +Metadata should not contain sensitive information. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Set-SecretInfo -Name Secret1 -Vault Vault1 -Metadata @{ Expiration = ([datetime]::new(2022, 5, 1)) } +PS C:\> Get-SecretInfo -Name Secret1 -Vault Vault1 | Select-Object Name,Metadata + +Name Metadata +---- -------- +Secret1 {[Expiration, 5/1/2022 12:00:00 AM]} +``` + +This example adds metadata to the 'Secret1' secret stored in 'Vault1' vault. +The metadata is then retrieved for 'Secret1' using the `Get-SecretInfo` command. + +### Example 2 +```powershell +PS C:\> Set-SecretInfo -Name Secret2 -Vault Vault2 -Metadata @{ Expiration = ([datetime]::new(2022, 5, 1)) } +Set-SecretInfo: Cannot set secret metadata Secret2. Vault Vault2 does not support secret metadata. +``` + +This example adds metadata to the 'Secret2' secret stored in 'Vault2' vault. +However, Vault2 does not support metadata and an error is generated. + +## PARAMETERS + +### -Metadata +Hashtable containing Name/Value pair that are stored in the vault. +The specified extension vault may not support secret metadata, in which case the operation will fail. +The metadata Name/Value value type must be one of the following: +- string +- int +- DateTime + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name +Name of secret for which the metadata is added + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Vault +Optional name of vault to which the secret is added. +If omitted, the secret will be added to the default vault. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Collections.Hashtable + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Set-SecretVaultDefault.md b/reference/ps-modules/SecretManagement/Set-SecretVaultDefault.md new file mode 100644 index 0000000..e0484c0 --- /dev/null +++ b/reference/ps-modules/SecretManagement/Set-SecretVaultDefault.md @@ -0,0 +1,127 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Set-SecretVaultDefault + +## SYNOPSIS +Sets the provided vault name as the default vault for the current user. + +## SYNTAX + +### NameParameterSet (Default) +``` +Set-SecretVaultDefault [-Name] [-WhatIf] [-Confirm] [] +``` + +### SecretVaultParameterSet +``` +Set-SecretVaultDefault [-SecretVault] [-WhatIf] [-Confirm] [] +``` + +### ClearParameterSet +``` +Set-SecretVaultDefault [-ClearDefault] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This cmdlet updates the vault registry to indicate the provided vault name as the default vault. +Only one registered vault can be the default vault. +If this cmdlet is run without specifying the 'Name' parameter, then no registered vault is the default vault. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True + +PS C:\> Set-SecretVaultDefault -Name CredMan +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore True +LocalStore Microsoft.PowerShell.SecretStore False + +PS C:\> Set-SecretVaultDefault +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore False +``` + +This cmdlet first runs 'Get-SecretVault' command to get all registered vault information, and shows that the 'LocalStore' is currently the default vault for the user. +Next, the 'Set-SecretVaultDefault' command is run to make the 'CredMan' vault the default vault. +The 'Get-SecretVault' command is run a second time to verify 'CredMan' vault is now default, and 'LocalStore' vault is no longer default. +Finally, the 'Set-SecretVaultDefault' command is run with no 'Name' parameter, to remove the default designation from any registered vault. +The 'Get-SecretVault' is run once again to verify there is no default vault. + +## PARAMETERS + +### -ClearDefault +Makes no registered vault the default vault. + +```yaml +Type: SwitchParameter +Parameter Sets: ClearParameterSet +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +Name of registered vault to be made the default vault. + +```yaml +Type: String +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SecretVault +A SecretVaultInfo object that represents the registered vault to be made the default vault. + +```yaml +Type: SecretVaultInfo +Parameter Sets: SecretVaultParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Test-SecretVault.md b/reference/ps-modules/SecretManagement/Test-SecretVault.md new file mode 100644 index 0000000..6fd96e6 --- /dev/null +++ b/reference/ps-modules/SecretManagement/Test-SecretVault.md @@ -0,0 +1,67 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Test-SecretVault + +## SYNOPSIS +Runs an extension vault self test. + +## SYNTAX + +``` +Test-SecretVault [[-Name] ] [] +``` + +## DESCRIPTION +This cmdlet runs an extension vault self test, by running the internal vault 'Test-SecretVault' command. +It will return 'True' if all tests succeeded, and 'False' otherwise. +Information on failing tests will be written to the error stream as error records. +For more information during the test run use the `-Verbose` command switch. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Test-SecretVault -Name CredMan -Verbose +VERBOSE: Invoking command Test-SecretVault on module Microsoft.PowerShell.CredManStore.Extension +VERBOSE: Vault CredMan succeeded validation test +True +``` + +This example runs self tests on the 'CredMan' extension vault. +All tests succeeded so no errors are written and 'True' is returned. + +## PARAMETERS + +### -Vault +Name of vault to run self tests on. + +```yaml +Type: string[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Boolean +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretManagement/Unregister-SecretVault.md b/reference/ps-modules/SecretManagement/Unregister-SecretVault.md new file mode 100644 index 0000000..00738c0 --- /dev/null +++ b/reference/ps-modules/SecretManagement/Unregister-SecretVault.md @@ -0,0 +1,155 @@ +--- +external help file: Microsoft.PowerShell.SecretManagement.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretManagement +online version: +schema: 2.0.0 +--- + +# Unregister-SecretVault + +## SYNOPSIS +Un-registers an extension vault from SecretManagement for the current user. + +## SYNTAX + +### NameParameterSet +``` +Unregister-SecretVault [-Name] [-WhatIf] [-Confirm] [] +``` + +### SecretVaultParameterSet +``` +Unregister-SecretVault [-SecretVault] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This cmdlet un-registers the specified extension vault. +Once un-registered, the vault is no longer available to SecretManagement, for the current user. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +LocalStore Microsoft.PowerShell.SecretStore True + +PS C:\> Unregister-SecretVault LocalStore +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False + +PS C:\> Get-Secret -Name Secret5 +Get-Secret: The secret Secret5 was not found. + +PS C:\> Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault +PS C:\> Get-SecretVault + +VaultName ModuleName IsDefaultVault +--------- ---------- -------------- +CredMan Microsoft.PowerShell.CredManStore False +SecretStore Microsoft.PowerShell.SecretStore True + +PS C:\> Get-Secret -Name Secret5 +System.Security.SecureString +``` + +In this example, 'Get-SecretVault' command is run to see what vaults are registered for the current user. +Next, the 'LocalStore' vault is un-registered. +'Get-SecretVault' command is run again to verify the vault no longer appears in the registry. +An attempt is made to retrieve 'Secret5', but it is not found since its vault was un-registered. +The vault is re-registered, under a different name, and set to be the default vault. +'Get-SecretVault' is run again to verify the newly registered vault. +Finally, the 'Secret5' secret is retrieved successfully from the new default vault. + +### Example 2 +```powershell +PS C:\> Get-SecretVault | Unregister-SecretVault +PS C:\> Get-SecretVault +PS C:\> +``` + +In this example, 'Get-SecretVault' output is piped to this 'Unregister-SecretVault' cmdlet to un-register all extension vaults for the current user. +Next, 'Get-SecretVault' is run again to show that no vaults are registered. + +## PARAMETERS + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +Name of the vault to un-register. + +```yaml +Type: string[] +Parameter Sets: NameParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` + +### -SecretVault +SecretVaultInfo object, returned by 'Get-SecretVault' cmdlet. +This can alternately be used to indicate a vault to be un-registered. + +```yaml +Type: SecretVaultInfo +Parameter Sets: SecretVaultParameterSet +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.SecretManagement.SecretVaultInfo + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretStore/About/about_Microsoft.PowerShell.SecretStore.md b/reference/ps-modules/SecretStore/About/about_Microsoft.PowerShell.SecretStore.md new file mode 100644 index 0000000..c63885c --- /dev/null +++ b/reference/ps-modules/SecretStore/About/about_Microsoft.PowerShell.SecretStore.md @@ -0,0 +1,43 @@ +# Secret Management local store extension vault module +## Microsoft.PowerShell.SecretStore + +# SHORT DESCRIPTION +This is an extension module for the Microsoft.PowerShell.SecretManagement module. +It stores secrets on the local machine in the current user account context. + +``` +ABOUT TOPIC NOTE: +About topics can be no longer than 80 characters wide when rendered to text. +Any topics greater than 80 characters will be automatically wrapped. +The generated about topic will be encoded UTF-8. +``` + +# LONG DESCRIPTION +{{ Long Description Placeholder }} + +## Optional Subtopics +{{ Optional Subtopic Placeholder }} + +# EXAMPLES +{{ Code or descriptive examples of how to leverage the functions described. }} + +# NOTE +{{ Note Placeholder - Additional information that a user needs to know.}} + +# TROUBLESHOOTING NOTE +{{ Troubleshooting Placeholder - Warns users of bugs}} + +{{ Explains behavior that is likely to change with fixes }} + +# SEE ALSO +{{ See also placeholder }} + +{{ You can also list related articles, blogs, and video URLs. }} + +# KEYWORDS +{{List alternate names or titles for this topic that readers might use.}} + +- {{ Keyword Placeholder }} +- {{ Keyword Placeholder }} +- {{ Keyword Placeholder }} +- {{ Keyword Placeholder }} diff --git a/reference/ps-modules/SecretStore/Get-SecretStoreConfiguration.md b/reference/ps-modules/SecretStore/Get-SecretStoreConfiguration.md new file mode 100644 index 0000000..679ab3a --- /dev/null +++ b/reference/ps-modules/SecretStore/Get-SecretStoreConfiguration.md @@ -0,0 +1,65 @@ +--- +external help file: Microsoft.PowerShell.SecretStore.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretStore +online version: +schema: 2.0.0 +--- + +# Get-SecretStoreConfiguration + +## SYNOPSIS +Returns SecretStore configuration information. + +## SYNTAX + +``` +Get-SecretStoreConfiguration [] +``` + +## DESCRIPTION +This cmdlet reads the SecretStore configuration file and writes configuration information to the pipeline. +Configuration information includes: + +- Scope + +- Authentication + +- PasswordTimeout (in seconds) + +- Interaction + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Get-SecretStoreConfiguration + + Scope Authentication PasswordTimeout Interaction + ----- -------------- --------------- ----------- +CurrentUser Password 900 Prompt +``` + +This example runs the command from a command shell prompt and displays four SecretStore configuration properties: +Scope : 'CurrentUser'. +Authentication : A password is required to access the SecretStore. +PasswordTimeout : The session password timeout time is 15 minutes. +Interaction : The user will be prompted for a password if the command is run in an interactive session. + +## PARAMETERS + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.SecretStore.SecureStoreConfig + +## NOTES + +'AllUsers' scope is currently not supported. Configuration scope is always 'CurrentUser'. + +## RELATED LINKS diff --git a/reference/ps-modules/SecretStore/Microsoft.PowerShell.SecretStore.md b/reference/ps-modules/SecretStore/Microsoft.PowerShell.SecretStore.md new file mode 100644 index 0000000..9ca48fc --- /dev/null +++ b/reference/ps-modules/SecretStore/Microsoft.PowerShell.SecretStore.md @@ -0,0 +1,27 @@ +--- +Module Name: Microsoft.PowerShell.SecretStore +Module Guid: 6b983e67-c297-431a-916c-f4ce24dd7bac +Download Help Link: {{ Update Download Link }} +Help Version: {{ Please enter version of help manually (X.X.X.X) format }} +Locale: en-US +--- + +# Microsoft.PowerShell.SecretStore Module +## Description +Local secure store extension vault for Microsoft.PowerShell.SecretManagement module. + +## Microsoft.PowerShell.SecretStore Cmdlets +### [Get-SecretStoreConfiguration](Get-SecretStoreConfiguration.md) +Writes the SecretStore configuration information. + +### [Reset-SecretStore](Reset-SecretStore.md) +Resets the SecretStore by deleting all current secret data, and setting the configuration properties to default values. + +### [Set-SecretStoreConfiguration](Set-SecretStoreConfiguration.md) +Applies configuration settings to the SecretStore. + +### [Unlock-SecretStore](Unlock-SecretStore.md) +Unlocks the SecretStore with the provided password. + +### [Set-SecretStorePassword](Set-SecretStorePassword.md) +Replaces the current SecretStore password with a new password. diff --git a/reference/ps-modules/SecretStore/Reset-SecretStore.md b/reference/ps-modules/SecretStore/Reset-SecretStore.md new file mode 100644 index 0000000..fba7d8d --- /dev/null +++ b/reference/ps-modules/SecretStore/Reset-SecretStore.md @@ -0,0 +1,213 @@ +--- +external help file: Microsoft.PowerShell.SecretStore.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretStore +online version: +schema: 2.0.0 +--- + +# Reset-SecretStore + +## SYNOPSIS +Resets the SecretStore by deleting all secret data and configuring the store with default options. + +## SYNTAX + +``` +Reset-SecretStore [-Scope ] [-Authentication ] [-PasswordTimeout ] + [-Interaction ] [-Force] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This cmdlet completely resets the SecretStore by deleting all secret data it may contain, and resetting configuration options to their default values. +It is intended to be used only if a required password is lost, or data files become corrupted so that SecretStore no longer functions and secret data cannot be accessed. +Default configuration options can be overridden by specifying individual command configuration option parameters. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Reset-SecretStore -PassThru +WARNING: !!This operation will completely remove all SecretStore module secrets and reset configuration settings to default values!! + +Reset SecretStore +Are you sure you want to erase all secrets in SecretStore and reset configuration settings to default? +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): Y +Creating a new Microsoft.PowerShell.SecretStore vault. A password is required by the current store configuration. +Enter password: +******** +Enter password again for verification: +******** + + Scope Authentication PasswordTimeout Interaction + ----- -------------- --------------- ----------- +CurrentUser Password 900 Prompt +``` + +This example resets the SecretStore for the current user, by deleting all secrets and forcing configuration settings to default values. +The user is warned of the consequences of this action and prompted to confirm before continuing. + +## PARAMETERS + +### -Authentication +Configuration option to set authentication for store access. +Configuration options are 'Password' or 'None'. +When 'Password' is selected, SecretStore is configured to require a password for accessing secrets. +Default authentication is 'Password', as this provides the strongest protection of secret data. + +```yaml +Type: Authenticate +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: Password +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +When used, the user will not be asked to confirm and the SecretStore will be reset without prompting. +Default value is false, and user will be asked to confirm the operation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Password +Sets the provided Password to the newly reset store. +If the reset store is not configured for password authentication, an error will be returned. + +```yaml +Type: SecureString +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru +Writes the newly reset store configuration object (SecureStorConfig) to the pipeline. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PasswordTimeout +Configuration option that provides the session password timeout in seconds. +Takes an argument whose value determines the session password timeout in seconds. +When the timeout value is reached, the current password value is invalidated for the session. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 900 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Scope +Configuration option that determines SecretStore operation scope. +Currently only 'CurrentUser' scope is supported. + +```yaml +Type: SecureStoreScope +Parameter Sets: (All) +Aliases: +Accepted values: CurrentUser, AllUsers + +Required: False +Position: Named +Default value: CurrentUser +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Interaction +Configuration option to allow or suppress user prompting. +Configuration options are 'Prompt' or 'None'. +When 'None' is selected, no prompt will be presented in an interactive session to provide a session password. +Default value is 'Prompt', and users will be prompted for password when needed. +When 'None' is selected and a session password is required, a Microsoft.PowerShell.SecretStore.PasswordRequiredException error is thrown. + +```yaml +Type: Interaction +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: Prompt +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.SecretStore.SecureStoreConfig + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretStore/Set-SecretStoreConfiguration.md b/reference/ps-modules/SecretStore/Set-SecretStoreConfiguration.md new file mode 100644 index 0000000..427142c --- /dev/null +++ b/reference/ps-modules/SecretStore/Set-SecretStoreConfiguration.md @@ -0,0 +1,211 @@ +--- +external help file: Microsoft.PowerShell.SecretStore.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretStore +online version: +schema: 2.0.0 +--- + +# Set-SecretStoreConfiguration + +## SYNOPSIS +Sets SecretStore configuration properties. + +## SYNTAX + +### ParameterSet (Default) +``` +Set-SecretStoreConfiguration [-Scope ] [-Authentication ] + [-PasswordTimeout ] [-Interaction ] [-Force] [-WhatIf] [-Confirm] [] +``` + +### DefaultParameterSet +``` +Set-SecretStoreConfiguration [-Default] [-Force] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This cmdlet takes individual parameter arguments that determine SecretStore configuration. +Or the '-Default' parameter can be used to restore SecretStore configuration to default settings. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Set-SecretStoreConfiguration -Default + +Confirm +Are you sure you want to perform this action? +Performing the operation "Changes local store configuration" on target "SecretStore module local store". +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): Y + + Scope Authentication PasswordTimeout Interaction + ----- -------------- --------------- ----------- +CurrentUser Password 900 Prompt +``` + +This example uses the command to restore the SecretStore configuration settings to their default values. + +## PARAMETERS + +### -Authentication +Configuration option to set authentication for store access. +Configuration options are 'Password' or 'None'. +When 'Password' is selected, SecretStore is configured to require a password for accessing secrets. +Default authentication is 'Password', as this provides the strongest protection of secret data. + +```yaml +Type: Authenticate +Parameter Sets: ParameterSet +Aliases: + +Required: False +Position: Named +Default value: Password +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Default +This parameter switch sets SecretStore configuration to its default settings. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParameterSet +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +When used, the user will not be asked to confirm and the SecretStore will be reset without prompting. +Default value is false, and user will be asked to confirm the operation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru +When used, will write the current SecretStore configuration to the pipeline. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PasswordTimeout +Configuration option that provides the session password timeout in seconds. +Takes an argument whose value determines the session password timeout in seconds. +When the timeout value is reached, the current password value is invalidated for the session. + +```yaml +Type: Int32 +Parameter Sets: ParameterSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Scope +Configuration option that determines SecretStore operation scope. +Currently only 'CurrentUser' scope is supported. + +```yaml +Type: SecureStoreScope +Parameter Sets: ParameterSet +Aliases: +Accepted values: CurrentUser, AllUsers + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Interaction +Configuration option to allow or suppress user prompting. +Configuration options are 'Prompt' or 'None'. +When 'None' is selected, no prompt will be presented in an interactive session to provide a session password. +Default value is 'Prompt', and users will be prompted for password when needed. +When 'None' is selected and a session password is required, a Microsoft.PowerShell.SecretStore.PasswordRequiredException error is thrown. + +```yaml +Type: Interaction +Parameter Sets: ParameterSet +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.SecretStore.SecureStoreConfig + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretStore/Set-SecretStorePassword.md b/reference/ps-modules/SecretStore/Set-SecretStorePassword.md new file mode 100644 index 0000000..7737414 --- /dev/null +++ b/reference/ps-modules/SecretStore/Set-SecretStorePassword.md @@ -0,0 +1,94 @@ +--- +external help file: Microsoft.PowerShell.SecretStore.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretStore +online version: +schema: 2.0.0 +--- + +# Set-SecretStorePassword + +## SYNOPSIS +Replaces the current SecretStore password with a new one. + +## SYNTAX + +``` +Set-SecretStorePassword [] +``` + +## DESCRIPTION +This cmdlet updates the password for SecretStore. +It takes no parameters and prompts the user for both the old and new passwords. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Set-SecretStorePassword +Old password +Enter password: +******* +New password +Enter password: +******* +Enter password again for verification: +******* +``` + +This example runs the command with no parameter arguments. +The user is first prompted for the old password. +And then prompted for the new password twice for verification. + +### Example 2 +```powershell +PS C:\> Set-SecretStorePassword -NewPassword $newPassword -Password $oldPassword +``` + +This example runs the command passing in both the current store password and the new +password to be set. + +## PARAMETERS + +### -NewPassword +New password to be applied to the store. + +```yaml +Type: SecureString +Parameter Sets: ParameterSet +Aliases: + +Required: True +Position: Named +Default value: +Accept pipeline input: True +Accept wildcard characters: False +``` + +### -Password +Existing password needed to unlock the store. +This can be ignored if the store doesn't currently use a password. + +```yaml +Type: SecureString +Parameter Sets: ParameterSet +Aliases: + +Required: False +Position: Named +Default value: +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/reference/ps-modules/SecretStore/Unlock-SecretStore.md b/reference/ps-modules/SecretStore/Unlock-SecretStore.md new file mode 100644 index 0000000..4e1662a --- /dev/null +++ b/reference/ps-modules/SecretStore/Unlock-SecretStore.md @@ -0,0 +1,92 @@ +--- +external help file: Microsoft.PowerShell.SecretStore.dll-Help.xml +Module Name: Microsoft.PowerShell.SecretStore +online version: +schema: 2.0.0 +--- + +# Unlock-SecretStore + +## SYNOPSIS +Unlocks SecretStore with the provided password. + +## SYNTAX + +``` +Unlock-SecretStore -Password [-PasswordTimeout ] [] +``` + +## DESCRIPTION +This cmdlet unlocks SecretStore for the current user with the provided password. +It can be used to unlock SecretStore when the configuration requires a password and the prompt configuration option is disabled. +The provided password will be applied to the current session, and will become invalid after the 'PasswordTimeout' time elapses. +If no password is provided by parameter argument, the user will be safely prompted for the password. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Get-Secret secret1 -Vault LocalStore +Get-Secret: A valid password is required to access the Microsoft.PowerShell.SecretStore vault. +Get-Secret: The secret secret1 was not found. + +PS C:\> Unlock-SecretStore + +cmdlet Unlock-SecretStore at command pipeline position 1 +Supply values for the following parameters: +SecureStringPassword: ******* + +PS C:\> Get-Secret secret1 -Vault LocalStore +System.Security.SecureString +``` + +In this example, the SecretManagement 'Get-Secret' command fails to retrieve secret1 because the SecretStore vault is locked. +The 'Unlock-SecretStore' command is run to unlock the vault. +No password parameter argument was provided to the 'Unlock-SecretStore' command, so the user is prompted for the password. +Running 'Get-Secret' again now works and returns the secret as a SecureString object. + +## PARAMETERS + +### -Password +This parameter takes the password argument as a SecureString object. + +```yaml +Type: SecureString +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -PasswordTimeout +This parameter takes a password timeout argument in seconds, and overrides the configuration password timeout value. +The password timeout value remains in effect for the session until changed. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Security.SecureString + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/samples-v1.0/Az.Compute/Az.Compute.md b/samples-v1.0/Az.Compute/Az.Compute.md deleted file mode 100644 index 715a86e..0000000 --- a/samples-v1.0/Az.Compute/Az.Compute.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -Module Name: Az.Compute -Module Guid: 0a83c907-1ffb-4d87-a492-c65ac7d7ed37 -Download Help Link: https://docs.microsoft.com/en-us/powershell/module/az.compute -Help Version: 3.5.0.0 -Locale: en-US -content_git_url: https://github.com/Azure/azure-powershell/blob/master/src/Compute/Compute/help/Az.Compute.md -original_content_git_url: https://github.com/Azure/azure-powershell/blob/master/src/Compute/Compute/help/Az.Compute.md ---- - -# Az.Compute Module -## Description -This topic displays the help topics for the Azure Compute Cmdlets. - -## Az.Compute Cmdlets diff --git a/samples-v1.0/Az.Compute/Get-AzDisk.md b/samples-v1.0/Az.Compute/Get-AzDisk.md deleted file mode 100644 index f00aa88..0000000 --- a/samples-v1.0/Az.Compute/Get-AzDisk.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -external help file: Microsoft.Azure.PowerShell.Cmdlets.Compute.dll-Help.xml -Module Name: Az.Compute -online version: https://docs.microsoft.com/en-us/powershell/module/az.compute/get-azdisk -schema: 2.0.0 -content_git_url: https://github.com/Azure/azure-powershell/blob/master/src/Compute/Compute/help/Get-AzDisk.md -original_content_git_url: https://github.com/Azure/azure-powershell/blob/master/src/Compute/Compute/help/Get-AzDisk.md ---- - -# Get-AzDisk - -## SYNOPSIS -Gets the properties of a Managed disk. - -## SYNTAX - -``` -Get-AzDisk [[-ResourceGroupName] ] [[-DiskName] ] [-DefaultProfile ] - [] -``` - -## DESCRIPTION -The **Get-AzDisk** cmdlet gets the properties of a Managed disk. - -## EXAMPLES - -### Example 1 -``` -PS C:\> Get-AzDisk -ResourceGroupName 'ResourceGroup01' -DiskName 'Disk01' - -ResourceGroupName : ResourceGroup01 -ManagedBy : -Sku : Microsoft.Azure.Management.Compute.Models.DiskSku -Zones : -TimeCreated : 6/29/2018 4:26:27 PM -OsType : Windows -CreationData : Microsoft.Azure.Management.Compute.Models.CreationData -DiskSizeGB : 127 -EncryptionSettings : -ProvisioningState : Succeeded -DiskIOPSReadWrite : 500 -DiskMBpsReadWrite : 100 -Id : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ResourceGroup01/providers/Microsoft.Compu - te/disks/Disk01 -Name : Disk01 -Type : Microsoft.Compute/disks -Location : westus2 -Tags : {} -``` - -This command gets the properties of the disk named 'Disk01' in the resource group 'ResourceGroup01'. - -### Example 2 -``` -PS C:\> Get-AzDisk -ResourceGroupName 'ResourceGroup01' - -ResourceGroupName : ResourceGroup01 -ManagedBy : -Sku : Microsoft.Azure.Management.Compute.Models.DiskSku -Zones : -TimeCreated : 6/29/2018 4:26:27 PM -OsType : Windows -CreationData : Microsoft.Azure.Management.Compute.Models.CreationData -DiskSizeGB : 127 -EncryptionSettings : -ProvisioningState : Succeeded -DiskIOPSReadWrite : 500 -DiskMBpsReadWrite : 100 -Id : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ResourceGroup01/providers/Microsoft.Compu - te/disks/win1_OsDisk_1 -Name : win1_OsDisk_1 -Type : Microsoft.Compute/disks -Location : westus2 -Tags : {} - -ResourceGroupName : ResourceGroup01 -ManagedBy : -Sku : Microsoft.Azure.Management.Compute.Models.DiskSku -Zones : -TimeCreated : 6/29/2018 4:27:27 PM -OsType : Windows -CreationData : Microsoft.Azure.Management.Compute.Models.CreationData -DiskSizeGB : 127 -EncryptionSettings : -ProvisioningState : Succeeded -DiskIOPSReadWrite : 500 -DiskMBpsReadWrite : 100 -Id : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ResourceGroup01/providers/Microsoft.Compu - te/disks/win1_OsDisk_2 -Name : win1_OsDisk_2 -Type : Microsoft.Compute/disks -Location : westus2 -Tags : {} -``` - -This command gets the properties of all disks in the resource group 'ResourceGroup01'. - -### Example 3 -``` -PS C:\> Get-AzDisk - -ResourceGroupName : ResourceGroup01 -ManagedBy : -Sku : Microsoft.Azure.Management.Compute.Models.DiskSku -Zones : -TimeCreated : 6/29/2018 4:26:27 PM -OsType : Windows -CreationData : Microsoft.Azure.Management.Compute.Models.CreationData -DiskSizeGB : 127 -EncryptionSettings : -ProvisioningState : Succeeded -DiskIOPSReadWrite : 500 -DiskMBpsReadWrite : 100 -Id : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ResourceGroup01/providers/Microsoft.Compu - te/disks/win1_OsDisk_1 -Name : win1_OsDisk_1 -Type : Microsoft.Compute/disks -Location : westus2 -Tags : {} - -ResourceGroupName : ResourceGroup02 -ManagedBy : -Sku : Microsoft.Azure.Management.Compute.Models.DiskSku -Zones : -TimeCreated : 6/29/2018 4:27:27 PM -OsType : Windows -CreationData : Microsoft.Azure.Management.Compute.Models.CreationData -DiskSizeGB : 127 -EncryptionSettings : -ProvisioningState : Succeeded -DiskIOPSReadWrite : 500 -DiskMBpsReadWrite : 100 -Id : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ResourceGroup02/providers/Microsoft.Compu - te/disks/win1_OsDisk_2 -Name : win1_OsDisk_2 -Type : Microsoft.Compute/disks -Location : westus2 -Tags : {} -``` - -This command gets the properties of all disks under the subscription. - -### Example 4 -``` -PS C:\> Get-AzDisk -Name win_OsDisk* - -ResourceGroupName : ResourceGroup01 -ManagedBy : -Sku : Microsoft.Azure.Management.Compute.Models.DiskSku -Zones : -TimeCreated : 6/29/2018 4:26:27 PM -OsType : Windows -CreationData : Microsoft.Azure.Management.Compute.Models.CreationData -DiskSizeGB : 127 -EncryptionSettings : -ProvisioningState : Succeeded -DiskIOPSReadWrite : 500 -DiskMBpsReadWrite : 100 -Id : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ResourceGroup01/providers/Microsoft.Compu - te/disks/win1_OsDisk_1 -Name : win1_OsDisk_1 -Type : Microsoft.Compute/disks -Location : westus2 -Tags : {} - -ResourceGroupName : ResourceGroup02 -ManagedBy : -Sku : Microsoft.Azure.Management.Compute.Models.DiskSku -Zones : -TimeCreated : 6/29/2018 4:27:27 PM -OsType : Windows -CreationData : Microsoft.Azure.Management.Compute.Models.CreationData -DiskSizeGB : 127 -EncryptionSettings : -ProvisioningState : Succeeded -DiskIOPSReadWrite : 500 -DiskMBpsReadWrite : 100 -Id : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/ResourceGroup02/providers/Microsoft.Compu - te/disks/win1_OsDisk_2 -Name : win1_OsDisk_2 -Type : Microsoft.Compute/disks -Location : westus2 -Tags : {} -``` - -This command gets the properties of all disks under the subscription name starting with win1_OsDisk. - -## PARAMETERS - -### -DefaultProfile -The credentials, account, tenant, and subscription used for communication with azure. - -```yaml -Type: Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer -Parameter Sets: (All) -Aliases: AzContext, AzureRmContext, AzureCredential - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -DiskName -Specifies the name of a disk. - -```yaml -Type: System.String -Parameter Sets: (All) -Aliases: Name - -Required: False -Position: 1 -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: True -``` - -### -ResourceGroupName -Specifies the name of a resource group. - -```yaml -Type: System.String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: True -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### Microsoft.Azure.Commands.Compute.Automation.Models.PSDisk - -## NOTES - -## RELATED LINKS diff --git a/samples-v1.0/Microsoft.PowerShell.Core/About/About.md b/samples-v1.0/Microsoft.PowerShell.Core/About/About.md deleted file mode 100644 index 89667e0..0000000 --- a/samples-v1.0/Microsoft.PowerShell.Core/About/About.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -Download Help Link: https://Please-enter-FwLink-manually -Help Version: 6.0 -keywords: powershell,cmdlet -Locale: en-US -Module Guid: 00000000-0000-0000-0000-000000000000 -Module Name: About -ms.date: 02/25/2019 -schema: 2.0.0 -title: About topics ---- -# About topics - -## Description - -About topics cover a ranges of concepts about PowerShell. - -## About Topics - -### [about_Aliases](about_Aliases.md) -Describes how to use alternate names for cmdlets and commands in PowerShell. - -### [about_Break](about_Break.md) -Describes a statement you can use to immediately exit Foreach, For, While, Do, or Switch statements. diff --git a/samples-v1.0/Microsoft.PowerShell.Core/About/about_Aliases.md b/samples-v1.0/Microsoft.PowerShell.Core/About/about_Aliases.md deleted file mode 100644 index a958803..0000000 --- a/samples-v1.0/Microsoft.PowerShell.Core/About/about_Aliases.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -keywords: powershell,cmdlet -Locale: en-US -ms.date: 11/27/2017 -online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_aliases?view=powershell-7.1&WT.mc_id=ps-gethelp -schema: 2.0.0 -title: about_Aliases ---- -# About Aliases - -## SHORT DESCRIPTION -Describes how to use alternate names for cmdlets and commands in -PowerShell. - -## LONG DESCRIPTION - -An alias is an alternate name or nickname for a cmdlet or for a command -element, such as a function, script, file, or executable file. You can use the -alias instead of the command name in any PowerShell commands. - -To create an alias, use the New-Alias cmdlet. For example, the following -command creates the "gas" alias for the `Get-AuthenticodeSignature` cmdlet: - -```powershell -New-Alias -Name gas -Value Get-AuthenticodeSignature -``` - -After you create the alias for the cmdlet name, you can use the alias instead -of the cmdlet name. For example, to get the Authenticode signature for the -SqlScript.ps1 file, type: - -```powershell -Get-AuthenticodeSignature SqlScript.ps1 -``` - -Or, type: - -```powershell -gas SqlScript.ps1 -``` - -If you create "word" as the alias for Microsoft Office Word, you can type -"word" instead of the following: - -```powershell -"C:\Program Files\Microsoft Office\Office11\Winword.exe" -``` - -## BUILT-IN ALIASES - -PowerShell includes a set of built-in aliases, including "cd" and "chdir" for -the Set-Location cmdlet, and "ls" and "dir" for the Get-ChildItem cmdlet. - -To get all the aliases on the computer, including the built-in aliases, type: - -```powershell -Get-Alias -``` - -## ALIAS CMDLETS - -PowerShell includes the following cmdlets, which are designed for working with -aliases: - -- `Get-Alias` - Gets all the aliases in the current session. -- `New-Alias` - Creates a new alias. -- `Set-Alias` - Creates or changes an alias. -- `Export-Alias` - Exports one or more aliases to a file. -- `Import-Alias` - Imports an alias file into PowerShell. - -For detailed information about the cmdlets, type: - -```powershell -Get-Help -Detailed -``` - -For example, type: - -```powershell -Get-Help Export-Alias -Detailed -``` - -## CREATING AN ALIAS - -To create a new alias, use the New-Alias cmdlet. For example, to create the -"gh" alias for Get-Help, type: - -```powershell -New-Alias -Name gh -Value Get-Help -``` - -You can use the alias in commands, just as you would use the full cmdlet name, -and you can use the alias with parameters. - -For example, to get detailed Help for the Get-WmiObject cmdlet, type: - -```powershell -Get-Help Get-WmiObject -Detailed -``` - -Or, type: - -```powershell -gh Get-WmiObject -Detailed -``` - -## SAVING ALIASES - -The aliases that you create are saved only in the current session. To use the -aliases in a different session, add the alias to your PowerShell profile. Or, -use the Export-Alias cmdlet to save the aliases to a file. - -For more information, type: - -```powershell -Get-Help about_Profiles -``` - -## GETTING ALIASES - -To get all the aliases in the current session, including the built-in aliases, -the aliases in your PowerShell profiles, and the aliases that you have created -in the current session, type: - -```powershell -Get-Alias -``` - -To get particular aliases, use the Name parameter of the Get-Alias cmdlet. For -example, to get aliases that begin with "p", type: - -```powershell -Get-Alias -Name p* -``` - -To get the aliases for a particular item, use the Definition parameter. For -example, to get the aliases for the Get-ChildItem cmdlet type: - -```powershell -Get-Alias -Definition Get-ChildItem -``` - -### GET-ALIAS OUTPUT - -Get-Alias returns only one type of object, an AliasInfo object -(System.Management.Automation.AliasInfo). The name of aliases that don't -include a hyphen, such as "cd" are displayed in the following format: - -```powershell -Get-Alias ac -``` - -```Output -CommandType Name Version Source ------------ ---- ------- ------ -Alias ac -> Add-Content -``` - -This makes it very quick and easy to get the information that you need. - -The arrow-based alias name format is not used for aliases that include a -hyphen. These are likely to be preferred substitute names for cmdlets and -functions, instead of typical abbreviations or nicknames, and the author might -not want them to be as evident. - -## ALTERNATE NAMES FOR COMMANDS WITH PARAMETERS - -You can assign an alias to a cmdlet, script, function, or executable file. You -cannot assign an alias to a command and its parameters. For example, you can -assign an alias to the `Get-Eventlog` cmdlet, but you cannot assign an alias -to the `Get-Eventlog -LogName System` command. - -You can create a function that includes the command. To create a function, -type the word "function" followed by a name for the function. Type the -command, and enclose it in braces ({}). - -For example, the following command creates the syslog function. This function -represents the `Get-Eventlog -LogName System` command: - -```powershell -function Get-SystemEventlog {Get-Eventlog -LogName System} -Set-Alias -Name syslog -Value Get-SystemEventlog -``` - -You can now type "syslog" instead of the command. And, you can create aliases -for the new function. - -For more information about functions, type: - -```powershell -Get-Help about_Functions -``` - -## ALIAS OBJECTS - -PowerShell aliases are represented by objects that are instances of the -System.Management.Automation.AliasInfo class. For more information about this -type of object, see [AliasInfo Class][aliasinfo] in the Microsoft Developer -Network (MSDN) library. - -To view the properties and methods of the alias objects, get the aliases. -Then, pipe them to the Get-Member cmdlet. For example: - -```powershell -Get-Alias | Get-Member -``` - -To view the values of the properties of a specific alias, such as the `dir` -alias, get the alias. Then, pipe it to the Format-List cmdlet. For example, -the following command gets the "dir" alias. Next, the command pipes the alias -to the Format-List cmdlet. Then, the command uses the Property parameter of -Format-List with a wildcard character (\*) to display all the properties of -the `dir` alias. The following command performs these tasks: - -```powershell -Get-Alias -Name dir | Format-List -Property * -``` - -## PowerShell ALIAS PROVIDER - -PowerShell includes the Alias provider. The Alias provider lets you view the -aliases in PowerShell as though they were on a file system drive. - -The Alias provider exposes the Alias: drive. To go into the Alias: drive, -type: - -```powershell -Set-Location Alias: -``` - -To view the contents of the drive, type: - -```powershell -Get-ChildItem -``` - -To view the contents of the drive from another PowerShell drive, begin the -path with the drive name. Include the colon (:). For example: - -```powershell -Get-ChildItem -Path Alias: -``` - -To get information about a particular alias, type the drive name and the alias -name. Or, type a name pattern. For example, to get all the aliases that begin -with "p", type: - -```powershell -Get-ChildItem -Path Alias:p* -``` - -For more information about the PowerShell Alias provider, type: - -```powershell -Get-Help Alias -``` - -## SEE ALSO - -- [New-Alias](xref:Microsoft.PowerShell.Utility.New-Alias) -- [Get-Alias](xref:Microsoft.PowerShell.Utility.Get-Alias) -- [Set-Alias](xref:Microsoft.PowerShell.Utility.Set-Alias) -- [Export-Alias](xref:Microsoft.PowerShell.Utility.Export-Alias) -- [Import-Alias](xref:Microsoft.PowerShell.Utility.Import-Alias) -- [Get-PSProvider](xref:Microsoft.PowerShell.Management.Get-PSProvider) -- [Get-PSDrive](xref:Microsoft.PowerShell.Management.Get-PSDrive) -- [about_functions](about_functions.md) -- [about_profiles](about_profiles.md) -- [about_providers](about_providers.md) - - -[aliasinfo]: /dotnet/api/system.management.automation.aliasinfo - diff --git a/samples-v1.0/Microsoft.PowerShell.Core/About/about_Break.md b/samples-v1.0/Microsoft.PowerShell.Core/About/about_Break.md deleted file mode 100644 index 83a5565..0000000 --- a/samples-v1.0/Microsoft.PowerShell.Core/About/about_Break.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -keywords: powershell,cmdlet -Locale: en-US -ms.date: 06/04/2020 -online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_break?view=powershell-7.1&WT.mc_id=ps-gethelp -schema: 2.0.0 -title: about_Break ---- -# About Break - -## Short description - -Describes a statement you can use to immediately exit `foreach`, `for`, -`while`, `do`, `switch`, or `trap` statements. - -## Long description - -The `break` statement provides a way to exit the current control block. -Execution continues at the next statement after the control block. The -statement supports labels. A label is a name you assign to a statement in a -script. - -## Using break in loops - -When a `break` statement appears in a loop, such as a `foreach`, `for`, `do`, -or `while` loop, PowerShell immediately exits the loop. - -A `break` statement can include a label that lets you exit embedded loops. A -label can specify any loop keyword, such as `foreach`, `for`, or `while`, in a -script. - -The following example shows how to use a `break` statement to exit a `for` -statement: - -```powershell -for($i=1; $i -le 10; $i++) { - Write-Host $i - break -} -``` - -In this example, the `break` statement exits the `for` loop when the `$i` -variable equals 1. Even though the `for` statement evaluates to **True** until -`$i` is greater than 10, PowerShell reaches the break statement the first time -the `for` loop is run. - -It is more common to use the `break` statement in a loop where an inner -condition must be met. Consider the following `foreach` statement example: - -```powershell -$i=0 -$varB = 10,20,30,40 -foreach ($val in $varB) { - if ($val -eq 30) { - break - } - $i++ -} -Write-Host "30 was found in array index $i" -``` - -In this example, the `foreach` statement iterates the `$varB` array. The `if` -statement evaluates to False the first two times the loop is run and the -variable `$i` is incremented by 1. The third time the loop is run, `$i` equals -2, and the `$val` variable equals 30. At this point, the `break` statement -runs, and the `foreach` loop exits. - -### Using a labeled break in a loop - -A `break` statement can include a label. If you use the `break` keyword with a -label, PowerShell exits the labeled loop instead of exiting the current loop. -The label is a colon followed by a name that you assign. The label must be the -first token in a statement, and it must be followed by the looping keyword, -such as `while`. - -`break` moves execution out of the labeled loop. In embedded loops, this has a -different result than the `break` keyword has when it is used by itself. This -example has a `while` statement with a `for` statement: - -```powershell -:myLabel while () { - for ($item in $items) { - if () { - break myLabel - } - $item = $x # A statement inside the For-loop - } -} -$a = $c # A statement after the labeled While-loop -``` - -If condition 2 evaluates to **True**, the execution of the script skips down to -the statement after the labeled loop. In the example, execution starts again -with the statement `$a = $c`. - -You can nest many labeled loops, as shown in the following example. - -```powershell -:red while () { - :yellow while () { - while () { - if ($a) {break} - if ($b) {break red} - if ($c) {break yellow} - } - Write-Host "After innermost loop" - } - Write-Host "After yellow loop" -} -Write-Host "After red loop" -``` - -If the `$b` variable evaluates to True, execution of the script resumes after -the loop that is labeled "red". If the `$c` variable evaluates to True, -execution of the script control resumes after the loop that is labeled -"yellow". - -If the `$a` variable evaluates to True, execution resumes after the innermost -loop. No label is needed. - -PowerShell does not limit how far labels can resume execution. The label can -even pass control across script and function call boundaries. - -## Using break in a switch statement - -In a `switch`construct, `break` causes PowerShell to exit the `switch` code block. - -The `break` keyword is used to leave the `switch` construct. For example, the -following `switch` statement uses `break` statements to test for the most -specific condition: - -```powershell -$var = "word2" -switch -regex ($var) { - "word2" { - Write-Host "Exact" $_ - break - } - - "word.*" { - Write-Host "Match on the prefix" $_ - break - } - - "w.*" { - Write-Host "Match on at least the first letter" $_ - break - } - - default { - Write-Host "No match" $_ - break - } -} -``` - -In this example, the `$var` variable is created and initialized to a string -value of `word2`. The `switch` statement uses the **Regex** class to match the -variable value first with the term `word2`. Because the variable value and the -first test in the `switch` statement match, the first code block in the -`switch` statement runs. - -When PowerShell reaches the first `break` statement, the `switch` statement -exits. If the four `break` statements are removed from the example, all four -conditions are met. This example uses the `break` statement to display results -when the most specific condition is met. - -## Using break in a trap statement - -If the final statement executed in the body of a `trap` statement is `break`, -the error object is suppressed and the exception is re-thrown. - -The following example create a **DivideByZeroException** exception that is -trapped using the `trap` statement. - -```powershell -function test { - trap [DivideByZeroException] { - Write-Host 'divide by zero trapped' - break - } - - $i = 3 - 'Before loop' - while ($true) { - "1 / $i = " + (1 / $i--) - } - 'After loop' -} -test -``` - -Notice that execution stops at the exception. The `After loop` is never reached. -The exception is re-thrown after the `trap` executes. - -```Output -Before loop -1 / 3 = 0.333333333333333 -1 / 2 = 0.5 -1 / 1 = 1 -divide by zero trapped -ParentContainsErrorRecordException: -Line | - 10 | "1 / $i = " + (1 / $i--) - | ~~~~~~~~~~~~~~~~~~~~~~~~ - | Attempted to divide by zero. -``` - -## Do not use break outside of a loop, switch, or trap - -When `break` is used outside of a construct that directly supports it -(loops, `switch`, `trap`), PowerShell looks _up the call stack_ for an -enclosing construct. If it can't find an enclosing construct, the current -runspace is quietly terminated. - -This means that functions and scripts that inadvertently use a `break` outside -of an enclosing construct that supports it can inadvertently terminate their -_callers_. - -Using `break` inside a pipeline `break`, such as a `ForEach-Object` script -block, not only exits the pipeline, it potentially terminates the entire -runspace. - -## See also - -[about_Comparison_Operators](about_Comparison_Operators.md) - -[about_Continue](about_Continue.md) - -[about_For](about_For.md) - -[about_Foreach](about_Foreach.md) - -[about_Switch](about_Switch.md) - -[about_Throw](about_Throw.md) - -[about_Trap](about_Trap.md) - -[about_Try_Catch_Finally](about_Try_Catch_Finally.md) - -[about_While](about_While.md) diff --git a/samples-v1.0/Microsoft.PowerShell.Core/Add-History.md b/samples-v1.0/Microsoft.PowerShell.Core/Add-History.md deleted file mode 100644 index 51cd1d6..0000000 --- a/samples-v1.0/Microsoft.PowerShell.Core/Add-History.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -external help file: System.Management.Automation.dll-Help.xml -keywords: powershell,cmdlet -Locale: en-US -Module Name: Microsoft.PowerShell.Core -ms.date: 05/13/2020 -online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/add-history?view=powershell-7.1&WT.mc_id=ps-gethelp -schema: 2.0.0 -title: Add-History ---- - -# Add-History - -## SYNOPSIS -Appends entries to the session history. - -## SYNTAX - -``` -Add-History [[-InputObject] ] [-Passthru] [] -``` - -## DESCRIPTION - -The `Add-History` cmdlet adds entries to the end of the session history, that is, the list of -commands entered during the current session. - -The session history is a list of the commands entered during the session. The session history -represents the order of execution, the status, and the start and end times of the command. As you -enter each command, PowerShell adds it to the history so that you can reuse it. For more information -about the session history, see [about_History](About/about_History.md). - -The session history is managed separately from the history maintained by the **PSReadLine** module. -Both histories are available in sessions where **PSReadLine** is loaded. This cmdlet only works with -the session history. For more information see, [about_PSReadLine](../PSReadLine/About/about_PSReadLine.md). - -You can use the `Get-History` cmdlet to get the commands and pass them to `Add-History`, or you can -export the commands to a CSV or XML file, then import the commands, and pass the imported file to -`Add-History`. You can use this cmdlet to add specific commands to the history or to create a single -history file that includes commands from more than one session. - -## EXAMPLES - -### Example 1: Add commands to the history of a different session - -This example add the commands typed in one PowerShell session to the history of a different -PowerShell session. - -```powershell -Get-History | Export-Csv c:\testing\history.csv -IncludeTypeInformation -Import-Csv c:\testing\history.csv | Add-History -``` - -The first command gets objects representing the commands in the history and exports them to the -`History.csv` file. - -The second command is typed at the command line of a different session. It uses the `Import-Csv` -cmdlet to import the objects in the `History.csv` file. The pipeline operator (`|`) passes the -objects to the `Add-History` cmdlet, which adds the objects representing the commands in the -`History.csv` file to the current session history. - -### Example 2: Import and run commands - -This example imports commands from the `History.xml` file, adds them to the current session history, -and then runs the commands in the combined history. - -```powershell -Import-Clixml c:\temp\history.xml | Add-History -PassThru | ForEach-Object -Process {Invoke-History} -``` - -The first command uses the `Import-Clixml` cmdlet to import a command history that was exported to -the `History.xml` file. The pipeline operator passes the commands to the `Add-History` cmdlet, which -adds the commands to the current session history. The **PassThru** parameter passes the objects -representing the added commands down the pipeline. - -The command then uses the `ForEach-Object` cmdlet to apply the `Invoke-History` command to each of -the commands in the combined history. The `Invoke-History` command is formatted as a script block, -enclosed in braces (`{}`), as required by the **Process** parameter of the `ForEach-Object` cmdlet. - -### Example 3: Add commands in the history to the end of the history - -This example adds the first five commands in the history to the end of the history list. - -```powershell -Get-History -Id 5 -Count 5 | Add-History -``` - -The `Get-History` cmdlet gets the five commands ending in command 5. The pipeline operator passes -them to the `Add-History` cmdlet, which appends them to the current history. The `Add-History` -command does not include any parameters, but PowerShell associates the objects passed through the -pipeline with the **InputObject** parameter of `Add-History`. - -### Example 4: Add commands in a .csv file to the current history - -This example add the commands in the `History.csv` file to the current session history. - -```powershell -$a = Import-Csv c:\testing\history.csv -Add-History -InputObject $a -PassThru -``` - -The `Import-Csv` cmdlet imports the commands in the `History.csv` file and -store its contents in the variable `$a`. - -The second command uses the `Add-History` cmdlet to add the commands from `History.csv` to the -current session history. It uses the **InputObject** parameter to specify the `$a` variable and the -**PassThru** parameter to generate an object to display at the command line. Without the -**PassThru** parameter, the `Add-History` cmdlet does not generate any output. - -### Example 5: Add commands in an .xml file to the current history - -This example adds the commands in the `history.xml` file to the current session history. - -```powershell -Add-History -InputObject (Import-Clixml c:\temp\history.xml) -``` - -The **InputObject** parameter passes the results of the command in parentheses to the `Add-History` -cmdlet. The command in parentheses, which is executed first, imports the `history.xml` file into -PowerShell. The `Add-History` cmdlet then adds the commands in the file to the session history. - -## PARAMETERS - -### -InputObject - -Specifies an array of entries to add to the history as **HistoryInfo** object to the session history. -You can use this parameter to submit a **HistoryInfo** object, such as the ones that are returned by -the `Get-History`, `Import-Clixml`, or `Import-Csv` cmdlets, to `Add-History`. - -```yaml -Type: System.Management.Automation.PSObject[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: True (ByValue) -Accept wildcard characters: False -``` - -### -Passthru - -Indicates that this cmdlet returns a **HistoryInfo** object for each history entry. By default, this -cmdlet does not generate any output. - -```yaml -Type: System.Management.Automation.SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.Commands.HistoryInfo - -You can pipe a **HistoryInfo** object to this cmdlet. - -## OUTPUTS - -### None or Microsoft.PowerShell.Commands.HistoryInfo - -This cmdlet returns a **HistoryInfo** object if you specify the **PassThru** parameter. Otherwise, -this cmdlet does not generate any output. - -## NOTES - -The session history is a list of the commands entered during the session together with the ID. The -session history represents the order of execution, the status, and the start and end times of the -command. As you enter each command, PowerShell adds it to the history so that you can reuse it. For -more information about the session history, see [about_History](About/about_History.md). - -To specify the commands to add to the history, use the **InputObject** parameter. The `Add-History` -command accepts only **HistoryInfo** objects, such as those returned for each command by the -`Get-History` cmdlet. You cannot pass it a path and file name or a list of commands. - -You can use the **InputObject** parameter to pass a file of **HistoryInfo** objects to -`Add-History`. To do so, export the results of a `Get-History` command to a file by using the -`Export-Csv` or `Export-Clixml` cmdlet and then import the file by using the `Import-Csv` or -`Import-Clixml` cmdlets. You can then pass the file of imported **HistoryInfo** objects to -`Add-History` through a pipeline or in a variable. For more information, see the examples. - -The file of **HistoryInfo** objects that you pass to the `Add-History` cmdlet must include the type -information, column headings, and all of the properties of the **HistoryInfo** objects. If you -intend to pass the objects back to `Add-History`, do not use the **NoTypeInformation** parameter of -the `Export-Csv` cmdlet and do not delete the type information, column headings, or any fields in -the file. - -To modify the session history, export the session to a CSV or XML file, modify the file, import the -file, and use `Add-History` to append it to the current session history. - -## RELATED LINKS - -[Clear-History](Clear-History.md) - -[Get-History](Get-History.md) - -[Invoke-History](Invoke-History.md) - -[about_PSReadLine](../PSReadLine/About/about_PSReadLine.md) - -[Get-PSReadLineOption](/powershell/module/psreadline/get-psreadlineoption) - -[Set-PSReadLineOption](/powershell/module/psreadline/set-psreadlineoption) - diff --git a/samples-v1.0/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md b/samples-v1.0/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md deleted file mode 100644 index b745fbd..0000000 --- a/samples-v1.0/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -Download Help Link: https://aka.ms/powershell71-help -Help Version: 7.1.0.0 -keywords: powershell,cmdlet -Locale: en-US -Module Guid: 00000000-0000-0000-0000-000000000000 -Module Name: Microsoft.PowerShell.Core -ms.date: 02/28/2019 -schema: 2.0.0 -title: Microsoft.PowerShell.Core ---- -# Microsoft.PowerShell.Core Module - -## Description - -This section contains the help topics for the cmdlets that are installed with PowerShell -Microsoft.PowerShell.Core module. The Core module contains cmdlets and providers that manage the -basic features of PowerShell. - -## Microsoft.PowerShell.Core Cmdlets