diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62cbf51299d..bf075f5c0f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,108 +1,9 @@ -# Contributing to PowerShell Documentation +# Contributor Guide -Thank you for your interest in PowerShell documentation! -See below for details on how you can contribute to our technical documentation. +Thank you for your interest in contributing to quality documentations. +As an open source project, we welcome input and updates from the community. +The following topics explain how to contribute to the PowerShell documentation. ->For general information about getting started with Git and GitHub, see [GitHub Help](https://help.github.com/). - -## Sign a CLA - -Before you can contribute to any PowerShell repositories, you must [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/). -If you've already contributed to PowerShell repositories in the past, congratulations! -You've already completed this step. - -## Providing feedback on PowerShell documentation - -You can point out errors, suggest changes, or request new topics by [creating an issue](https://help.github.com/articles/creating-an-issue/) on the -[PowerShell-Docs repository issues page](https://github.com/PowerShell/PowerShell-Docs/issues). - -Issues are reviewed regularly by members of the PowerShell documentation team, and are triaged, assigned, and addressed accordingly. - -## Writing PowerShell documentation - -One of the easiest ways to contribute to PowerShell is by helping to write and edit documentation. -All of our documentation hosted on GitHub is written using [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). - -## Making minor edits to existing topics - -To [edit an existing file](https://help.github.com/articles/editing-files-in-another-user-s-repository/), simply navigate to it and click the "Edit" button. -GitHub will automatically create your own fork of our repository where you can make your changes. -Once you're finished, save your edits and submit a [pull request](https://help.github.com/articles/creating-a-pull-request/) to the *staging* branch of the [PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repository. -After your pull request is created, someone on the PowerShell documentation team will review your changes before merging them into the *staging* branch. - -## Making major edits to existing topics - -If you are making substantial changes to an existing article, adding or changing images, or contributing a new article, you will need to manually create your GitHub fork, then clone the fork down to your local computer. -A fork is a GitHub-based replica of the main repository, under your GitHub account, which provides you with a working copy which you can use in isolation. -You will create pull requests from your fork. -Similarly, a clone is a local-based replica of the repository which, in this case, will be a clone of your fork. -The clone allows you to work on Git repositories offline, and using more powerful native software/tools. - -Here is the workflow for making major edits to existing documentation: - -1. [Create a fork](https://help.github.com/articles/fork-a-repo/) of the [PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repository. -2. [Create a clone of your fork](https://help.github.com/articles/cloning-a-repository/) on your local computer. -3. Create a new local branch in your cloned repository. -4. Make changes to the file(s) you want to update in a Markdown editor. - See below for commonly used Markdown editors. -5. [Push your local branch](https://help.github.com/articles/pushing-to-a-remote/) to your fork. -6. [Create a pull request](https://help.github.com/articles/creating-a-pull-request/) to the *staging* branch of the [PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repository. - -## Creating new topics - -If you want to contribute new documentation, first check for [issues tagged as "in progress"](https://github.com/PowerShell/PowerShell-Docs/labels/in%20progress) to make sure you're not duplicating efforts. -If no one seems to be working on what you have planned: - -* Open a new issue and label it as "in progress" (if you are a member of the PowerShell organization) or add "in progress" as a comment to tell others what you're working on -* Follow the same workflow as described above for making major edits to existing topics. -* Edit the `TOC.md` topic (located in the top-level folder for each documentation set) to add your new topics to the table of contents. - Determine where your new topic belongs in the table of contents, and add a heading of the appropriate level, with a link to your topic (`[My topic title](relative path to my topic)`). - -## Markdown editors - -Here are some Markdown editors you can try out: - -* [Visual Studio Code](https://code.visualstudio.com) -* [Markdown Pad](http://markdownpad.com/) -* [Atom](https://atom.io/) -* [Sublime Text](http://www.sublimetext.com/) - - -## GitHub Flavored Markdown (GFM) - -All of the articles in this repository use [GitHub Flavored Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/). - -Some of the basic GFM syntax includes: - -* **Line breaks vs. paragraphs:** In Markdown there is no HTML `
` or `

` element. -Instead, a new paragraph is designated by an empty line between two blocks of text. - -> **Note**: Please add a single newline after each sentence to simplify the command-line output of diffs and history. -This is not currently adopted across all of PowerShell-Docs, but we will be working towards it over time. -Feel free to help out. - -* **Italics:** The HTML `some text` element is written as `*some text*` -* **Bold:** The HTML `some text` element is written as `**some text**` -* **Headings:** HTML headings are designated using `#` characters at the start of the line. - The number of `#` characters corresponds to the hierarchical level of the heading (for example, `#` = `

` and `###` = ```

```). -* **Numbered lists:** To make a numbered (ordered) list start the line with `1. `. - If you want multiple elements within a single list element, format your list as follows: -``` -1. For the first element (like this one), insert a tab stop after the 1. - - To include a second element (like this one), insert a line break after the first and align indentations. -``` -to get this output: - -1. For the first element (like this one), insert a tab stop after the 1. - - To include a second element (like this one), insert a line break after the first and align indentations. - -* **Bulleted lists:** Bulleted (unordered) lists are almost identical to ordered lists except that the `1. ` is replaced with either `* `, `- `, or `+ `. -Multiple element lists work the same way as with ordered lists. -* **Links:** The syntax for a hyperlink is `[visible link text](link URL)`. -* **Link to another topic within the same docset:** A docset is a top-level folder in this repository - (for example, "dsc", "scripting"). - The syntax for a hyperlink to a topic within the same docset is `[topic title](relative path to topic)`. - For more information, see [Relative links in READMEs](https://help.github.com/articles/relative-links-in-readmes/). - To link to a topic in a different top-level folder, use the URL of the published page, as described above. +1. [Get started](./contributing/GETSTARTED.md) +2. [Writing PowerShell documentation](./contributing/WRITING.md) +3. [Style Guide](./contributing/STYLE.md) diff --git a/STYLE.md b/STYLE.md deleted file mode 100644 index ef3c3532fb3..00000000000 --- a/STYLE.md +++ /dev/null @@ -1,93 +0,0 @@ -# Style guide for PowerShell-Docs - - -## Titles/Headings - -* Titles/headings (anything preprended by \#) should be followed with a newline -* Only the first letter of a title and any proper nouns in that title should be capitalized -* Only 1 H1 per document -* When editing reference content, the H2s are prescribed by platyPS and should not be added or removed as it will cause a build break -* Only use \# style headers (as opposed to = or \- style headers) - -### Correct - -``` -# Header 1 - -## Header 2 - -### Header 3 - -``` - -### Incorrect - -``` -Header 1 -======== - -Header 2 --------- - -### Header 3 -``` - -## Terminology - -There are several variants of PowerShell. -This table defines some of the different terms used to discuss PowerShell. - -| Terminology | Definition | -| ----- | -----| -| PowerShell | This is the default. We are shipping PowerShell. The term PowerShell can be legitimately used to indicate any of the particular editions. This can be used to refer to the language, framework and default cmdlets, etc. | -| PowerShell Core (PSCore) | PowerShell built on .NET Core Common Language Runtime (CoreCLR) for any of the platforms. | -| Windows PowerShell | PowerShell built on .NET Common Language Runtime (CLR). Windows PowerShell ships only on Windows and requires the complete CLR. | - -In general, references to "Windows PowerShell" in documentation can be changed to "PowerShell". -"Windows PowerShell" should **not** be changed when Windows-specific technology is being discussed. - -## About_ Files -We are changing the way we process about_ files. -For details, see [issue #1806](https://github.com/PowerShell/PowerShell-Docs/issues/1806). -Until this issue is completed, about_ files will not be properly formatted Markdown issues. -Please do not alter the formatting of about_ files without checking in with a repo maintainer. - -## Syntax - -* When talking about a cmdlet in paragraph, use \` to highlight cmdlet names - * Correct Example: - This `Write-Host` Cmdlet can ... - * Incorrect Example: -  This **Write-Host** Cmdlet can ... and pipeline to out-file Cmdlet to ... -* When writing an article (as opposed to reference content), the first instance of a cmdlet name should be a link to the cmdlet documentation -* All PowerShell syntax blocks should use ```powershell -* Do not start PowerShell commands with "`PS C:\>`" - * Correct Example: - ```powershell - Get-Process - ``` - * Incorrect Example: - ```powershell - PS C:\> Get-Process - ``` -* Output emitted by PowerShell commands should be commented to prevent it from recieving syntax highlighting -* Property names and parameter names should be in **bold** -* PowerShell cmdlets are "[Pascal Cased](https://en.wikipedia.org/wiki/PascalCase)". Verbs are seperated from nouns by a hyphen. - -## Lists - -* Do not end list items with a period (unless they contain multiple sentences) -* If your list contains multiple sentences, consider using a header 3/4/5 (as applicable) underneath your primary idea - -## Links - -* Links are always marked up using MarkDown syntax `[friendlyname](url)` -* Links should have a a friendly name when applicable, most likely the title of the linked page - * **Exception**: Links going towards non-Microsoft sites should only have a URL -* All items in the "related links" section at the bottom should be hyperlinked. - -## Line breaks - -* You must include semantic line breaks -* You should limit lines to 100char (Open item: tooling to help us validate this) -* You CAN remove additional line breaks for PS4+, NOT ps3 (needs validation) diff --git a/contributing/GETSTARTED.md b/contributing/GETSTARTED.md new file mode 100644 index 00000000000..7644e02ea77 --- /dev/null +++ b/contributing/GETSTARTED.md @@ -0,0 +1,67 @@ +# Contributing to PowerShell Documentation + +Thank you for your interest in PowerShell documentation! +See below for details on how you can contribute to our technical documentation. + +>For general information about getting started with Git and GitHub, see [GitHub Help][git-help]. + +## Sign a CLA + +Before you can contribute to any PowerShell repositories, you must sign a +[Microsoft Contribution Licensing Agreement (CLA)][cla]. +If you've already contributed to PowerShell repositories in the past, congratulations! +You've already completed this step. + +## Providing feedback on PowerShell documentation + +You can point out errors, suggest changes, or request new topics by [creating an issue][new-issue] +on the [PowerShell-Docs repository issues page][doc-issues]. + +Issues are reviewed regularly by members of the PowerShell documentation team. +The issues are triaged, assigned, and addressed accordingly. + +## Making minor edits to existing topics + +To [edit an existing file][edit-file], simply navigate to it and click the "Edit" button. +GitHub will automatically create your own fork of our repository where you can make your changes. +Once you're finished, save your edits and submit a [pull request][pull] to the *staging* branch +of the [PowerShell-Docs][docs-repo] repository. +After your pull request is created, someone on the PowerShell documentation team reviews your changes +before merging them into the *staging* branch. + +## Making major edits to existing topics + +If you are making substantial changes to an existing article, adding or changing images, +or contributing a new article, you will need to manually create your GitHub fork, +then clone the fork down to your local computer. +A fork is a GitHub-based replica of the main repository, under your GitHub account, +that provides you with a working copy which you can use in isolation. +You will create pull requests from your fork. +Similarly, a clone is a local-based replica of the repository which, in this case, will be a clone of your fork. +The clone allows you to work on Git repositories offline, and using more powerful native software/tools. + +Here is the workflow for making major edits to existing documentation: + +1. [Create a fork][fork] of the [PowerShell-Docs][docs-repo] repository. +2. [Create a clone of your fork][clone] on your local computer. +3. Create a new local branch in your cloned repository. +4. Make changes to the file(s) you want to update in a Markdown editor. +5. [Push your local branch][push] to your fork. +6. [Create a pull request][pull] to the *staging* branch of the [PowerShell-Docs][docs-repo] repository. + + +## Next steps + +See [Writing PowerShell documentation](WRITING.md). + + +[git-help]: https://help.github.com/ +[cla]: https://cla.microsoft.com/ +[new-issue]: https://help.github.com/articles/creating-an-issue/ +[doc-issues]: https://github.com/PowerShell/PowerShell-Docs/issues +[edit-file]: https://help.github.com/articles/editing-files-in-another-user-s-repository/ +[docs-repo]: https://github.com/PowerShell/PowerShell-Docs +[fork]: https://help.github.com/articles/fork-a-repo/ +[clone]: https://help.github.com/articles/cloning-a-repository/ +[push]: https://help.github.com/articles/pushing-to-a-remote/ +[pull]: https://help.github.com/articles/creating-a-pull-request/ diff --git a/contributing/STYLE.md b/contributing/STYLE.md new file mode 100644 index 00000000000..b2f43ddd55b --- /dev/null +++ b/contributing/STYLE.md @@ -0,0 +1,171 @@ +# Style guide for PowerShell-Docs + +## Product Terminology + +There are several variants of PowerShell. +This table defines some of the different terms used to discuss PowerShell. + +| Terminology | Definition | +| ----- | -----| +| PowerShell | This is the default. We are shipping PowerShell. The term PowerShell can be legitimately used to indicate any of the particular editions. This can be used to refer to the language, framework and default cmdlets, etc. | +| PowerShell Core (PSCore) | PowerShell built on .NET Core Common Language Runtime (CoreCLR) for any of the platforms. | +| Windows PowerShell | PowerShell built on .NET Common Language Runtime (CLR). Windows PowerShell ships only on Windows and requires the complete CLR. | + +In general, references to "Windows PowerShell" in documentation can be changed to "PowerShell". +"Windows PowerShell" should **not** be changed when Windows-specific technology is being discussed. + +## About_ file formatting +We are changing the way we process about_ files. +About_* files are being reformatted for the best compatibility across PowerShell versions and our publishing tools. +For details, see [issue #1806][issue1806]. +Please do not alter the formatting of about_ files without checking in with a repo maintainer. + +Basic formatting guidelines: + +- Limit lines to 80 characters +- Code blocks should be limited to 76 characters +- Within a paragraph, the following characters must be escaped using a leading `\` character: $,\`,\< +- Tables need fit withing 76 characters + - Manually wrap contents of cells across multiple lines + - Use opening and closing `|` characters on each line + - See a working example in [about_Comparison_Operators][about-example] + +## Use semantic line breaks + +Add a single newline after each sentence or a clause boundary near the 100 character limit. +This simplifies the command-line output of diffs and history. + +* You must include semantic line breaks +* Limit lines to 100 characters +* If a sentence is longer than 100 characters, break the line at a clause boundary + near the 100 character limit + +For a good explanation of semantic line breaks, see [Semantic Linefeeds by Rhodes Mill][semantics]. + +This is not currently adopted across all of PowerShell-Docs, but we will be working towards it over time. +Feel free to help out. + +## Blank lines & Spaces vs Tabs + +Remove duplicate blank lines. +Multiple blank lines render as a single blank line in HTML. +Blank lines can also signal the end of a block in Markdown. +There should be a single blank between Markdown blocks of different types (for example, +between a paragraph and a list). + +**NOTE:** Spacing is significant in Markdown. +Always uses spaces instead of hard tabs. +Remove extra spaces at the end of lines. + +## Titles/Headings + +Only use [ATX headings][atx] (as opposed to = or \- style headers). + +* Titles/headings should be surrounded by blank lines +* Only the first letter of a title and any proper nouns in that title should be capitalized +* Only one H1 per document + +When editing reference content, the H2s are prescribed by platyPS and must not be added or removed. +Adding or removing H2 causes a build break. + +## Formatting syntax elements + +* PowerShell cmdlets are "[Pascal Cased][pascal-case]". + Verbs are seperated from nouns by a hyphen. + +* When talking about a cmdlet in paragraph, use \` to highlight cmdlet names + +* Property names and parameter names should be in **bold** + +* When writing an article (as opposed to reference content), the first instance of a cmdlet name should be a link to the cmdlet documentation. + + For example: + + This [`Write-Host`](..\reference\6\Microsoft.PowerShell.Utility\Write-Host.md) cmdlet uses the **-Object** parameter to ... + +## Formatting code blocks + +* All PowerShell syntax blocks should use ```powershell code fence marker. + +* Do **NOT** start PowerShell commands with the PowerShell prompt ("`PS C:\>`"). + +* Avoid using line continuation characters (\`) in PowerShell code examples. + These are a hard to see and can cause problems if there are extra spaces on the end of the line. + +* Output emitted by PowerShell commands should be enclosed in a naked code block to prevent it from recieving syntax highlighting. + + For example: + + ```powershell + Get-Command -Module Microsoft.PowerShell.Security + ``` + + ``` + CommandType Name Version Source + ----------- ---- ------- ------ + Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + ``` + +## Lists + +* Do not end list items with a period (unless they contain multiple sentences) +* If your list contains multiple sentences, consider using a header 3/4/5 (as applicable) underneath your primary idea. + +If you want multiple lines within a single list element, format your list as follows: + +```markdown +1. For the first element (like this one), insert a space after the 1. + + To include a second element (like this one), insert a line break after the first and align indentations. + The indentation of the second element must line up with the first character after the numbered list marker. + +1. The next numbered item starts here. +``` + +to get this output: + +1. For the first element (like this one), insert a space after the 1. + + To include a second element (like this one), insert a line break after the first and align indentations. + The indentation of the second element must line up with the first character after the numbered list marker. + +1. The next numbered item starts here. + +## Links + +* Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url)` +* Links should have a a friendly name when applicable, most likely the title of the linked page + * **Exception**: Links to non-Microsoft sites can be bare URLs +* All items in the "related links" section at the bottom should be hyperlinked. + +## Using relative links + +You should use relative links when linking to other content that is hosted on **docs.microsoft.com**. +When the content is in the same repo, the relative links are simple to calculate. +Note that the path to cmdlet reference is created by our publishing system. +There are special rules for linking to reference topics from conceptual topics. + +\[TO DO\] - document special rules + + +[pascal-case]: https://en.wikipedia.org/wiki/PascalCase +[issue1806]: https://github.com/PowerShell/PowerShell-Docs/issues/1806 +[atx]: https://github.github.com/gfm/#atx-headings +[about-example]: https://github.com/PowerShell/PowerShell-Docs/blob/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +[links]: https://help.github.com/articles/relative-links-in-readmes/ +[gfm-spec]: https://github.github.com/gfm/ +[semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ \ No newline at end of file diff --git a/contributing/WRITING.md b/contributing/WRITING.md new file mode 100644 index 00000000000..4cab0242048 --- /dev/null +++ b/contributing/WRITING.md @@ -0,0 +1,56 @@ +# Writing PowerShell documentation + +One of the easiest ways to contribute to PowerShell is by helping to write and edit documentation. +All of our documentation hosted on GitHub is written using GitHub Flavored Markdown (GFM). + +## Markdown editors + +Here are some Markdown editors you can try out: + +* [Visual Studio Code](https://code.visualstudio.com) +* [Markdown Pad](http://markdownpad.com/) +* [Atom](https://atom.io/) +* [Sublime Text](http://www.sublimetext.com/) + +## Using GitHub Flavored Markdown + +To get started using GFM, see GitHub's Help topics for [Writing on GitHub][gfm-help]. + +**NOTE:** GitHub recently adopted the CommonMark specification (with GFM extensions) for its Markdown syntax. +In the new specification, many spacing rules have changed. +Spaces are significant in GFM. +Do not use hard tabs in Markdown. +For more detailed information about the Markdown specification, see the [GitHub Flavored Markdown Spec][gfm-spec]. + +## Creating new topics + +If you want to contribute new documentation, first check for [issues tagged as "in progress"][labels] +to make sure you're not duplicating efforts. +If no one seems to be working on what you have planned: + +* Open a new issue and label it as "in progress" (if you are a member of the PowerShell organization) + or add "in progress" as a comment to tell others what you're working on. +* Follow the same workflow as described above for making major edits to existing topics. +* Do not edit the `TOC.md` or `TOC.yml` files (located in the top-level folder for each documentation set). +* Create an issue requesting that your new article be added table of contents. + Include a suggestion about where you think it show appear in the TOC. + Someone on the PowerShell documentation team will make the appropriate changes to the TOC files. + +## Updating topics that exist in multiple versions + +Most reference topics are duplicated across all versions of PowerShell. +When reporting an issue about a cmdlet reference or an About_ topic, you must specify which versions are affected by the issue. +The default issue template in GitHub includes a [GFM task list][gfm-task]. +Use the checkboxes in the task list to specify which versions of the content are affected. +When you submit a change to a topic for an issue that affects multiple versions of the content, +you must apply the appropriate change to each version of the file. + +## Next Steps + +Read the [Style Guide](STYLE.md). + + +[gfm-help]: https://help.github.com/categories/writing-on-github/ +[gfm-spec]: https://github.github.com/gfm/ +[labels]: https://github.com/PowerShell/PowerShell-Docs/labels/in%20progress +[gfm-task]: https://github.github.com/gfm/#task-list-items-extension- \ No newline at end of file diff --git a/dsc/configurations.md b/dsc/configurations.md index e6bc1148b6a..fd8a6ef9454 100644 --- a/dsc/configurations.md +++ b/dsc/configurations.md @@ -26,7 +26,8 @@ Configuration MyDscConfiguration { Name = "Bitlocker" } } -} +} +MyDscConfiguration ``` @@ -60,6 +61,7 @@ Configuration MyDscConfiguration { } } } +MyDscConfiguration ``` diff --git a/dsc/secureMOF.md b/dsc/secureMOF.md index 632ff849c62..1fc354b0696 100644 --- a/dsc/secureMOF.md +++ b/dsc/secureMOF.md @@ -217,7 +217,7 @@ Import-Certificate -FilePath "$env:temp\DscPublicKey.cer" -CertStoreLocation Cer ```powershell # Import to the root store so that it is trusted $mypwd = ConvertTo-SecureString -String "YOUR_PFX_PASSWD" -Force -AsPlainText -Import-PfxCertificate -FilePath "$env:temp\DscPrivateKey.pfx" -CertStoreLocation Cert:\LocalMachine\Root -Password $mypwd > $null +Import-PfxCertificate -FilePath "$env:temp\DscPrivateKey.pfx" -CertStoreLocation Cert:\LocalMachine\My -Password $mypwd > $null ``` ## Configuration data diff --git a/dsc/windowsfeatureResource.md b/dsc/windowsfeatureResource.md index 1c560cbafb8..344c32529e6 100644 --- a/dsc/windowsfeatureResource.md +++ b/dsc/windowsfeatureResource.md @@ -31,7 +31,7 @@ WindowsFeature [string] #ResourceName | Property | Description | |---|---| -| Name| Indicates the name of the role or feature that you want to ensure is added or removed. This is the same as the __Name__ property from the [Get-WindowsFeature](https://technet.microsoft.com/en-us/library/jj205469.aspx) cmdlet, and not the display name of the role or feature.| +| Name| Indicates the name of the role or feature that you want to ensure is added or removed. This is the same as the __Name__ property from the [Get-WindowsFeature](/powershell/module/servermanager/Get-WindowsFeature) cmdlet, and not the display name of the role or feature.| | Credential| Indicates the credentials to use to add or remove the role or feature.| | Ensure| Indicates if the role or feature is added. To ensure that the role or feature is added, set this property to "Present" To ensure that the role or feature is removed, set the property to "Absent".| | IncludeAllSubFeature| Set this property to __$true__ to ensure the state of all required subfeatures with the state of the feature you specify with the __Name__ property.| diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md index ab4fb973409..7384d76683c 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -194,8 +194,8 @@ Get-Help about_Functions 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](http://go.microsoft.com/fwlink/?LinkId=143644) -in the Microsoft Developer Network (MSDN) library. +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: @@ -266,3 +266,6 @@ Get-Help Alias - [about_functions](about_functions.md) - [about_profiles](about_profiles.md) - [about_providers](about_providers.md) + + +[aliasinfo]: http://go.microsoft.com/fwlink/?LinkId=143644 \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index 237a0e83b1c..a08a495cb97 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -33,20 +33,29 @@ Beginning in PowerShell 3.0, the `-shr` (shift-right) and `-shl` PowerShell supports the following arithmetic operators: -|Operator|Description|Example| -|--------|-----------|-------| -| + |Adds integers; concatenates strings,
concatenates arrays, and hash tables.|`6 + 2`
`"file" + "name"`
`@(1, "one") + @(2.0, "two")`
`@{"one" = 1} + @{"two" = 2}`| -| - | Subtracts one value from another value | `6 - 2` | -| - | Makes a number a negative number | `-6`
`(Get-Date).AddDays(-1)` | -| * |Multiplies numbers, copies strings and
arrays the specified number of times.|`6 * 2`
`"!" * 3`
`@("!") * 4`| -| / |Divides two values.|`6 / 2`| -| % |Returns the remainder of a division operation.|`7 % 2`| -|-band|Bitwise AND|`5 -band 3`| -|-bnot|Bitwise NOT|`-bnot 5`| -|-bor|Bitwise OR|`5 -bor 0x03`| -|-bxor|Bitwise XOR|`5 -bxor 3`| -|-shl|Shifts bits to the left the specified number of times|`102 -shl 2`| -|-shr|Shifts bits to the right the specified number of times|`102 -shr 2`| +|Operator|Description |Example | +|--------|----------------------------------|-----------------------------| +| + |Adds integers; concatenates |`6 + 2` | +| |strings, arrays, and hash tables. |`"file" + "name"` | +| | |`@(1, "one") + @(2.0, "two")`| +| | |`@{"one" = 1} + @{"two" = 2}`| +| - |Subtracts one value from another |`6 - 2` | +| |value | | +| - |Makes a number a negative number |`-6` | +| | |`(Get-Date).AddDays(-1)` | +| * |Multiply numbers or copy strings |`6 * 2` | +| |and arrays the specified number |`@("!") * 4` | +| |of times. |`"!" * 3` | +| / |Divides two values. |`6 / 2` | +| % |Modulus - returns the remainder of|`7 % 2` | +| |a division operation. | | +|-band |Bitwise AND |`5 -band 3` | +|-bnot |Bitwise NOT |`-bnot 5` | +|-bor |Bitwise OR |`5 -bor 0x03` | +|-bxor |Bitwise XOR |`5 -bxor 3` | +|-shl |Shifts bits to the left the |`102 -shl 2` | +| |specified number of times | | +|-shr |Shifts bits to the right |`102 -shr 2` | The bitwise operators only work on integer types. @@ -54,22 +63,22 @@ The bitwise operators only work on integer types. PowerShell processes arithmetic operators in the following order: -| Precedence | Operator | Description | -|---|---|---| -|1 | `()` | Parentheses| -|2 | `-` | For a negative number or unary operator| -|3 | `*`, `/`, `%` | -|4 | `+`, `-` | For addition and subtraction| +|Precedence|Operator |Description | +|----------|---------------|---------------------------------------| +|1 | `()` |Parentheses | +|2 | `-` |For a negative number or unary operator| +|3 | `*`, `/`, `%` |For muliplication and division | +|4 | `+`, `-` |For addition and subtraction | PowerShell processes the expressions from left to right according to the precedence rules. The following examples show the effect of the precedence rules: -| Expression | Result | -|---|---| -| `3+6/3*4` | `11` | -|`3+6/(3*4)` | `3.5` | -|`(3+6)/3*4` | `12` | +|Expression |Result| +|-----------|------| +|`3+6/3*4` |`11` | +|`3+6/(3*4)`|`3.5` | +|`(3+6)/3*4`|`12` | The order in which PowerShell evaluates expressions might differ from other programming and scripting languages that you have used. The following @@ -110,10 +119,10 @@ nearest even integer. The following example shows the effect of rounding to the nearest even integer. -| Expression | Result | -|---|---| -|`[int]( 5 / 2 )` | `2` | -|`[int]( 7 / 2 )` | `4` | +|Expression |Result| +|----------------|------| +|`[int]( 5 / 2 )`|`2` | +|`[int]( 7 / 2 )`|`4` | Notice how **_5/2_ = 2.5** gets rounded to **2**. But, **_7/2_ = 3.5** gets rounded to **4**. @@ -159,13 +168,13 @@ The following examples demonstrate the use of the addition and multiplication operators; in operations that include different object types. Assume `$array = 1,2,3`: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`$array + 16` | `1`
`2`
`3`
`16`| -|`$array + "file"` | `1`
`2`
`3`
`file`| -|`$array * 2` | `1`
`2`
`3`
`1`
`2`
`3`| -|`"file" * 3` | `filefilefile`| +|Expression |Result | +|-----------------|-----------------------| +|`"file" + 16` |`file16` | +|`$array + 16` |`1`,`2`,`3`,`16` | +|`$array + "file"`|`1`,`2`,`3`,`file` | +|`$array * 2` |`1`,`2`,`3`,`1`,`2`,`3`| +|`"file" * 3` |`filefilefile` | Because the method that is used to evaluate statements is determined by the leftmost object, addition and multiplication in PowerShell are not strictly @@ -174,10 +183,13 @@ commutative. For example, `(a + b)` does not always equal `(b + a)`, and The following examples demonstrate this principle: -| Expression | Result | -|---|---| -|`"file" + 16` | `file16`| -|`16 + "file"` | `Cannot convert value "file" to type "System.Int32".`
`Error: "Input string was not in a correct format."`
`At line:1 char:1`
`+ 16 + "file"`| +|Expression |Result | +|-------------|-----------------------------------------------------| +|`"file" + 16`|`file16` | +|`16 + "file"`|`Cannot convert value "file" to type "System.Int32".`| +| |`Error: "Input string was not in a correct format."` | +| |`At line:1 char:1` | +| |+ 16 + "file"` | Hash tables are a slightly different case. You can add hash tables to another hash table, as long as, the added hash tables don't have duplicate @@ -325,10 +337,11 @@ Decimal type, the result will be of the Decimal type. If the result is too large for the Decimal type, it will not be cast to Double. Instead, an error results. -| Expression | Result | -|---|---| -|`[Decimal]::maxvalue` | `79228162514264337593543950335`| -|`[Decimal]::maxvalue + 1` | `Value was either too large`
`or too small for a Decimal.`| +|Expression |Result | +|-------------------------|-----------------------------------------------| +|`[Decimal]::maxvalue` |`79228162514264337593543950335` | +|`[Decimal]::maxvalue + 1`|`Value was either too large or too small for a`| +| |`Decimal.` | ## ARITHMETIC OPERATORS AND VARIABLES @@ -336,10 +349,10 @@ You can also use arithmetic operators with variables. The operators act on the values of the variables. The following examples demonstrate the use of arithmetic operators with variables: -| Expression | Result | -|---|---| -|`$intA = 6`
`$intB = 4`
`$intA + $intB` | `10`| -|`$a = "Power"`
`$b = "Shell"`
`$a + $b` | `PowerShell`| +| Expression |Result | +|-----------------------------------------------|------------| +|`$intA = 6`
`$intB = 4`
`$intA + $intB`|`10` | +|`$a = "Power"`
`$b = "Shell"`
`$a + $b`|`PowerShell`| ## ARITHMETIC OPERATORS AND COMMANDS @@ -377,27 +390,6 @@ In the above expression, each process working space (`$_.ws`) is multiplied by `2`; and, the result, compared against `50mb` to see if it is greater than that. -### EXAMPLES - -The following examples show how to use the arithmetic operators in -PowerShell: - -|Expression|Result| -|----------|------| -|`1 + 1` | `2` | -|`1 - 1` | `0` | -|`-(6 + 3)`| `-9` | -|`6 * 2` | `12` | -|`7 / 2` | `3.5`| -|`7 % 2` | `1` | -|`'w' * 3` | `www`| -|`3 * 'w'` | `Cannot convert value "w" to type "System.Int32".`
` Error: "Input string was not in a correct format."`| -|`"Power" + "Shell"` | `PowerShell`| -|`$a = "Power" + "Shell"`
`$a[5]` | `S`| -|`$b = 1,2,3`
`$b + 4` | `1`
`2`
`3`
`4`| -|`$servers = @{`
  `0 = "LocalHost"`
  `1 = "Server01"`
  `2 = "Server02"`
`}`
`$servers + @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| -|`#Use assignment operator`
`$servers += @{3 = "Server03"}` | `Name Value`
`---- -----`
`3 Server03`
`2 Server02`
`1 Server01`
`0 LocalHost`| - ## Bitwise Operators PowerShell supports the standard bitwise operators, including bitwise-AND @@ -484,11 +476,11 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shl 0` | 21 | 0001 0101 | -|`21 -shl 1` | 42 | 0010 1010 | -|`21 -shl 2` | 84 | 0101 0100 | +|Expression |Result|Binary Result| +|-----------|------|-------------| +|`21 -shl 0`|21 |0001 0101 | +|`21 -shl 1`|42 |0010 1010 | +|`21 -shl 2`|84 |0101 0100 | In a bitwise shift-right operation, all bits are moved "n" places to the right, where "n" is specified by the right operand. The shift-right @@ -501,19 +493,19 @@ right operand determine how many bits of the left operand are shifted. When the left operand is a Long (64-bit) value, the lower 6 bits of the right operand determine how many bits of the left operand are shifted. -| Expression | Result | Binary Result | -|---|---|---| -|`21 -shr 0` | 21 | 0001 0101 | -|`21 -shr 1` | 10 | 0000 1010 | -|`21 -shr 2` | 5 | 0000 0101 | -|`21 -shr 31` | 0 | 0000 0000 | -|`21 -shr 32` | 21 | 0001 0101 | -|`21 -shr 64` | 21 | 0001 0101 | -|`21 -shr 65` | 10 | 0000 1010 | -|`21 -shr 66` | 5 | 0000 0101 | -|`[int]::MaxValue -shr 1` | 1073741823 | 0011 1111 1111 1111 1111 1111 1111 1111 | -|`[int]::MinValue -shr 1` | -1073741824 | 1100 0000 0000 0000 0000 0000 0000 0000 | -|`-1 -shr 1` | -1 | 1111 1111 1111 1111 1111 1111 1111 1111 | +|Expression |Result |Binary |Hex | +|------------------------|------------|-----------|------------| +|`21 -shr 0` | 21 | 0001 0101 | 0x15 | +|`21 -shr 1` | 10 | 0000 1010 | 0x0A | +|`21 -shr 2` | 5 | 0000 0101 | 0x05 | +|`21 -shr 31` | 0 | 0000 0000 | 0x00 | +|`21 -shr 32` | 21 | 0001 0101 | 0x15 | +|`21 -shr 64` | 21 | 0001 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x15 | +|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | +|`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | +|`-1 -shr 1` | -1 | | 0xFFFFFFFF | ## SEE ALSO diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index 0f8a7fb028c..34af56c3eab 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-24 +ms.date: 2017-11-27 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators @@ -18,16 +18,21 @@ perform numeric operations on the values before the assignment. Windows PowerShell supports the following assignment operators. -| Operator | Description | -| ------- | ----------- | -| = | Sets the value of a variable to the specified value. | -| += | Increases the value of a variable by the specified value, or appends the specified value to the existing value. | -|-= | Decreases the value of a variable by the specified value. | -| *= | Multiplies the value of a variable by the specified value, or appends the specified value to the existing value. | -| /= | Divides the value of a variable by the specified value. | -| %= | Divides the value of a variable by the specified value and then assigns the remainder (modulus) to the variable. | -| ++ | Increases the value of a variable, assignable property, or array element by 1. | -| -- | Decreases the value of a variable, assignable property, or array element by 1. | +|Operator|Description | +|--------|-------------------------------------------------------------| +|= |Sets the value of a variable to the specified value. | +|+= |Increases the value of a variable by the specified value, or | +| |appends the specified value to the existing value. | +|-= |Decreases the value of a variable by the specified value. | +|*= |Multiplies the value of a variable by the specified value, or| +| |appends the specified value to the existing value. | +|/= |Divides the value of a variable by the specified value. | +|%= |Divides the value of a variable by the specified value and | +| |then assigns the remainder (modulus) to the variable. | +|++ |Increases the value of a variable, assignable property, or | +| |array element by 1. | +|-- |Decreases the value of a variable, assignable property, or | +| |array element by 1. | ## SYNTAX @@ -335,8 +340,8 @@ $a You cannot use the `-=` operator to delete the values of a variable. To delete all the values that are assigned to a variable, use the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) or -[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) cmdlets -to assign a value of `$null` or `""` to the variable. +[Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) +cmdlets to assign a value of `$null` or `""` to the variable. ```powershell $a = $null diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 85f7b056746..0fe7b2fae3a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -251,7 +251,8 @@ were ignored. ```powershell $calendar = @($null, $null, “Meeting”, $null, $null, “Team Lunch”, $null) -$days = Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" +$days = "Sunday","Monday","Tuesday","Wednesday","Thursday", + "Friday","Saturday" $currentDay = 0 foreach($day in $calendar) { diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 223cd9bdde4..2c2792134da 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -17,10 +17,11 @@ Describes how to write comment-based help topics for functions and scripts. You can write comment-based help topics for functions and scripts by using special help comment keywords. -The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same format in which -it displays the cmdlet help topics that are generated from XML files. Users -can use all of the parameters of `Get-Help`, such as **Detailed**, **Full**, **Example**, -and **Online**, to display the contents of comment-based help. +The [Get-Help](../Get-Help.md) cmdlet displays comment-based help in the same +format in which it displays the cmdlet help topics that are generated from XML +files. Users can use all of the parameters of `Get-Help`, such as +**Detailed**, **Full**, **Example**, and **Online**, to display the contents +of comment-based help. You can also write XML-based help files for functions and scripts. To enable the `Get-Help` cmdlet to find the XML-based help file for a function @@ -31,8 +32,9 @@ This topic explains how to write help topics for functions and scripts. For information about how to display help topics for functions and scripts, see `Get-Help`. -The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets work only on XML files. Updatable Help -does not support comment-based help topics. +The [Update-Help](../Update-Help.md) and [Save-Help](../Save-Help.md) cmdlets +work only on XML files. Updatable Help does not support comment-based help +topics. ## SYNTAX FOR COMMENT-BASED HELP @@ -52,8 +54,10 @@ or #> ``` -Comment-based help is written as a series of comments. You can type a -comment symbol `#` before each line of comments, or you can use the `<#` and `#>` symbols to create a comment block. All the lines within the comment block are interpreted as comments. +Comment-based help is written as a series of comments. You can type a comment +symbol `#` before each line of comments, or you can use the `<#` and `#>` +symbols to create a comment block. All the lines within the comment block are +interpreted as comments. All of the lines in a comment-based help topic must be contiguous. If a comment-based help topic follows a comment that is not part of the help @@ -84,10 +88,9 @@ multiple lines. Comment-based help for a function can appear in one of three locations: - At the beginning of the function body. - - At the end of the function body. - -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword. +- Before the Function keyword. There cannot be more than one blank line + between the last line of the function help and the Function keyword. For example: @@ -132,11 +135,17 @@ function Get-Function { } Comment-based help for a script can appear in one of the following two locations in the script. -- At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. +- At the beginning of the script file. Script help can be preceded in the + script only by comments and blank lines. -- If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. +- If the first item in the script body (after the help) is a function + declaration, there must be at least two blank lines between the end of the + script help and the function declaration. Otherwise, the help is interpreted + as being help for the function, not help for the script. -- At the end of the script file. However, if the script is signed, place Comment-based help at the beginning of the script file. The end of the script is occupied by the signature block. +- At the end of the script file. However, if the script is signed, place + Comment-based help at the beginning of the script file. The end of the script + is occupied by the signature block. For example: @@ -162,14 +171,13 @@ function Get-Function { } ## SYNTAX FOR COMMENT-BASED HELP IN SCRIPT MODULES -In a script module `.psm1`, comment-based help uses the syntax -for functions, not the syntax for scripts. You cannot use the -script syntax to provide help for all functions defined in a -script module. +In a script module `.psm1`, comment-based help uses the syntax for functions, +not the syntax for scripts. You cannot use the script syntax to provide help +for all functions defined in a script module. -For example, if you are using the "ExternalHelp" keyword to -identify the XML-based help files for the functions in a script -module, you must add an "ExternalHelp" comment to each function. +For example, if you are using the "ExternalHelp" keyword to identify the +XML-based help files for the functions in a script module, you must add an +"ExternalHelp" comment to each function. ```powershell .ExternalHelp @@ -182,10 +190,10 @@ function ## COMMENT-BASED HELP KEYWORDS -The following are valid comment-based help keywords. They are listed in the order in -which they typically appear in a help topic along with their intended use. -These keywords can appear in any order in the comment-based help, and they -are not case-sensitive. +The following are valid comment-based help keywords. They are listed in the +order in which they typically appear in a help topic along with their intended +use. These keywords can appear in any order in the comment-based help, and +they are not case-sensitive. ### .SYNOPSIS @@ -199,45 +207,44 @@ used only once in each topic. ### .PARAMETER -The description of a parameter. Add a ".PARAMETER" keyword for -each parameter in the function or script syntax. +The description of a parameter. Add a ".PARAMETER" keyword for each parameter +in the function or script syntax. -Type the parameter name on the same line as the ".PARAMETER" keyword. -Type the parameter description on the lines following the ".PARAMETER" -keyword. Windows PowerShell interprets all text between the ".PARAMETER" -line and the next keyword or the end of the comment block as part of -the parameter description. The description can include paragraph breaks. +Type the parameter name on the same line as the ".PARAMETER" keyword. Type the +parameter description on the lines following the ".PARAMETER" keyword. Windows +PowerShell interprets all text between the ".PARAMETER" line and the next +keyword or the end of the comment block as part of the parameter description. +The description can include paragraph breaks. ``` .PARAMETER ``` -The Parameter keywords can appear in any order in the comment block, but -the function or script syntax determines the order in which the parameters -(and their descriptions) appear in help topic. To change the order, -change the syntax. +The Parameter keywords can appear in any order in the comment block, but the +function or script syntax determines the order in which the parameters (and +their descriptions) appear in help topic. To change the order, change the +syntax. You can also specify a parameter description by placing a comment in the -function or script syntax immediately before the parameter variable name. -If you use both a syntax comment and a Parameter keyword, the description +function or script syntax immediately before the parameter variable name. If +you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored. ### .EXAMPLE -A sample command that uses the function or script, optionally followed -by sample output and a description. Repeat this keyword for each example. +A sample command that uses the function or script, optionally followed by +sample output and a description. Repeat this keyword for each example. ### .INPUTS The Microsoft .NET Framework types of objects that can be piped to the -function or script. You can also include a description of the input -objects. +function or script. You can also include a description of the input objects. ### .OUTPUTS -The .NET Framework type of the objects that the cmdlet returns. You can -also include a description of the returned objects. +The .NET Framework type of the objects that the cmdlet returns. You can also +include a description of the returned objects. ### .NOTES @@ -245,24 +252,24 @@ Additional information about the function or script. ### .LINK -The name of a related topic. The value appears on the line below -the ".LINK" keyword and must be preceded by a comment symbol `#` or -included in the comment block. +The name of a related topic. The value appears on the line below the ".LINK" +keyword and must be preceded by a comment symbol `#` or included in the +comment block. Repeat the ".LINK" keyword for each related topic. This content appears in the Related Links section of the help topic. The "Link" keyword content can also include a Uniform Resource Identifier -(URI) to an online version of the same help topic. The online version -opens when you use the **Online** parameter of `Get-Help`. The URI must begin -with "http" or "https". +(URI) to an online version of the same help topic. The online version opens +when you use the **Online** parameter of `Get-Help`. The URI must begin with +"http" or "https". ### .COMPONENT -The technology or feature that the function or script uses, or to which -it is related. This content appears when the `Get-Help` command includes -the **Component** parameter of `Get-Help`. +The technology or feature that the function or script uses, or to which it is +related. This content appears when the `Get-Help` command includes the +**Component** parameter of `Get-Help`. ### .ROLE @@ -276,9 +283,9 @@ command includes the **Functionality** parameter of `Get-Help`. ### .FORWARDHELPTARGETNAME -Redirects to the help topic for the specified command. You can redirect -users to any help topic, including help topics for a function, script, -cmdlet, or provider. +Redirects to the help topic for the specified command. You can redirect users +to any help topic, including help topics for a function, script, cmdlet, or +provider. ``` .FORWARDHELPTARGETNAME @@ -286,10 +293,10 @@ cmdlet, or provider. ### .FORWARDHELPCATEGORY -Specifies the help category of the item in "ForwardHelpTargetName". -Valid values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", -"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use this -keyword to avoid conflicts when there are commands with the same name. +Specifies the help category of the item in "ForwardHelpTargetName". Valid +values are "Alias", "Cmdlet", "HelpFile", "Function", "Provider", "General", +"FAQ", "Glossary", "ScriptCommand", "ExternalScript", "Filter", or "All". Use +this keyword to avoid conflicts when there are commands with the same name. ``` .FORWARDHELPCATEGORY @@ -298,7 +305,8 @@ keyword to avoid conflicts when there are commands with the same name. ### .REMOTEHELPRUNSPACE Specifies a session that contains the help topic. Enter a variable that -contains a "PSSession". This keyword is used by the [Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) +contains a "PSSession". This keyword is used by the +[Export-PSSession](../../Microsoft.PowerShell.Utility/Export-PSSession.md) cmdlet to find the help topics for the exported commands. ``` @@ -313,34 +321,35 @@ Specifies an XML-based help file for the script or function. .EXTERNALHELP ``` -The "ExternalHelp" keyword is required when a function or script -is documented in XML files. Without this keyword, `Get-Help` cannot -find the XML-based help file for the function or script. +The "ExternalHelp" keyword is required when a function or script is documented +in XML files. Without this keyword, `Get-Help` cannot find the XML-based help +file for the function or script. -The "ExternalHelp" keyword takes precedence over other comment-based -help keywords. If "ExternalHelp" is present, `Get-Help` does not display -comment-based help, even if it cannot find a help topic that matches -the value of the "ExternalHelp" keyword. +The "ExternalHelp" keyword takes precedence over other comment-based help +keywords. If "ExternalHelp" is present, `Get-Help` does not display +comment-based help, even if it cannot find a help topic that matches the value +of the "ExternalHelp" keyword. -If the function is exported by a module, set the value of the -"ExternalHelp" keyword to a file name without a path. `Get-Help` looks for -the specified file name in a language-specific subdirectory of the module -directory. There are no requirements for the name of the XML-based help -file for a function, but a best practice is to use the following format: +If the function is exported by a module, set the value of the "ExternalHelp" +keyword to a file name without a path. `Get-Help` looks for the specified file +name in a language-specific subdirectory of the module directory. There are no +requirements for the name of the XML-based help file for a function, but a +best practice is to use the following format: ``` -help.xml ``` -If the function is not included in a module, include a path to the -XML-based help file. If the value includes a path and the path contains +If the function is not included in a module, include a path to the XML-based +help file. If the value includes a path and the path contains UI-culture-specific subdirectories, `Get-Help` searches the subdirectories recursively for an XML file with the name of the script or function in -accordance with the language fallback standards established for Windows, -just as it does in a module directory. +accordance with the language fallback standards established for Windows, just +as it does in a module directory. -For more information about the cmdlet help XML-based help file format, -see [How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in the MSDN library. +For more information about the cmdlet help XML-based help file format, see +[How to Write Cmdlet Help](https://go.microsoft.com/fwlink/?LinkID=123415) in +the MSDN library. ## AUTOGENERATED CONTENT @@ -349,41 +358,40 @@ parameters, and remarks are automatically generated by the `Get-Help` cmdlet. ### Name -The "Name" section of a function help topic is taken from the function -name in the function syntax. The "Name" of a script help topic is -taken from the script file name. To change the name or its -capitalization, change the function syntax or the script file name. +The "Name" section of a function help topic is taken from the function name in +the function syntax. The "Name" of a script help topic is taken from the +script file name. To change the name or its capitalization, change the +function syntax or the script file name. ### Syntax -The "Syntax" section of the help topic is generated from the function -or script syntax. To add detail to the help topic syntax, such as -the .NET Framework type of a parameter, add the detail to the syntax. -If you do not specify a parameter type, the "Object" type is -inserted as the default value. +The "Syntax" section of the help topic is generated from the function or +script syntax. To add detail to the help topic syntax, such as the .NET +Framework type of a parameter, add the detail to the syntax. If you do not +specify a parameter type, the "Object" type is inserted as the default value. ### Parameter List -The "Parameter list" in the help topic is generated from the function -or script syntax and from the descriptions that you add by using the -"Parameters" keyword. The function parameters appear in the "Parameters" -section of the help topic in the same order that they appear in -the function or script syntax. The spelling and capitalization of -parameter names is also taken from the syntax; it is not affected -by the parameter name specified by the "Parameter" keyword. +The "Parameter list" in the help topic is generated from the function or +script syntax and from the descriptions that you add by using the "Parameters" +keyword. The function parameters appear in the "Parameters" section of the +help topic in the same order that they appear in the function or script +syntax. The spelling and capitalization of parameter names is also taken from +the syntax; it is not affected by the parameter name specified by the +"Parameter" keyword. ### Common Parameters -The "Common parameters" are added to the syntax and parameter list -of the help topic, even if they have no effect. For more information -about the common parameters, see [about_CommonParameters](about_CommonParameters.md). +The "Common parameters" are added to the syntax and parameter list of the help +topic, even if they have no effect. For more information about the common +parameters, see [about_CommonParameters](about_CommonParameters.md). ### Parameter Attribute Table -`Get-Help` generates the table of parameter attributes that appears -when you use the **Full** or **Parameter** parameter of `Get-help`. The value -of the "Required", "Position", and "Default" value attributes is taken -from the function or script syntax. +`Get-Help` generates the table of parameter attributes that appears when you +use the **Full** or **Parameter** parameter of `Get-help`. The value of the +"Required", "Position", and "Default" value attributes is taken from the +function or script syntax. Default values and a value for "Accept Wildcard characters" do not appear in the "Parameter attribute table" even when they are defined in the function or @@ -391,21 +399,19 @@ script. To help users, provide this information in the parameter description. ### Remarks -The "Remarks" section of the help topic is automatically generated -from the function or script name. You cannot change or affect its -content. +The "Remarks" section of the help topic is automatically generated from the +function or script name. You cannot change or affect its content. ## DISABLING COMMENT-BASED HELP -[This technique was suggested by Rich Prescott, a Windows engineer -from New York, NY.] +[This technique was suggested by Rich Prescott, a Windows engineer from New +York, NY.] -You can disable comment-based help. This makes the comment-based -help ineffective without deleting it. +You can disable comment-based help. This makes the comment-based help +ineffective without deleting it. -To disable comment-based help, enclose the comments in a here-string. To -hide the here-string, assign it to a variable or pipe it to the Out-Null -cmdlet. +To disable comment-based help, enclose the comments in a here-string. To hide +the here-string, assign it to a variable or pipe it to the Out-Null cmdlet. While it is disabled, the comment-based help has no effect. @@ -425,8 +431,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To disable the comment-based help, enclose it in a here-string, -as shown in the following example. +To disable the comment-based help, enclose it in a here-string, as shown in +the following example. ```powershell @" @@ -445,10 +451,9 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -To hide the disabled comment-based help, assign the here-string to -a local variable that is not otherwise used in the function, as -shown in the following example. You can also pipe it to the [Out-Null](../Out-Null.md) -cmdlet. +To hide the disabled comment-based help, assign the here-string to a local +variable that is not otherwise used in the function, as shown in the following +example. You can also pipe it to the [Out-Null](../Out-Null.md) cmdlet. ```powershell $x = @" @@ -467,7 +472,8 @@ param ([string]$Name,[string]$Extension = "txt") } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ## EXAMPLES @@ -504,7 +510,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension +or file name. .EXAMPLE @@ -549,11 +556,13 @@ Adds a file name extension to a supplied name. SYNTAX -Add-Extension [[-Name] ] [[-Extension] ] [] +Add-Extension [[-Name] ] [[-Extension] ] +[] DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. PARAMETERS @@ -586,7 +595,8 @@ None. You cannot pipe objects to Add-Extension. OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. Example 1 @@ -612,8 +622,8 @@ Set-Item - Parameter Descriptions in Function Syntax This example is the same as the previous one, except that the parameter -descriptions are inserted in the function syntax. This format is most -useful when the descriptions are brief. +descriptions are inserted in the function syntax. This format is most useful +when the descriptions are brief. ```powershell function Add-Extension @@ -640,7 +650,8 @@ Adds a file name extension to a supplied name. .DESCRIPTION -Adds a file name extension to a supplied name. Takes any strings for the file name or extension. +Adds a file name extension to a supplied name. Takes any strings for the +file name or extension. .INPUTS @@ -648,7 +659,8 @@ None. You cannot pipe objects to Add-Extension. .OUTPUTS -System.String. Add-Extension returns a string with the extension or file name. +System.String. Add-Extension returns a string with the extension or +file name. .EXAMPLE @@ -678,12 +690,12 @@ Set-Item - Comment-based Help for a Script -The following sample script includes comment-based help. -Notice the blank lines between the closing "#>" and the "Param" statement. -In a script that does not have a Param statement, there must be at least -two blank lines between the final comment in the help topic and the first -function declaration. Without these blank lines, `Get-Help` associates the -help topic with the function, not the script. +The following sample script includes comment-based help. Notice the blank +lines between the closing "#>" and the "Param" statement. In a script that +does not have a Param statement, there must be at least two blank lines +between the final comment in the help topic and the first function +declaration. Without these blank lines, `Get-Help` associates the help topic +with the function, not the script. ```powershell <# @@ -722,7 +734,8 @@ C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv +C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +C:\Reports\2009\January.csv #> param ([string]$InputPath, [string]$OutPutPath) @@ -731,9 +744,9 @@ function Get-Data { } ... ``` -The following command gets the script help. Because the script is not -in a directory that is listed in the "Path" environment variable, the -`Get-Help` command that gets the script help must specify the script path. +The following command gets the script help. Because the script is not in a +directory that is listed in the "Path" environment variable, the `Get-Help` +command that gets the script help must specify the script path. ```powershell Get-Help -Path .\update-month.ps1 -Full @@ -813,12 +826,12 @@ C:\Reports\2009\January.csv - Redirecting to an XML File You can write XML-based help topics for functions and scripts. Although -comment-based help is easier to implement, XML-based help is required -for Updatable Help and to provide help topics in multiple languages. +comment-based help is easier to implement, XML-based help is required for +Updatable Help and to provide help topics in multiple languages. The following example shows the first few lines of the Update-Month.ps1 -script. The script uses the "ExternalHelp" keyword to specify the path to -an XML-based help topic for the script. +script. The script uses the "ExternalHelp" keyword to specify the path to an +XML-based help topic for the script. Note that the value of the "ExternalHelp" keyword appears on the same line as the keyword. Any other placement is ineffective. @@ -831,7 +844,8 @@ function Get-Data { } ... ``` -The following examples show three valid placements of the "ExternalHelp" keyword in a function. +The following examples show three valid placements of the "ExternalHelp" +keyword in a function. ```powershell function Add-Extension @@ -867,10 +881,10 @@ $name - Redirecting to a Different Help Topic -The following code is an excerpt from the beginning of the built-in -help function in Windows PowerShell, which displays one screen of help -text at a time. Because the help topic for the `Get-Help` cmdlet describes -the help function, the help function uses the "ForwardHelpTargetName" and +The following code is an excerpt from the beginning of the built-in help +function in Windows PowerShell, which displays one screen of help text at a +time. Because the help topic for the `Get-Help` cmdlet describes the help +function, the help function uses the "ForwardHelpTargetName" and "ForwardHelpCategory" keywords to redirect the user to the `Get-Help` cmdlet help topic. diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 4d6610ec506..c7950b31389 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -498,8 +498,8 @@ Are you sure you want to perform this action? Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is -"Y"): s +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default +is "Y"): s PS C:\ps-test> Get-Help New-Item -Parameter ItemType @@ -516,8 +516,10 @@ PS C:\ps-test> exit Confirm Are you sure you want to perform this action? -Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt". -[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y +Performing operation "Create File" on Target "Destination: C:\ps-test\test +.txt". +[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (defau +lt is "Y"): y Directory: C:\ps-test diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md index de2e650f230..94e46f9d56e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,39 +10,39 @@ title: about_Eventlogs ## Short Description -Windows PowerShell creates a Windows event log that is -named "Windows PowerShell" to record Windows PowerShell events. You can -view this log in Event Viewer or by using cmdlets that get events, such as -the `Get-EventLog` cmdlet. By default, Windows PowerShell engine and provider -events are recorded in the event log, but you can use the event log -preference variables to customize the event log. For example, you can add -events about Windows PowerShell commands. +Windows PowerShell creates a Windows event log that is named "Windows +PowerShell" to record Windows PowerShell events. You can view this log in +Event Viewer or by using cmdlets that get events, such as the `Get-EventLog` +cmdlet. By default, Windows PowerShell engine and provider events are recorded +in the event log, but you can use the event log preference variables to +customize the event log. For example, you can add events about Windows +PowerShell commands. ## Long Description The Windows PowerShell event log records details of Windows PowerShell -operations, such as starting and stopping the program engine and starting -and stopping the Windows PowerShell providers. You can also log details -about Windows PowerShell commands. +operations, such as starting and stopping the program engine and starting and +stopping the Windows PowerShell providers. You can also log details about +Windows PowerShell commands. The Windows PowerShell event log is in the Application and Services Logs -group. The Windows PowerShell log is a classic event log that does not use -the Windows Eventing technology. To view the log, use the cmdlets designed -for classic event logs, such as `Get-EventLog`. +group. The Windows PowerShell log is a classic event log that does not use the +Windows Eventing technology. To view the log, use the cmdlets designed for +classic event logs, such as `Get-EventLog`. ## Viewing the Windows PowerShell Event Log -You can view the Windows PowerShell event log in Event Viewer or by -using the `Get-EventLog` and `Get-WmiObject` cmdlets. To view the contents -of the Windows PowerShell log, type: +You can view the Windows PowerShell event log in Event Viewer or by using the +`Get-EventLog` and `Get-WmiObject` cmdlets. To view the contents of the +Windows PowerShell log, type: ```powershell Get-EventLog -LogName "Windows PowerShell" ``` -To examine the events and their properties, use the `Sort-Object` cmdlet, -the `Group-Object` cmdlet, and the cmdlets that contain the `Format` verb -(the `Format` cmdlets). +To examine the events and their properties, use the `Sort-Object` cmdlet, the +`Group-Object` cmdlet, and the cmdlets that contain the `Format` verb (the +`Format` cmdlets). For example, to view the events in the log grouped by the event ID, type: @@ -54,8 +54,8 @@ Or, type: ```powershell Get-EventLog "Windows PowerShell" | - Sort-Object EventID | - Group-Object EventID + Sort-Object EventID | + Group-Object EventID ``` To view all the classic event logs, type: @@ -64,14 +64,14 @@ To view all the classic event logs, type: Get-EventLog -List ``` -You can also use the `Get-WmiObject` cmdlet to use the event-related -Windows Management Instumentation (WMI) classes to examine the event log. -For example, to view all the properties of the event log file, type: +You can also use the `Get-WmiObject` cmdlet to use the event-related Windows +Management Instumentation (WMI) classes to examine the event log. For example, +to view all the properties of the event log file, type: ```powershell Get-WmiObject Win32_NTEventlogFile | - where LogFileName -EQ "Windows PowerShell" | - Format-List -Property * + where LogFileName -EQ "Windows PowerShell" | + Format-List -Property * ``` To find the Win32 event-related WMI classes, type: @@ -85,28 +85,27 @@ For more information, type "Get-Help Get-EventLog" and ## Selecting Events for the Windows PowerShell Event Log -You can use the event log preference variables to determine which events -are recorded in the Windows PowerShell event log. +You can use the event log preference variables to determine which events are +recorded in the Windows PowerShell event log. -There are six event log preference variables; two variables for each of -the three logging components: the engine (the Windows PowerShell -program), the providers, and the commands. The LifeCycleEvent variables -log normal starting and stopping events. The Health variables log error -events. +There are six event log preference variables; two variables for each of the +three logging components: the engine (the Windows PowerShell program), the +providers, and the commands. The LifeCycleEvent variables log normal starting +and stopping events. The Health variables log error events. The following table lists the event log preference variables. -| Variable | Description | -| -------------------------- | ---------------------------------------------------------- | -| $LogEngineLifeCycleEvent | Logs starting and stopping of Windows PowerShell | -| $LogEngineHealthEvent | Logs Windows PowerShell program errors | -| $LogProviderLifeCycleEvent | Logs starting and stopping of Windows PowerShell providers | -| $LogProviderHealthEvent | Logs Windows PowerShell provider errors | -| $LogCommandLifeCycleEvent | Logs starting and completion of commands | -| $LogCommandHealthEvent | Logs command errors | +|Variable |Description | +|--------------------------|-----------------------------------------------| +|$LogEngineLifeCycleEvent |Logs the start and stop of PowerShell | +|$LogEngineHealthEvent |Logs PowerShell program errors | +|$LogProviderLifeCycleEvent|Logs the start and stop of PowerShell providers| +|$LogProviderHealthEvent |Logs PowerShell provider errors | +|$LogCommandLifeCycleEvent |Logs the starting and completion of commands | +|$LogCommandHealthEvent |Logs command errors | -(For information about Windows PowerShell providers, -see [about_Providers](about_Providers.md).) +(For information about Windows PowerShell providers, see +[about_Providers](about_Providers.md).) By default, only the following event types are enabled: @@ -115,8 +114,8 @@ By default, only the following event types are enabled: * $LogProviderLifeCycleEvent * $LogProviderHealthEvent -To enable an event type, set the preference variable for that event type -to $true. For example, to enable command life-cycle events, type: +To enable an event type, set the preference variable for that event type to +$true. For example, to enable command life-cycle events, type: ```powershell $LogCommandLifeCycleEvent @@ -128,35 +127,36 @@ Or, type: $LogCommandLifeCycleEvent = $true ``` -To disable an event type, set the preference variable for that event type -to $false. For example, to disable command life-cycle events, type: +To disable an event type, set the preference variable for that event type to +$false. For example, to disable command life-cycle events, type: ```powershell $LogProviderLifeCycleEvent = $false ``` You can disable any event, except for the events that indicate that the -Windows PowerShell engine and the core providers are started. These events -are generated before the Windows PowerShell profiles are run and before -the host program is ready to accept commands. +Windows PowerShell engine and the core providers are started. These events are +generated before the Windows PowerShell profiles are run and before the host +program is ready to accept commands. -The variable settings apply only for the current Windows PowerShell -session. To apply them to all Windows PowerShell sessions, add them to -your Windows PowerShell profile. +The variable settings apply only for the current Windows PowerShell session. +To apply them to all Windows PowerShell sessions, add them to your Windows +PowerShell profile. ## Logging Module Events -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets -and functions in Windows PowerShell modules and snap-ins by setting the -LogPipelineExecutionDetails property of modules and snap-ins to TRUE. In Windows -PowerShell 2.0, this feature is available only for snap-ins. +Beginning in Windows PowerShell 3.0, you can record execution events for the +cmdlets and functions in Windows PowerShell modules and snap-ins by setting +the LogPipelineExecutionDetails property of modules and snap-ins to TRUE. In +Windows PowerShell 2.0, this feature is available only for snap-ins. -When the LogPipelineExecutionDetails property value is TRUE (`$true`), Windows PowerShell -writes cmdlet and function execution events in the session to the Windows PowerShell -log in Event Viewer. The setting is effective only in the current session. +When the LogPipelineExecutionDetails property value is TRUE (`$true`), Windows +PowerShell writes cmdlet and function execution events in the session to the +Windows PowerShell log in Event Viewer. The setting is effective only in the +current session. -To enable logging of execution events of cmdlets and functions in a module, use the -following command sequence. +To enable logging of execution events of cmdlets and functions in a module, +use the following command sequence. ```powershell Import-Module @@ -164,58 +164,65 @@ $m = Get-Module $m.LogPipelineExecutionDetails = $true ``` -To enable logging of execution events of cmdlets in a snap-in, use the following -command sequence. +To enable logging of execution events of cmdlets in a snap-in, use the +following command sequence. ```powershell $m = Get-PSSnapin [-Registered] $m.LogPipelineExecutionDetails = $True ``` -To disable logging, use the same command sequence to set the property -value to FALSE (`$false`). +To disable logging, use the same command sequence to set the property value to +FALSE (`$false`). You can also use the "Turn on Module Logging" Group Policy setting to enable and disable module and snap-in logging. The policy value includes a list of module and snap-in names. Wildcards are supported. When "Turn on Module Logging" is set for a module, the value of the -LogPipelineExecutionDetails property of the module is TRUE in all sessions -and it cannot be changed. +LogPipelineExecutionDetails property of the module is TRUE in all sessions and +it cannot be changed. The Turn On Module Logging group policy setting is located in the following Group Policy paths: -Computer Configuration\Administrative Templates\Windows Components\Windows PowerShell -User Configuration\Administrative Templates\Windows Components\Windows PowerShell +``` +Computer Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell + +User Configuration\ + Administrative Templates\ + Windows Components\ + Windows PowerShell +``` -The User Configuration policy takes precedence over the Computer Configuration policy, -and both policies take preference over the value of the LogPipelineExecutionDetails -property of modules and snap-ins. +The User Configuration policy takes precedence over the Computer Configuration +policy, and both policies take preference over the value of the +LogPipelineExecutionDetails property of modules and snap-ins. -For more information about this Group Policy setting, -see [about_Group_Policy_Settings](about_Group_Policy_Settings.md). +For more information about this Group Policy setting, see +[about_Group_Policy_Settings](about_Group_Policy_Settings.md). ## Security and Auditing -The Windows PowerShell event log is designed to indicate activity and -to provide operational details for troubleshooting. +The Windows PowerShell event log is designed to indicate activity and to +provide operational details for troubleshooting. -However, like most Windows-based application event logs, the -Windows PowerShell event log is not designed to be secure. It should not -be used to audit security or to record confidential or proprietary -information. +However, like most Windows-based application event logs, the Windows +PowerShell event log is not designed to be secure. It should not be used to +audit security or to record confidential or proprietary information. -Event logs are designed to be read and understood by users. Users can -read from and write to the log. A malicious user could read an event log -on a local or remote computer, record false data, and then prevent the -logging of their activities. +Event logs are designed to be read and understood by users. Users can read +from and write to the log. A malicious user could read an event log on a local +or remote computer, record false data, and then prevent the logging of their +activities. ## Notes -Authors of module authors can add logging features to their modules. -For more information, see -[Writing a Windows PowerShell Module](https://go.microsoft.com/fwlink/?LinkID=144916) +Authors of module authors can add logging features to their modules. For more +information, see [Writing a Windows PowerShell Module](https://go.microsoft.com/fwlink/?LinkID=144916) in the MSDN library. ## See Also diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md index efbd9576258..8bd83579b3f 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -15,79 +15,53 @@ collection of items. ## LONG DESCRIPTION -The Foreach statement (also known as a Foreach loop) is a language -construct for stepping through (iterating) a series of values in a -collection of items. +The Foreach statement (also known as a Foreach loop) is a language construct +for stepping through (iterating) a series of values in a collection of items. The simplest and most typical type of collection to traverse is an array. -Within a Foreach loop, it is common to run one or more commands against -each item in an array. +Within a Foreach loop, it is common to run one or more commands against each +item in an array. ## Syntax The following shows the ForEach syntax: - foreach ($ in $){} - -### Simplified syntax - -Starting in PowerShell 3.0, syntax with language keywords such as Where and -ForEach was simplified. Comparison operators that work on the members of a -collection are treated as parameters. You can use a method on the members -of a collection without containing it in a script block or adding the -automatic variable `$_.`. Consider the following two examples: - -```powershell - dir cert:\ -Recurse | foreach GetKeyAlgorithm - dir cert:\ -Recurse | foreach {$_.GetKeyAlgorithm()} -``` - -Although both commands work, the first returns results without using a -script block or the `$_`. automatic variable. The method `GetKeyAlgorithm` -is treated as a parameter of ForEach. The first command returns the same -results, but without errors, because the simplified syntax does not attempt -to return results for items for which the specified argument did not apply. - -In this example, the `Get-Process` property `Description` is passed as a -parameter argument of the `ForEach` statement. The results are the -descriptions of active processes. - -```powershell -Get-Process | ForEach Description +```syntax +foreach ($ in $){} ``` -### The `Foreach` statement outside a command pipeline -The part of the `Foreach` statement enclosed in parenthesis represents a +The part of the `ForEach` statement enclosed in parenthesis represents a variable and a collection to iterate. PowerShell creates the variable (`$`) automatically when the `Foreach` loop runs. Prior to each -iteration through the loop, the variable is set to a value in the -collection. The block following a `Foreach` statement `{}` -contains a set of commands to execute against each item in a collection. +iteration through the loop, the variable is set to a value in the collection. +The block following a `Foreach` statement `{}` contains a set +of commands to execute against each item in a collection. ### Examples -For example, the `Foreach` loop in the following example displays the -values in the `$letterArray` array. + +For example, the `Foreach` loop in the following example displays the values +in the `$letterArray` array. ```powershell $letterArray = "a","b","c","d" foreach ($letter in $letterArray) { - Write-Host $letter + Write-Host $letter } ``` -In this example, the `$letterArray` array is created and initialized with -the string values `"a"`, `"b"`, `"c"`, and `"d"`. The first time the -`Foreach` statement runs, it sets the `$letter` variable equal to the first -item in `$letterArray` (`"a"`). Then, it uses the `Write-Host` cmdlet to -display the letter a. The next time through the loop, `$letter` is set to -`"b"`, and so on. After the `Foreach` loop displays the letter d, Windows -PowerShell exits the loop. +In this example, the `$letterArray` array is created and initialized with the +string values `"a"`, `"b"`, `"c"`, and `"d"`. The first time the `Foreach` +statement runs, it sets the `$letter` variable equal to the first item in +`$letterArray` (`"a"`). Then, it uses the `Write-Host` cmdlet to display the +letter a. The next time through the loop, `$letter` is set to `"b"`, and so +on. After the `Foreach` loop displays the letter d, Windows PowerShell exits +the loop. The entire `Foreach` statement must appear on a single line to run it as a -command at the PowerShell command prompt. The entire `Foreach` statement -does not have to appear on a single line if you place the command in a .ps1 -script file instead. +command at the PowerShell command prompt. The entire `Foreach` statement does +not have to appear on a single line if you place the command in a .ps1 script +file instead. `Foreach` statements can also be used together with cmdlets that return a collection of items. In the following example, the Foreach statement steps @@ -96,42 +70,42 @@ through the list of items that is returned by the `Get-ChildItem` cmdlet. ```powershell foreach ($file in Get-ChildItem) { - Write-Host $file + Write-Host $file } ``` You can refine the example by using an `If` statement to limit the results -that are returned. In the following example, the `Foreach` statement -performs the same looping operation as the previous example, but it adds an -`If` statement to limit the results to files that are greater than 100 -kilobytes (KB): +that are returned. In the following example, the `Foreach` statement performs +the same looping operation as the previous example, but it adds an `If` +statement to limit the results to files that are greater than 100 kilobytes +(KB): ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) - { - Write-Host $file - } + if ($file.length -gt 100KB) + { + Write-Host $file + } } ``` -In this example, the `Foreach` loop uses a property of the `$file` variable -to perform a comparison operation (`$file.length -gt 100KB`). The `$file` +In this example, the `Foreach` loop uses a property of the `$file` variable to +perform a comparison operation (`$file.length -gt 100KB`). The `$file` variable contains all the properties in the object that is returned by the -`Get-ChildItem` cmdlet. Therefore, you can return more than just a file -name. In the next example, PowerShell returns the length and the last -access time inside the statement list: +`Get-ChildItem` cmdlet. Therefore, you can return more than just a file name. +In the next example, PowerShell returns the length and the last access time +inside the statement list: ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) - { - Write-Host $file - Write-Host $file.length - Write-Host $file.lastaccesstime - } + if ($file.length -gt 100KB) + { + Write-Host $file + Write-Host $file.length + Write-Host $file.lastaccesstime + } } ``` @@ -145,162 +119,53 @@ size: ```powershell $i = 0 foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) { - Write-Host $file "file size:" ($file.length / 1024).ToString("F0") KB - $i = $i + 1 - } + if ($file.length -gt 100KB) { + Write-Host $file "file size:" ($file.length / 1024).ToString("F0") KB + $i = $i + 1 + } } if ($i -ne 0) { - Write-Host - Write-Host $i " file(s) over 100 KB in the current directory." + Write-Host + Write-Host $i " file(s) over 100 KB in the current directory." } else { - Write-Host "No files greater than 100 KB in the current directory." + Write-Host "No files greater than 100 KB in the current directory." } ``` In the preceding example, the `$i` variable is set to `0` outside the loop, and the variable is incremented inside the loop for each file that is found -that is larger than 100 KB. When the loop exits, an `If` statement -evaluates the value of `$i` to display a count of all the files over 100 -KB. Or, it displays a message stating that no files over 100 KB were found. +that is larger than 100 KB. When the loop exits, an `If` statement evaluates +the value of `$i` to display a count of all the files over 100 KB. Or, it +displays a message stating that no files over 100 KB were found. -The previous example also demonstrates how to format the file length -results: +The previous example also demonstrates how to format the file length results: ```powershell ($file.length / 1024).ToString("F0") ``` The value is divided by 1,024 to show the results in kilobytes rather than -bytes, and the resulting value is then formatted using the fixed-point -format specifier to remove any decimal values from the result. The 0 makes -the format specifier show no decimal places. - -### The `Foreach` Statement Inside a Command Pipeline -When `Foreach` appears in a command pipeline, PowerShell uses the `foreach` -alias, which calls the `ForEach-Object` command. When you use the `foreach` -alias in a command pipeline, you do not include the `($ in -$)` syntax as you do with the `Foreach` statement. This is -because the prior command in the pipeline provides this information. The -syntax of the `foreach` alias when used in a command pipeline is as -follows: - - | foreach {} - -For example, the `Foreach` loop in the following command displays processes -whose working set (memory usage) is greater than 20 megabytes (MB). - -The `Get-Process` command gets all of the processes on the computer. The -`Foreach` alias performs the commands in the script block on each process -in sequence. - -The `IF` statement selects processes with a working set (WS) greater than -20 megabytes. The `Write-Host` cmdlet writes the name of the process -followed by a colon. It divides the working set value, which is stored in -bytes by 1 megabyte to get the working set value in megabytes. Then it -converts the result from a double to a string. It displays the value as a -fixed point number with zero decimals (F0), a space separator (" "), and -then "MB". - -```powershell -Write-Host "Processes with working sets greater than 20 MB." -Get-Process | foreach { - if ($_.WS -gt 20MB) - { - Write-Host $.name ": " ($.WS/1MB).ToString("F0") MB -Separator "" - } -} -``` - -The `foreach` alias also supports beginning command blocks, middle command -blocks, and end command blocks. The beginning and end command blocks run -once, and the middle command block runs every time the `Foreach` loop steps -through a collection or array. - -The syntax of the `foreach` alias when used in a command pipeline with a -beginning, middle, and ending set of command blocks is as follows: - - | foreach {}{}{} - -The following example demonstrates the use of the beginning, middle, and -end command blocks. - -```powershell -Get-ChildItem | foreach { - $fileCount = $directoryCount = 0 -}{ - if ($_.PsIsContainer) { - $directoryCount++ - } else { - $fileCount++ - } -}{ - "$directoryCount directories and $fileCount files" -} -``` - -The beginning block creates and initializes two variables to 0: - -```powershell -{$fileCount = $directoryCount = 0} -``` - -The middle block evaluates whether each item returned by Get-ChildItem -is a directory or a file: - -```powershell -{if ($_.PsIsContainer) {$directoryCount++} else {$fileCount++}} -``` - -If the item that is returned is a directory, the `$directoryCount` variable -is incremented by 1. If the item is not a directory, the `$fileCount` -variable is incremented by 1. The ending block runs after the middle block -completes its looping operation and then returns the results of the -operation: - -```powershell -{"$directoryCount directories and $fileCount files"} -``` - -By using the beginning, middle, and ending command block structure and the -pipeline operator, you can rewrite the earlier example to find any files -that are greater than 100 KB, as follows: - -```powershell -Get-ChildItem | foreach { - $i = 0 } { - if ($_.length -gt 10KB) { - Write-Host $_.name "file size:" ($_.length / 1024).ToString("F0") KB - $i++ - } -} { - if ($i -ne 0) { - Write-Host - Write-Host "$i file(s) over 100 KB in the current directory." - } - else { - Write-Host "No files greater than 100 KB in the current directory." - } -} -``` - -The following example, a function which returns the functions that are used -in scripts and script modules, demonstrates how to use the `MoveNext` -method (which works similarly to `skip X` on a `For` loop) and the -`Current` property of the `$foreach` variable inside of a foreach script -block, even if there are unusually- or inconsistently-spaced function -definitions that span multiple lines to declare the function name. The -example also works if there are comments in the functions used in a script -or script module. +bytes, and the resulting value is then formatted using the fixed-point format +specifier to remove any decimal values from the result. The 0 makes the format +specifier show no decimal places. + +In the following example, the function defined parses PowerShell scripts and +script modules and returns the location of functions contained within. The +example demonstrates how to use the `MoveNext` method (which works similarly +to `skip X` on a `For` loop) and the `Current` property of the `$foreach` +variable inside of a foreach script block. The example function can find +functions in a script even if there are unusually- or inconsistently-spaced +function definitions that span multiple lines. ```powershell function Get-FunctionPosition { [CmdletBinding()] [OutputType('FunctionPosition')] param( - [Parameter(Position = 0, Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)] + [Parameter(Position = 0, Mandatory, + ValueFromPipeline, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [Alias('PSPath')] [System.String[]] @@ -311,22 +176,26 @@ function Get-FunctionPosition { try { $filesToProcess = if ($_ -is [System.IO.FileSystemInfo]) { $_ + } else { + $filesToProcess = Get-Item -Path $Path } - else { - Get-Item -Path $Path - } + $parser = [System.Management.Automation.Language.Parser] foreach ($item in $filesToProcess) { - if ($item.PSIsContainer -or $item.Extension -notin @('.ps1', '.psm1')) { + if ($item.PSIsContainer -or + $item.Extension -notin @('.ps1', '.psm1')) { continue } $tokens = $errors = $null - $ast = [System.Management.Automation.Language.Parser]::ParseFile($item.FullName, ([REF]$tokens), ([REF]$errors)) + $ast = $parser::ParseFile($item.FullName, ([REF]$tokens), + ([REF]$errors)) if ($errors) { - Write-Warning "File '$($item.FullName)' has $($errors.Count) parser errors." + $msg = "File '{0}' has {1} parser errors." -f $item.FullName, + $errors.Count + Write-Warning $msg } :tokenLoop foreach ($token in $tokens) { if ($token.Kind -ne 'Function') { - continue + continue } $position = $token.Extent.StartLineNumber do { @@ -340,7 +209,8 @@ function Get-FunctionPosition { LineNumber = $position Path = $item.FullName } - Add-Member -InputObject $functionPosition -TypeName FunctionPosition -PassThru + Add-Member -InputObject $functionPosition ` + -TypeName FunctionPosition -PassThru } } } @@ -357,4 +227,4 @@ function Get-FunctionPosition { [about_If](about_If.md) -[Foreach-Object](../ForEach-Object.md) \ No newline at end of file +[ForEach-Object](../ForEach-Object.md) \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 81366f5431e..377265dd865 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-28 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,31 +10,30 @@ title: about_Format.ps1xml ## Short Description -The Format.ps1xml files in Windows PowerShell define the default display -of objects in the Windows PowerShell console. You can create your own +The Format.ps1xml files in Windows PowerShell define the default display of +objects in the Windows PowerShell console. You can create your own Format.ps1xml files to change the display of objects or to define default displays for new object types that you create in Windows PowerShell. ## Long Description -The Format.ps1xml files in Windows PowerShell define the default display -of objects in Windows PowerShell. You can create your own Format.ps1xml -files to change the display of objects or to define default displays -for new object types that you create in Windows PowerShell. +The Format.ps1xml files in Windows PowerShell define the default display of +objects in Windows PowerShell. You can create your own Format.ps1xml files to +change the display of objects or to define default displays for new object +types that you create in Windows PowerShell. When Windows PowerShell displays an object, it uses the data in structured -formatting files to determine the default display of the object. The -data in the formatting files determines whether the object is rendered in -a table or in a list, and it determines which properties are displayed by -default. +formatting files to determine the default display of the object. The data in +the formatting files determines whether the object is rendered in a table or +in a list, and it determines which properties are displayed by default. The formatting affects the display only. It does not affect which object properties are passed down the pipeline or how they are passed. Format.ps1xml files cannot be used to customize the output format for hashtables. -Windows PowerShell includes seven formatting files. These files are -located in the installation directory (`$PSHOME`). Each file defines the -display of a group of Microsoft .NET Framework objects: +Windows PowerShell includes seven formatting files. These files are located in +the installation directory (`$PSHOME`). Each file defines the display of a +group of Microsoft .NET Framework objects: 1. Certificate.Format.ps1xml @@ -43,8 +42,8 @@ display of a group of Microsoft .NET Framework objects: 2. DotNetTypes.Format.ps1xml - Other .NET Framework types, such as CultureInfo, FileVersionInfo, - and EventLogEntry objects. + Other .NET Framework types, such as CultureInfo, FileVersionInfo, and + EventLogEntry objects. 3. FileSystem.Format.ps1xml @@ -67,67 +66,67 @@ display of a group of Microsoft .NET Framework objects: Registry objects, such as keys and entries. -A formatting file can define four different views of each object: -table, list, wide, and custom. For example, when the output of a -`Get-ChildItem` command is piped to a `Format-List` command, `Format-List` -uses the view in the FileSystem.format.ps1xml file to determine how to -display the file and folder objects as a list. +A formatting file can define four different views of each object: table, list, +wide, and custom. For example, when the output of a `Get-ChildItem` command is +piped to a `Format-List` command, `Format-List` uses the view in the +FileSystem.format.ps1xml file to determine how to display the file and folder +objects as a list. -When a formatting file includes more than one view of an object, -Windows PowerShell applies the first view that it finds. +When a formatting file includes more than one view of an object, Windows +PowerShell applies the first view that it finds. -In a Format.ps1xml file, a view is defined by a set of XML tags that -describe the name of the view, the type of object to which it can -be applied, the column headers, and the properties that are displayed -in the body of the view. The format in Format.ps1xml files is applied -just before the data is presented to the user. +In a Format.ps1xml file, a view is defined by a set of XML tags that describe +the name of the view, the type of object to which it can be applied, the +column headers, and the properties that are displayed in the body of the view. +The format in Format.ps1xml files is applied just before the data is presented +to the user. ## Creating New Format.ps1xml Files -The .ps1xml files that are installed with Windows PowerShell are -digitally signed to prevent tampering because the formatting can include -script blocks. Therefore, to change the display format of an existing -object view, or to add views for new objects, create your own -Format.ps1xml files, and then add them to your Windows PowerShell -session. - -To create a new file, copy an existing Format.ps1xml file. The new file -can have any name, but it must have a .ps1xml file name extension. You -can place the new file in any directory that is accessible to Windows -PowerShell, but it is useful to place the files in the Windows PowerShell -installation directory (`$PSHOME`) or in a subdirectory of the installation -directory. - -To change the formatting of a current view, locate the view in the -formatting file, and then use the tags to change the view. To create a -view for a new object type, create a new view, or use an existing view -as a model. (The tags are described in the next section of this topic.) -You can then delete all the other views in the file so that the changes -are obvious to anyone examining the file. - -When you have saved the changes, use the `Update-FormatData` cmdlet to add -the new file to your Windows PowerShell session. If you want your view -to take precedence over a view defined in the built-in files, use the -**PrependPath** parameter of `Update-FormatData`. `Update-FormatData` affects -only the current session. To make the change to all future sessions, add -the `Update-FormatData` command to your Windows PowerShell profile. +The .ps1xml files that are installed with Windows PowerShell are digitally +signed to prevent tampering because the formatting can include script blocks. +Therefore, to change the display format of an existing object view, or to add +views for new objects, create your own Format.ps1xml files, and then add them +to your Windows PowerShell session. + +To create a new file, copy an existing Format.ps1xml file. The new file can +have any name, but it must have a .ps1xml file name extension. You can place +the new file in any directory that is accessible to Windows PowerShell, but it +is useful to place the files in the Windows PowerShell installation directory +(`$PSHOME`) or in a subdirectory of the installation directory. + +To change the formatting of a current view, locate the view in the formatting +file, and then use the tags to change the view. To create a view for a new +object type, create a new view, or use an existing view as a model. (The tags +are described in the next section of this topic.) You can then delete all the +other views in the file so that the changes are obvious to anyone examining +the file. + +When you have saved the changes, use the `Update-FormatData` cmdlet to add the +new file to your Windows PowerShell session. If you want your view to take +precedence over a view defined in the built-in files, use the **PrependPath** +parameter of `Update-FormatData`. `Update-FormatData` affects only the current +session. To make the change to all future sessions, add the +`Update-FormatData` command to your Windows PowerShell profile. ### Example: Adding Calendar Data to Culture Objects + This example shows how to change the formatting of the culture objects -(System.Globalization.CultureInfo) generated by the `Get-Culture` cmdlet. -The commands in the example add the calendar property to the default -table view display of culture objects. +(System.Globalization.CultureInfo) generated by the `Get-Culture` cmdlet. The +commands in the example add the calendar property to the default table view +display of culture objects. -The first step is to find the Format.ps1xml file that contains the -current view of the culture objects. The following `Select-String` command -finds the file: +The first step is to find the Format.ps1xml file that contains the current +view of the culture objects. The following `Select-String` command finds the +file: ```powershell -Select-String -Path $PSHOME\*format.ps1xml -Pattern System.Globalization.CultureInfo +Select-String -Path $PSHOME\*format.ps1xml ` + -Pattern System.Globalization.CultureInfo ``` -This command reveals that the definition is in the -DotNetTypes.Format.ps1xml file. +This command reveals that the definition is in the DotNetTypes.Format.ps1xml +file. The next command copies the file contents to a new file, MyDotNetTypes.Format.ps1xml. @@ -136,44 +135,44 @@ MyDotNetTypes.Format.ps1xml. Copy-Item DotNetTypes.Format.ps1xml MyDotNetTypes.Format.ps1xml ``` -Next, open the MyDotNetTypes.Format.ps1xml file in any XML or text -editor, such as Notepad. Find the System.Globalization.CultureInfo object -section. The following XML defines the views of the CultureInfo object. -The object has only a TableControl view. +Next, open the MyDotNetTypes.Format.ps1xml file in any XML or text editor, +such as Notepad. Find the System.Globalization.CultureInfo object section. The +following XML defines the views of the CultureInfo object. The object has only +a TableControl view. ```xml - System.Globalization.CultureInfo - - Deserialized.System.Globalization.CultureInfo - System.Globalization.CultureInfo - - - - - 16 - - - 16 - - - - - - - - LCID - - - Name - - - DisplayName - - - - - + System.Globalization.CultureInfo + + Deserialized.System.Globalization.CultureInfo + System.Globalization.CultureInfo + + + + + 16 + + + 16 + + + + + + + + LCID + + + Name + + + DisplayName + + + + + ``` @@ -187,58 +186,58 @@ digital signature whenever you change the file. - System.Globalization.CultureInfo - - Deserialized.System.Globalization.CultureInfo - System.Globalization.CultureInfo - - - - - 16 - - - 16 - - - - - - - - LCID - - - Name - - - DisplayName - - - - - + System.Globalization.CultureInfo + + Deserialized.System.Globalization.CultureInfo + System.Globalization.CultureInfo + + + + + 16 + + + 16 + + + + + + + + LCID + + + Name + + + DisplayName + + + + + ``` -Next, create a new column for the Calendar property by adding a new set -of `` tags. The value of the Calendar property can be -long, so a value of 45 characters is used, as follows: +Next, create a new column for the Calendar property by adding a new set of +`` tags. The value of the Calendar property can be long, so +a value of 45 characters is used, as follows: ```xml - - 16 - - - 16 - - - 45 - - + + 16 + + + 16 + + + 45 + + ``` @@ -246,37 +245,38 @@ Now, add a new column item in the table rows, as follows: ```xml - - - - LCID - - - Name - - - Calendar - - - DisplayName - - - + + + + LCID + + + Name + + + Calendar + + + DisplayName + + + ``` -After saving the file and closing it, use an `Update-FormatData` command, -such as the following command, to add the new format file to the current -session. The command uses the **PrependPath** parameter to place the new file -in a higher precedence order than the original file. For more information -about `Update-FormatData`, see [Update-FormatData](../../Microsoft.PowerShell.Utility/Update-FormatData.md). +After saving the file and closing it, use an `Update-FormatData` command, such +as the following command, to add the new format file to the current session. +The command uses the **PrependPath** parameter to place the new file in a +higher precedence order than the original file. For more information about +`Update-FormatData`, see +[Update-FormatData](../../Microsoft.PowerShell.Utility/Update-FormatData.md). ```powershell Update-FormatData -PrependPath $PSHOME\MyDotNetTypes.format.ps1xml ``` -To test the change, type `Get-Culture`, and then review the output, -which includes the Calendar property. +To test the change, type `Get-Culture`, and then review the output, which +includes the Calendar property. ```powershell PS C:\> Get-Culture @@ -288,82 +288,78 @@ LCID Name Calendar DisplayName ## The XML in Format.ps1xml Files -The ViewDefinitions section of each Format.ps1xml file contains the -`` tags that define each view. A typical `` tag includes the -following tags: +The ViewDefinitions section of each Format.ps1xml file contains the `` +tags that define each view. A typical `` tag includes the following +tags: * `` identifies the name of the view -* `` specifies the object type or types to which the view applies +* `` specifies the object type or types to which the view + applies * `` specifies how items in the view will be combined in groups * ``, ``, ``, and `` contain the tags that specify how each item will be displayed -The `` tag can contain a `` tag for each object -type to which the view applies. Or, it can contain a `` -tag that references a selection set that is defined elsewhere by using -a `` tag. +The `` tag can contain a `` tag for each object type +to which the view applies. Or, it can contain a `` tag that +references a selection set that is defined elsewhere by using a +`` tag. -The `` tag contains a `` tag that specifies the -object property by which items are to be grouped. It also contains either -a `