diff --git a/.spelling b/.spelling index 8d09ca52cb..ddb80d778a 100644 --- a/.spelling +++ b/.spelling @@ -44,8 +44,11 @@ favor favorite frontload FullCLR +Get-Acl +Get-AuthenticodeSignature Get-ChildItem Get-ComputerInfo +Get-PSSessionConfiguration Get-WinEvent github hashtable @@ -62,6 +65,8 @@ macOS Microsoft.PowerShell.Archive MS-PSRP myget +New-PSSessionOption +New-PSTransportOption NuGet nuget nunit @@ -79,12 +84,17 @@ PowerShellGet ProgramFiles ps1 PSReadline +Register-EngineEvent +Register-PSSessionConfiguration remoting ResGen RFCs Runspace runtimes SecureString +Set-Acl +Set-AuthenticodeSignature +Set-ExecutionPolicy ssh StackOverflow submodule @@ -92,6 +102,8 @@ submodules sudo TeamCity toolset +Unregister-Event +Unregister-PSSessionConfiguration vscode walkthrough wget @@ -229,6 +241,12 @@ Win8 windir - docs/KNOWNISSUES.md cp +pipelining +psl-omi-provider +globbing +Register-WmiEvent +System.Management.Automation.SemanticVersion +System.Timers.Timer - docs/learning-powershell/create-powershell-scripts.md NetIP.ps1. RemoteSigned @@ -322,8 +340,6 @@ Export-ModuleMember Find-DscResource Find-PackageProvider Find-RoleCapability -Get-Acl -Get-AuthenticodeSignature Get-CimAssociatedInstance Get-CimClass Get-CimInstance @@ -352,7 +368,6 @@ Get-PSReadlineOption Get-PSRepository Get-PSSession Get-PSSessionCapability -Get-PSSessionConfiguration Get-Runspace Get-RunspaceDebug Get-TimeZone @@ -382,8 +397,6 @@ New-ModuleManifest New-PSDrive New-PSRoleCapabilityFile New-PSSessionConfigurationFile -New-PSSessionOption -New-PSTransportOption New-ScriptFileInfo New-TemporaryFile New-WinEvent @@ -392,11 +405,9 @@ New-WSManSessionOption Receive-PSSession Register-ArgumentCompleter Register-CimIndicationEvent -Register-EngineEvent Register-ObjectEvent Register-PackageSource Register-PSRepository -Register-PSSessionConfiguration Remove-CimInstance Remove-CimSession Remove-ItemProperty @@ -413,10 +424,7 @@ Rename-ItemProperty Rename-LocalGroup Rename-LocalUser Select-xml -Set-Acl -Set-AuthenticodeSignature Set-CimInstance -Set-ExecutionPolicy Set-ItemProperty Set-LocalGroup Set-LocalUser @@ -436,10 +444,8 @@ Test-ModuleManifest Test-PSSessionConfigurationFile Test-ScriptFileInfo Test-WSMan -Unregister-Event Unregister-PackageSource Unregister-PSRepository -Unregister-PSSessionConfiguration Update-FormatData Update-ModuleManifest Update-ScriptFileInfo diff --git a/docs/FAQ.md b/docs/FAQ.md index a99d3ecd8e..e8bc134500 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,17 +1,16 @@ -Where can I learn PowerShell's syntax? -====================================== +# Frequently Asked Questions + +## Where can I learn PowerShell's syntax? [SS64.com](http://ss64.com/ps/syntax.html) is a good resource. -What are the best practices and style? -====================================== +## What are the best practices and style? The [PoshCode][] unofficial guide is our reference. [PoshCode]: https://github.com/PoshCode/PowerShellPracticeAndStyle -What are PowerShell's scoping rules? -==================================== +## What are PowerShell's scoping rules? - Variables are created in your current scope unless explicitly indicated. - Variables are visible in a child scope unless explicitly indicated. @@ -19,38 +18,34 @@ What are PowerShell's scoping rules? explicitly indicated. - Variables may be placed explicitly in a scope. -Things that create a scope: ---------------------------- +### Things that create a scope - [functions](http://ss64.com/ps/syntax-functions.html) - [call operator](http://ss64.com/ps/call.html) (`& { }`) - [script invocations](http://ss64.com/ps/syntax-run.html) -Things that operate in the current scope: ------------------------------------------ +### Things that operate in the current scope - [source operator](http://ss64.com/ps/source.html) (`. { }`) - [statements](http://ss64.com/ps/statements.html) (`if .. else`, `for`, `switch`, etc.) -Why didn't an error throw an exception? -======================================= +## Why didn't an error throw an exception? -Error handling in PowerShell is a bit weird, as not all errors result in catchable exceptions by default. -Setting `$ErrorActionPreference = 'Stop'` will likely do what you want; -that is, cause non-terminating errors instead to terminate. +Error handling in PowerShell is a bit weird, as not all errors result in catchable exceptions by default. +Setting `$ErrorActionPreference = 'Stop'` will likely do what you want; +that is, cause non-terminating errors instead to terminate. Read [An Introduction To Error Handling in PowerShell][error] for more information. [error]: https://blogs.msdn.microsoft.com/kebab/2013/06/09/an-introduction-to-error-handling-in-powershell/ -Where do I get the PowerShell Core SDK package? -============================================================= +## Where do I get the PowerShell Core SDK package? The SDK NuGet package `Microsoft.PowerShell.SDK` is provided for developers to write .NET Core C# code targeting PowerShell Core. PowerShell NuGet packages for releases starting from v6.0.0-alpha.9 will be published to the [powershell-core][] myget feed. To use the `Microsoft.PowerShell.SDK` NuGet package, declare the `frameworks` section in your `project.json` file as follows: -``` +```json "frameworks": { "netstandard1.6": { "imports": [ "dnxcore50", "portable-net45+win8" ], @@ -63,8 +58,7 @@ To use the `Microsoft.PowerShell.SDK` NuGet package, declare the `frameworks` se [powershell-core]: https://powershell.myget.org/gallery/powershell-core -Why did my build fail? -============================================ +## Why did my build fail? There are few common issues with the build. The easiest way to resolve most issues with the build is to run `Start-PSBuild -Clean`. @@ -72,7 +66,7 @@ The easiest way to resolve most issues with the build is to run `Start-PSBuild - ### Dependency changed If package dependencies were changed in any `project.json`, you need to manually -run `dotnet restore` to update your local dependency graphs. +run `dotnet restore` to update your local dependency graphs. `Start-PSBuild -Restore` can automatically do this. ### Resource changed @@ -88,15 +82,13 @@ Try it, when you see compilation error about *strings. Similar to `-ResGen` parameter, there is `-TypeGen` parameter that triggers regeneration of type catalog. -Why did `Start-PSBuild` tell me to update `dotnet`? -=================================================== +## Why did `Start-PSBuild` tell me to update `dotnet`? We depend on the latest version of the .NET CLI, as we use the output of `dotnet ---info` to determine the current runtime identifier. +--info` to determine the current runtime identifier. Without this information, our build function can't know where `dotnet` is going to place the build artifacts. You can automatically install this using `Start-PSBootstrap`. - **However, you must first manually uninstall other versions of the CLI.** If you have installed by using any of the following means: @@ -113,11 +105,10 @@ scripts, which do essentially the same thing), you must manually delete the folder, as the .NET CLI team re-engineered how their binaries are setup, such that new packages' binaries get stomped on by old packages' binaries. -Why is my submodule empty? -========================== +## Why is my submodule empty? If a submodule (such as `src/Modules/Pester`) is empty, that means it is -uninitialized. +uninitialized. If you've already cloned, you can do this with: ```sh @@ -133,14 +124,14 @@ git submodule status If they're initialized, it will look like this: -``` - f23641488f8d7bf8630ca3496e61562aa3a64009 src/Modules/Pester (f23641488) - c99458533a9b4c743ed51537e25989ea55944908 src/libpsl-native/test/googletest (release-1.7.0) +```output +f23641488f8d7bf8630ca3496e61562aa3a64009 src/Modules/Pester (f23641488) +c99458533a9b4c743ed51537e25989ea55944908 src/libpsl-native/test/googletest (release-1.7.0) ``` If they're not, there will be minuses in front (and the folders will be empty): -``` +```output -f23641488f8d7bf8630ca3496e61562aa3a64009 src/Modules/Pester (f23641488) -c99458533a9b4c743ed51537e25989ea55944908 src/libpsl-native/test/googletest (release-1.7.0) ``` @@ -148,15 +139,14 @@ If they're not, there will be minuses in front (and the folders will be empty): Please note that the commit hashes for the submodules have likely changed since this FAQ was written. -Why does my submodule say "HEAD detached at" some commit? -========================================================= +## Why does my submodule say "HEAD detached at" some commit? When a submodule is first initialized and updated, it is not checked out to a branch, but the very exact commit that the super-project (this PowerShell -repository) has recorded for the submodule. +repository) has recorded for the submodule. This behavior is intended. -If you want to check out an actual branch, just do so with `git checkout `. +If you want to check out an actual branch, just do so with `git checkout `. A submodule is just a Git repository; it just happens to be nested inside another repository. Please read the Git Book chapter on [submodules][]. diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md index abd1867457..4f73e51fc2 100644 --- a/docs/KNOWNISSUES.md +++ b/docs/KNOWNISSUES.md @@ -1,9 +1,10 @@ -Known Issues for PowerShell on Non-Windows Platforms -==================================== +# Known Issues + +## Known Issues for PowerShell on Non-Windows Platforms The first Alpha release of PowerShell on Linux and macOS is mostly functional but -does have some significant limitations and usability issues. -In some cases, these issues are simply bugs that haven't been fixed yet. +does have some significant limitations and usability issues. +In some cases, these issues are simply bugs that haven't been fixed yet. In other cases (as with the default aliases for ls, cp, etc.) we are looking for feedback from the community regarding the choices we make. @@ -12,142 +13,130 @@ and macOS tend to share the same level of maturity in both features and bugs. Except as noted below, the issues in this section will apply to both operating systems. -Case-sensitivity in PowerShell -------------------------------- +### Case-sensitivity in PowerShell -Historically, PowerShell has been uniformly case-insensitive, with few exceptions. +Historically, PowerShell has been uniformly case-insensitive, with few exceptions. On UNIX-like operating systems, the file system is case-sensitive and this is exposed through a number of ways, obvious and non-obvious. -### Directly: +#### Directly -- When specifying a file in PowerShell the correct case must be used. +- When specifying a file in PowerShell the correct case must be used. -- Only forward slashes can be used in path. +- Only forward slashes can be used in path. (On Windows either forward or backward slashes can be used.) -### Indirectly: +#### Indirectly -- If a script tries to load a module and the module name is not cased - correctly, then the module load will fail. +- If a script tries to load a module and the module name is not cased + correctly, then the module load will fail. This may cause a problem with existing scripts if the name by which the module is referenced doesn't match the actual file name. -- Tab-completion will not automatically auto-complete if the file name case is wrong. +- Tab-completion will not automatically auto-complete if the file name case is wrong. The fragment to complete must be cased properly. (Completion is case-insensitive for type name and type member completions.) -.PS1 File Extensions --------------------- +### .PS1 File Extensions PowerShell scripts must end in `.ps1` for the interpreter to understand -how to load and run them in the current process. -Running scripts in the current process is the expected usual behavior for PowerShell. +how to load and run them in the current process. +Running scripts in the current process is the expected usual behavior for PowerShell. The `#!` magic number may be added to a script that doesn't have a `.ps1` extension, but this will cause the script to be run in a new PowerShell instance preventing the script from working properly when interchanging objects. -Missing command aliases ------------------------ +### Missing command aliases On Linux/macOS, the "convenience aliases" for the basic commands `ls`, `cp`, -`mv`, `rm`, `cat`, `man`, `mount`, `ps` have been removed. +`mv`, `rm`, `cat`, `man`, `mount`, `ps` have been removed. On Windows, PowerShell provides a set of aliases that map to Linux command -names for user convenience. -These aliases have been removed from the default PowerShell on Linux/macOS distributions, -allowing the native executable to be run instead. -There are pros and cons to having do this. +names for user convenience. +These aliases have been removed from the default PowerShell on Linux/macOS distributions, +allowing the native executable to be run instead. +There are pros and cons to having do this. It exposes the native command experience to the PowerShell user but reduces functionality in the shell because the native commands return strings not objects. -> NOTE: This is an area where the PowerShell team is looking for feedback. -> What is the preferred solution? Should we leave it as is or add the -> convenience aliases back? See +> NOTE: This is an area where the PowerShell team is looking for feedback. +> What is the preferred solution? Should we leave it as is or add the +> convenience aliases back? See > [Issue #929](https://github.com/PowerShell/PowerShell/issues/929). -Missing Wildcard (globbing) Support ------------------------------------- +### Missing Wildcard (globbing) Support Currently, PowerShell only does wildcard expansion (globbing) for the -built-ins but not for external commands. -This means that a command like `ls *.txt` will fail because the asterisk will not be -expanded to match file names. -You can work around this by doing `ls (gci *.txt | % name)` or, more simply, +built-ins but not for external commands. +This means that a command like `ls *.txt` will fail because the asterisk will not be +expanded to match file names. +You can work around this by doing `ls (gci *.txt | % name)` or, more simply, `gci *.txt` using the PowerShell built-in equivalent to `ls`. [RFC0009](https://github.com/PowerShell/PowerShell-RFC/issues/33) -.NET Framework vs .NET Core Framework ------------------ +### .NET Framework vs .NET Core Framework PowerShell on Linux/macOS uses the .NET Core which is a subset of the full -.NET Framework on Microsoft Windows. +.NET Framework on Microsoft Windows. This is significant because PowerShell provides direct access to the underlying framework types, -methods etc. -As a result, scripts that run on Windows may not run on non-Windows platforms because of the differences in the frameworks. +methods etc. +As a result, scripts that run on Windows may not run on non-Windows platforms because of the differences in the frameworks. For more information about .NET Core Framework, see -Redirection Issues ------------------- +### Redirection Issues -Input redirection is not supported in PowerShell on any platform. +Input redirection is not supported in PowerShell on any platform. [Issue #1629](https://github.com/PowerShell/PowerShell/issues/1629) Use either `Get-Content` to write the contents of a file into the pipeline. -PowerShell does not currently support "direct pipelining" external commands. -Although the pipeline works properly for built-in PowerShell commands, +PowerShell does not currently support "direct pipelining" external commands. +Although the pipeline works properly for built-in PowerShell commands, with external (also called native) commands, each individual command in the pipeline is run to completion and then the aggregated -data is passed to the next command. +data is passed to the next command. (This behavior is intended to be fixed in a later release.) -Redirected output will contain the Unicode byte order mark (BOM) when the default UTF-8 encoding is used. +Redirected output will contain the Unicode byte order mark (BOM) when the default UTF-8 encoding is used. The BOM will cause problems when working with utilities that do not expect it or when appending to a file. Use `-Encoding ascii` to write ASCII text (which, not being Unicode, will not have a BOM). -Job Control ------------ +### Job Control -There is no job-control support in PowerShell on Linux/macOS. +There is no job-control support in PowerShell on Linux/macOS. The `fg` and `bg` commands are not available. `Ctrl-Z` sends the `powershell` process to the background. -Remoting Support ----------------- +### Remoting Support -Client-side remoting from Linux/macOS is not supported with the initial package. +Client-side remoting from Linux/macOS is not supported with the initial package. The work is being done in the [psl-omi-provider](https://github.com/PowerShell/psl-omi-provider) repo. -Just-Enough-Administration (JEA) Support ----------------------------------------- +### Just-Enough-Administration (JEA) Support The ability to create constrained administration (JEA) remoting -endpoints is not currently available in PowerShell on Linux/macOS. +endpoints is not currently available in PowerShell on Linux/macOS. This feature is currently not in scope for 6.0 and something we will consider post 6.0 but requires significant design work. -sudo, exec, and PowerShell -------------------------- +### `sudo`, `exec`, and PowerShell Because PowerShell runs most commands in memory (like Python or Ruby) -you can't use sudo directly with PowerShell built-ins. -(You can, of course, run `powershell` from sudo.) +you can't use sudo directly with PowerShell built-ins. +(You can, of course, run `powershell` from sudo.) If it is necessary to run a PowerShell cmdlet from within PowerShell with sudo, for example `sudo Set-Date 8/18/2016`, -then you would do `sudo powershell Set-Date 8/18/2016`. -Likewise, you can't exec a PowerShell built-in directly. +then you would do `sudo powershell Set-Date 8/18/2016`. +Likewise, you can't exec a PowerShell built-in directly. Instead you would have to do `exec powershell item_to_exec`. -Missing Cmdlets ---------------- +### Missing Cmdlets -A large number of the commands (cmdlets) normally available in PowerShell are not available on Linux/macOS. -In many cases, these commands make no sense on these platforms (e.g. Windows-specific features like the registry). -Other commands like the service control commands (get/start/stop-service) are present, but not functional. +A large number of the commands (cmdlets) normally available in PowerShell are not available on Linux/macOS. +In many cases, these commands make no sense on these platforms (e.g. Windows-specific features like the registry). +Other commands like the service control commands (get/start/stop-service) are present, but not functional. Future releases will correct these problems, fixing the broken cmdlets and adding new ones over time. -Command Availability --------------------- +### Command Availability The following table lists commands that are known not to work in PowerShell on Linux/macOS. @@ -159,7 +148,7 @@ The following table lists commands that are known not to work in PowerShell on L These commands will not be recognized. This will be fixed in a future release. -Get-Acl, Set-Acl +Get-Acl, Set-Acl Not available. These commands will not be recognized. This will be fixed in a future release. @@ -199,21 +188,19 @@ The following table lists commands that are known not to work in PowerShell on L -Installing Software using PackageManagement and PowerShellGet Modules ---------------------------------------- -- (v6.0.0-alpha.9) A bug in handling of System.Management.Automation.SemanticVersion as described in [#1618](https://github.com/PowerShell/PowerShell/issues/1618) prevents installing modules using -the Install-Module cmdlet due to the inability to parse the Alpha version string "6.0.0-alpha". -This similarly affects the Install-Package cmdlet. A fix has been merged and will be in a future -release. +### Installing Software using PackageManagement and PowerShellGet Modules -Known Issues for PowerShell on Windows -====================================== +- (v6.0.0-alpha.9) A bug in handling of System.Management.Automation.SemanticVersion as described in [#1618](https://github.com/PowerShell/PowerShell/issues/1618) prevents installing modules using + the Install-Module cmdlet due to the inability to parse the Alpha version string "6.0.0-alpha". + This similarly affects the Install-Package cmdlet. A fix has been merged and will be in a future + release. -Remoting Endpoint Creation on Nano Server TP5 ---------------------------------------------- +## Known Issues for PowerShell on Windows -The [script](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/windows.md) to create a new WinRM remoting +### Remoting Endpoint Creation on Nano Server TP5 + +The [script](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/windows.md) to create a new WinRM remoting endpoint (`Install-PowerShellRemoting.ps1`) encounters a bug in the in-box PowerShell Core on Nano Server TP5. The bug causes the script to create an incorrect directory for the plug-in and may result in creation of an invalid remoting endpoint. -When the same command is run for the second time, the script executes as expected and successfully creates the WinRM remoting endpoint. +When the same command is run for the second time, the script executes as expected and successfully creates the WinRM remoting endpoint. The bug in in-box PowerShell Core on Nano Server TP5 does not occur in later versions of Nano Server. diff --git a/test/common/markdown/markdown.tests.ps1 b/test/common/markdown/markdown.tests.ps1 index 02aca5abce..16f4bfd10e 100644 --- a/test/common/markdown/markdown.tests.ps1 +++ b/test/common/markdown/markdown.tests.ps1 @@ -73,6 +73,7 @@ Describe 'Common Tests - Validate Markdown Files' -Tag 'CI' { { $docsToTest = @( './*.md' + './docs/*.md' './docs/installation/*.md' ) $filter = ($docsToTest -join ',')