diff --git a/.gitignore b/.gitignore index 31efaeaa4333..4c24cd2eb25f 100644 --- a/.gitignore +++ b/.gitignore @@ -17,5 +17,4 @@ updatablehelp/ xhtml/ **/settings.json StaleContentReport.*.csv -.vscode/styles .vale/ diff --git a/reference/docs-conceptual/community/2020-updates.md b/reference/docs-conceptual/community/2020-updates.md index 869d8a2a861f..31ac8e5daeef 100644 --- a/reference/docs-conceptual/community/2020-updates.md +++ b/reference/docs-conceptual/community/2020-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2020 -ms.date: 02/02/2023 +ms.date: 03/30/2025 title: What's New in PowerShell Docs for 2020 --- diff --git a/reference/docs-conceptual/community/2021-updates.md b/reference/docs-conceptual/community/2021-updates.md index 10f23eef864e..de9ddbb51817 100644 --- a/reference/docs-conceptual/community/2021-updates.md +++ b/reference/docs-conceptual/community/2021-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2021 -ms.date: 02/02/2023 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2021 --- # What's new in PowerShell Docs for 2021 diff --git a/reference/docs-conceptual/community/2022-updates.md b/reference/docs-conceptual/community/2022-updates.md index 41a8b1917334..d6bcb4b4feaa 100644 --- a/reference/docs-conceptual/community/2022-updates.md +++ b/reference/docs-conceptual/community/2022-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2022 -ms.date: 06/28/2023 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2022 --- # What's new in PowerShell Docs for 2022 diff --git a/reference/docs-conceptual/community/2023-updates.md b/reference/docs-conceptual/community/2023-updates.md index e8ecfd4089b2..217cc2f7fc22 100644 --- a/reference/docs-conceptual/community/2023-updates.md +++ b/reference/docs-conceptual/community/2023-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2023 -ms.date: 01/02/2024 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2023 --- # What's new in PowerShell Docs for 2023 diff --git a/reference/docs-conceptual/community/2024-updates.md b/reference/docs-conceptual/community/2024-updates.md index 945f8198c8db..9abfcdf08c98 100644 --- a/reference/docs-conceptual/community/2024-updates.md +++ b/reference/docs-conceptual/community/2024-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2024 -ms.date: 01/02/2025 +ms.date: 03/30/2025 title: What's New in PowerShell-Docs for 2024 --- # What's new in PowerShell Docs for 2024 diff --git a/reference/docs-conceptual/community/community-support.md b/reference/docs-conceptual/community/community-support.md index df19b2ddb1ab..9324b3da32df 100644 --- a/reference/docs-conceptual/community/community-support.md +++ b/reference/docs-conceptual/community/community-support.md @@ -1,6 +1,6 @@ --- description: List of resources created for and by PowerShell users -ms.date: 11/16/2022 +ms.date: 03/30/2025 title: PowerShell community support resources --- # Getting support from the community @@ -8,19 +8,30 @@ title: PowerShell community support resources The PowerShell Community is a vibrant and active group of users. This article can help you get connected with other member of the community. -The PowerShell community can file issues, bugs, or feature requests in our -[GitHub](https://github.com/powershell/powershell/issues) repository. If you have questions, you may -find help from other members of the community in one of these public forums: +The PowerShell community can file issues, bugs, or feature requests in our [GitHub][07] repository. +If you have questions, you may find help from other members of the community in one of these public +forums: -- [User Groups](https://aka.ms/psusergroup) -- [PowerShell Tech Community](https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell) -- [DSC Community](https://dsccommunity.org/) -- [PowerShell.org](https://forums.powershell.org/) -- [Stack Overflow](https://stackoverflow.com/questions/tagged/powershell) -- [r/PowerShell subreddit](https://www.reddit.com/r/PowerShell/) +- [User Groups][04] +- [PowerShell Tech Community][09] +- [DSC Community][05] +- [PowerShell.org][06] +- [Stack Overflow][08] +- [r/PowerShell subreddit][10] - PowerShell Virtual User Group - join via: - - [Slack](https://aka.ms/psslack) - - [Discord](https://aka.ms/psdiscord) + - [Slack][03] + - [Discord][02] -For information about our support policy, see the -[PowerShell Support Lifecycle](/powershell/scripting/powershell-support-lifecycle). +For information about our support policy, see the [PowerShell Support Lifecycle][01]. + + +[01]: /powershell/scripting/powershell-support-lifecycle +[02]: https://aka.ms/psdiscord +[03]: https://aka.ms/psslack +[04]: https://aka.ms/psusergroup +[05]: https://dsccommunity.org/ +[06]: https://forums.powershell.org/ +[07]: https://github.com/powershell/powershell/issues +[08]: https://stackoverflow.com/questions/tagged/powershell +[09]: https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell +[10]: https://www.reddit.com/r/PowerShell/ diff --git a/reference/docs-conceptual/community/community-update.yml b/reference/docs-conceptual/community/community-update.yml index b5573b7eb234..40a4f0ebbca8 100644 --- a/reference/docs-conceptual/community/community-update.yml +++ b/reference/docs-conceptual/community/community-update.yml @@ -9,7 +9,7 @@ metadata: ms.topic: landing-page # Required author: sdwheeler #Required; your GitHub user alias, with correct capitalization. ms.author: sewhee #Required; Microsoft alias of author; optional team alias. - ms.date: 02/03/2025 + ms.date: 03/30/2025 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | # overview | quickstart | reference | tutorial | video | whats-new diff --git a/reference/docs-conceptual/community/contributing/editorial-checklist.md b/reference/docs-conceptual/community/contributing/editorial-checklist.md index acbc011cd460..3ecc02636d14 100644 --- a/reference/docs-conceptual/community/contributing/editorial-checklist.md +++ b/reference/docs-conceptual/community/contributing/editorial-checklist.md @@ -1,17 +1,17 @@ --- -description: This is a summarized list of rules for editing PowerShell documentation. -ms.date: 11/16/2022 +description: This article contains a summarized list of rules for editing PowerShell documentation. +ms.date: 03/30/2025 title: Editorial checklist --- # Editor's checklist -This is a summary of rules to apply when writing new or updating existing articles. See other -articles in the Contributor's Guide for detailed explanations and examples of these rules. +This article contains a summarized list of rules for writing or editing PowerShell documentation. +See other articles in the Contributor's Guide for detailed explanations and examples of these rules. ## Metadata - `ms.date`: must be in the format **MM/DD/YYYY** - - Change the date when there is a significant or factual update + - Change the date when there's a significant or factual update - Reorganizing the article - Fixing factual errors - Adding new information @@ -31,7 +31,7 @@ articles in the Contributor's Guide for detailed explanations and examples of th - File paths `C:\Program Files\PowerShell`, `/usr/bin/pwsh` - URLs that aren't meant to be clickable in the document - Property or parameter values -- Use bold for property names, parameter names, class names, module names, entity names, object or +- Use bold for property names, parameter names, class names, module names, entity names, object, or type names - Bold is used for semantic markup, not emphasis - Bold - use asterisks `**` @@ -45,39 +45,39 @@ articles in the Contributor's Guide for detailed explanations and examples of th ### Headers -- H1 is first - only one H1 per article +- Start with H1 first - only one H1 per article - Use [ATX Headers][1] only - Use sentence case for all headers - Don't skip levels - no H3 without an H2 -- Max depth of H3 or H4 -- Blank line before and after -- PlatyPS enforces specific headers in its schema - don't add or remove headers +- Limit header depth to H3 or H4 +- Add blank lines before and after +- Don't add or remove headers - PlatyPS enforces specific headers in its schema ### Code blocks -- Blank line before and after +- Add blank lines before and after - Use tagged code fences - **powershell**, **Output**, or other appropriate language ID -- Untagged fence - syntax blocks or other shells -- Put output in separate code block except for basic examples where you don't intend the for the +- Use untagged code fence for syntax blocks +- Put output in separate code block except for basic examples where you don't intend for the reader to use the **Copy** button - See list of [supported languages][2] ### Lists -- Indented properly -- Blank line before first item and after last item -- Bullet - use hyphen (`-`) not asterisk (`*`) to reduce confusion with emphasis -- For numbered lists, all numbers are "1." +- Indent properly +- Add blank lines before first item and after last item +- Use hyphen (`-`) for bullets not asterisk (`*`) to reduce confusion with emphasis +- Use `1.` for all items in a numbered list ## Terminology -- PowerShell vs. Windows PowerShell +- Use _PowerShell_ vs. _Windows PowerShell_ - See [Product Terminology][3] ## Cmdlet reference examples - Must have at least one example in cmdlet reference -- Examples should be just enough code to demonstrate the usage +- Examples should be only enough code to demonstrate the usage - PowerShell syntax - Use full names of cmdlets and parameters - no aliases - Use splatting for parameters when the command line gets too long @@ -108,11 +108,12 @@ articles in the Contributor's Guide for detailed explanations and examples of th ## Linking to other documents - When linking outside the docset or between cmdlet reference and conceptual - - Use site-relative URLs when linking to Microsoft Learn (remove `https://learn.microsoft.com/en-us`) - - don't include locales in URLs on Microsoft properties (eg. remove `/en-us` from URL) + - Use site-relative URLs when linking to Microsoft Learn (remove + `https://learn.microsoft.com/en-us`) + - don't include locales in URLs on Microsoft properties (remove `/en-us` from URL) - All URLs to external websites should use HTTPS unless that's not valid for the target site - When linking within the docset - - Use the relative filepath (e.g. `../folder/file.md`) + - Use the relative filepath (`../folder/file.md`) - All paths use forward-slash (`/`) characters - Image links should have unique alt text diff --git a/reference/docs-conceptual/community/contributing/file-an-issue.md b/reference/docs-conceptual/community/contributing/file-an-issue.md index d54d2c8ed4a7..2c0570531848 100644 --- a/reference/docs-conceptual/community/contributing/file-an-issue.md +++ b/reference/docs-conceptual/community/contributing/file-an-issue.md @@ -1,6 +1,6 @@ --- description: This article explains how to give feedback about the PowerShell documentation. -ms.date: 07/26/2022 +ms.date: 03/30/2025 title: How to file a PowerShell-Docs issue --- # How to file a PowerShell-Docs issue @@ -15,24 +15,23 @@ There are two ways to create an issue: For a full description of the feedback controls, see the Docs Team blog announcing this [feature][1]. -At the bottom of most pages on `learn.microsoft.com`, you'll see two feedback buttons. One is a link +At the bottom of most pages on `learn.microsoft.com`, there are two feedback buttons. One is a link for product feedback and one is for documentation feedback. The documentation feedback requires a GitHub account. Clicking the button takes you in GitHub and presents an issue template. Enter your feedback and submit the form. > [!NOTE] -> The feedback tool not a support channel. This is a way to ask questions to clarify documentation -> or to report errors and omissions. If you need technical support, see [Community resources][2]. +> The feedback tool not a support channel. It's a way to ask questions to clarify documentation or +> to report errors and omissions. If you need technical support, see [Community resources][2]. ## Filing issues on GitHub -To file a GitHub issue directly, you can click the [New issue][3] button in the PowerShell-Docs -repository. Click the **Get started** button for the issue you want to create. The GitHub issue +To file a GitHub issue directly, you can select the [New issue][3] button in the PowerShell-Docs +repository. Select the **Get started** button for the issue you want to create. The GitHub issue template helps you provide the information needed to address the problem you're reporting. -Before you file a new issue, read through existing issues to see if your problem has already been -reported. This helps avoid duplication and your issue may have been answered already. If you find an -existing issue, you can add your comments, related questions, or answers. +To avoid duplication, search the existing issues to see if someone else has already reported it. If +you find an existing issue, you can add your comments, related questions, or answers. ## Next steps diff --git a/reference/docs-conceptual/community/contributing/general-markdown.md b/reference/docs-conceptual/community/contributing/general-markdown.md index 3b67603caa65..e0785cace3e1 100644 --- a/reference/docs-conceptual/community/contributing/general-markdown.md +++ b/reference/docs-conceptual/community/contributing/general-markdown.md @@ -1,21 +1,20 @@ --- description: This article provides specific guidance for using Markdown in our documentation. -ms.date: 08/01/2024 +ms.date: 03/30/2025 title: Markdown best practices --- # Markdown best practices -This article provides specific guidance for using Markdown in our documentation. This is not a -tutorial for Markdown, but lists specific rules and best practices for Markdown in the PowerShell -docs. If you need a tutorial for Markdown, see this [Markdown cheatsheet][12]. +This article provides specific guidance for using Markdown in our documentation. It isn't a tutorial +for Markdown. If you need a tutorial for Markdown, see this [Markdown cheatsheet][12]. The Microsoft Open Publishing System (OPS) that builds our documentation uses [markdig][06] to process the Markdown documents. Markdig parses the documents based on the rules of the latest [CommonMark][10] specification. OPS follows the CommonMark specification and adds some extensions for platform-specific features, such as tables and alerts. -The CommonMark specification is much stricter about the construction of some Markdown elements. Pay -close attention to the details provided in this document. +The CommonMark specification is stricter about the construction of some Markdown elements. Pay close +attention to the details provided in this document. We use the [markdownlint][08] extension in VS Code to enforce our style and formatting rules. This extension is installed as part of the **Learn Authoring Pack**. @@ -24,11 +23,12 @@ extension is installed as part of the **Learn Authoring Pack**. Blank lines also signal the end of a block in Markdown. -- There should be a single blank between Markdown blocks of different types -- for example, between +- Put a single blank between Markdown blocks of different types; for example, between a paragraph and a list or header. - Don't use more than one blank line. Multiple blank lines render as a single blank line in HTML, therefore the extra blank lines are unnecessary. -- Within a code block, consecutive blank lines break the code block. +- Don't use put multiple consecutive blank lines in a code block, consecutive blank lines break the + code block. Spacing is significant in Markdown. @@ -37,29 +37,31 @@ Spacing is significant in Markdown. ## Titles and headings -Only use [ATX headings][07] (`#` style, as opposed to `=` or `-` style headers). +Use [ATX headings][07] only (`#` style, as opposed to `=` or `-` style headers). - Use sentence case - only proper nouns and the first letter of a title or header should be capitalized -- There must be a single space between the `#` and the first letter of the heading -- Headings should be surrounded by a single blank line -- Only one H1 per document -- Header levels should increment by one -- don't skip levels +- Include a single space between the `#` and the first letter of the heading +- Surround headings with single blank line +- Don't use more than one H1 per document + - It should be the first header + - It should match the title of the article +- Increment header levels by one - don't skip levels - Limit depth to H3 or H4 - Avoid using bold or other markup in headers ## Limit line length to 100 characters -This applies to conceptual articles and cmdlet reference. For `about_` topics, limit the line -length to 79 characters. Limiting the line length improves the readability of `git` diffs and -history. It also makes it easier for other writers to make contributions. +For conceptual articles and cmdlet reference, limit lines to 100 characters. For `about_` articles, +limit the line length to 79 characters. Limiting the line length improves the readability of `git` +diffs and history. It also makes it easier for other writers to make contributions. Use the [Reflow Markdown][09] extension in VS Code to reflow paragraphs to fit the prescribed line length. -Some content types can't be easily reflowed. For example, the code inside of code blocks may also be -difficult to reflow, depending on the content and the code language. And you can't reflow a table. -In these cases, use your best judgment to keep the content as close to the 100-character limit as +Some content types can't be easily reflowed. For example, the code inside of code blocks can also be +difficult to reflow, depending on the content and the code language. You can't reflow a table. In +these cases, use your best judgment to keep the content as close to the 100-character limit as possible. ## Emphasis @@ -70,21 +72,21 @@ mark the emphasis. However, to be consistent and show intent: - Use `**` for bold - Use `_` for italics -Following this pattern makes it easier for others to understand the intent of the markup when there -is a mix of bold and italics in a document. +Following this pattern makes it easier for others to understand the intent of the markup when +there's a mix of bold and italics in a document. ## Lists If your list has multiple sentences or paragraphs, consider using a sublevel header rather than a list. -List should be surrounded by a single blank line. +Surround lists with a single blank line. ### Unordered lists - Don't end list items with a period unless they contain multiple sentences. -- Use the hyphen character (`-`) for list item bullets. This avoids confusion with emphasis markup - that uses the asterisk (`*`). +- Use the hyphen character (`-`) for list item bullets to avoid confusion with emphasis markup that + uses the asterisk (`*`). - To include a paragraph or other elements under a bullet item, insert a line break and align indentation with the first character after the bullet. @@ -129,8 +131,8 @@ This is a list that contains child elements under a bullet item. For example: ```Markdown -1. For the first element, insert a single space after the 1. Long sentences should be wrapped to the - next line and must line up with the first character after the numbered list marker. +1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to + the next line and must line up with the first character after the numbered list marker. To include a second element, 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 @@ -141,8 +143,8 @@ For example: The resulting Markdown is rendered as follows: -1. For the first element, insert a single space after the 1. Long sentences should be wrapped to the - next line and must line up with the first character after the numbered list marker. +1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to + the next line and must line up with the first character after the numbered list marker. To include a second element, 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 @@ -227,8 +229,11 @@ Warning block ## Markdown extension - Tables -A table is an arrangement of data with rows and columns, consisting of a single header row, a -delimiter row separating the header from the data, and zero or more data rows. +A table is an arrangement of data with rows and columns consisting of: + +- A single header row +- A delimiter row separating the header from the data +- Zero or more data rows Each row consists of cells containing arbitrary text separated by pipes (`|`). A leading and trailing pipe is also recommended for clarity. Spaces between pipes and cell content are trimmed. @@ -237,9 +242,11 @@ Block-level elements can't be inserted in a table. All content of a row must be The delimiter row consists of cells whose only content are hyphens (`-`), and optionally, a leading or trailing colon (`:`), or both, to indicate left, right, or center alignment respectively. -For small tables, consider using a list instead. Lists are easier to maintain and read, can be -reflowed to fit within the 100-character line limit, and are more accessible for users that use -screen readers for visual assistance. +For small tables, consider using a list instead. Lists are: + +- Easier to maintain and read +- Can be reflowed to fit within the 100-character line limit +- More accessible for users that use screen readers for visual assistance For more information, see _Tables_ section of [Markdown reference for Microsoft Learn][05]. @@ -253,7 +260,7 @@ For more information, see _Tables_ section of [Markdown reference for Microsoft - All URLs to external websites should use HTTPS unless that isn't valid for the target site. - Links must have a friendly name, usually the title of the linked article - Avoid using backticks, bold, or other markup inside the brackets of a hyperlink. -- Bare URLs may be used when you're documenting a specific URI but must be enclosed in backticks. +- Bare URLs can be used when you're documenting a specific URI but must be enclosed in backticks. For example: ```Markdown diff --git a/reference/docs-conceptual/community/contributing/get-started-writing.md b/reference/docs-conceptual/community/contributing/get-started-writing.md index 57076a72ead1..18c12effb105 100644 --- a/reference/docs-conceptual/community/contributing/get-started-writing.md +++ b/reference/docs-conceptual/community/contributing/get-started-writing.md @@ -1,6 +1,6 @@ --- description: This article is an overview of how to get started as a contributor to the PowerShell documentation. -ms.date: 01/17/2025 +ms.date: 03/30/2025 title: Get started contributing to PowerShell documentation --- # Get started contributing to PowerShell documentation @@ -74,7 +74,7 @@ documentation. All articles must be included in the Table of Contents (TOC). The location should be included in the issue discussion. > [!NOTE] -> The TOC for reference content is autogenerated by the publishing system. You don't have to update +> The publishing system autogenerates the TOC for reference content. You don't have to update > the TOC. ## Updating existing articles @@ -89,7 +89,7 @@ Apply the appropriate change to each version of the file. The PowerShell documentation is written in English and translated into 17 other languages. The English content is stored in the GitHub repository named `MicrosoftDocs/PowerShell-Docs`. Issues -found in the translated content should be submitted to the English repository. +found in the translated content should be submitted to this repository. All translations start from the English content first. We use both human and machine translation. @@ -98,11 +98,11 @@ All translations start from the English content first. We use both human and mac | Human translation | de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW | | Machine translation | cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR | -The content translated by machine translation may not always result in correct word choices and +The content translated by machine translation might not always result in correct word choices and grammar. If you find an error in translation for any language, rather than in the technical details of the article, open an issue explaining why you think the translation is wrong. -Some translation issues can be fixed by changing the English source files. However, some issues may +Some translation issues can be fixed by changing the English source files. However, some issues can require updates to our internal translation system. For those cases, we must submit the issue to our internal localization team for review and response. @@ -120,8 +120,8 @@ should be made in a working branch in you copy of the PowerShell-Docs. If you're edit** method in GitHub, these steps are handled for you. If you're using the **full GitHub workflow**, you must be set up to [work locally][7]. -Both methods end with the creation of a Pull Request (PR). See [Submitting a pull request][8] for -more information and best practices. +Both methods end with the creation of a Pull Request (PR). For more information and best practices, +see [Submitting a pull request][8]. [1]: https://github.com/MicrosoftDocs/PowerShell-Docs diff --git a/reference/docs-conceptual/community/contributing/hackathons.md b/reference/docs-conceptual/community/contributing/hackathons.md index f099eafbb4c8..89007d6bfb3d 100644 --- a/reference/docs-conceptual/community/contributing/hackathons.md +++ b/reference/docs-conceptual/community/contributing/hackathons.md @@ -1,6 +1,6 @@ --- description: This article describes how we manage and support hack-a-thon events like Hacktoberfest. -ms.date: 10/04/2022 +ms.date: 03/30/2025 title: Hacktoberfest and other hack-a-thon events --- # Hacktoberfest and other hack-a-thon events @@ -13,8 +13,8 @@ in Hacktoberfest. ## How to contribute Before you can contribute to an open source repo, you must first configure your account to -contribute to Microsoft Learn. If you have never completed this process, start by -[signing up for a GitHub account][01]. Be sure to [install Git and the Markdown tools][02]. +contribute to Microsoft Learn. If you're new to this process, start by signing up for a +[GitHub account][01]. Be sure to [install Git and the Markdown tools][02]. To get credit for participation, [register with Hacktoberfest][03] and read their [participation guide][04]. @@ -22,18 +22,18 @@ To get credit for participation, [register with Hacktoberfest][03] and read thei ## Find a repo that needs your help The PowerShell-Docs team is supporting Hacktoberfest contributions for several PowerShell -documentation repositories. We have defined a set of cleanup tasks designed to be simple for first -time contributors. Full information can be found in the [Hacktoberfest meta-issue][05]. +documentation repositories. We defined a set of cleanup tasks designed to be simple for first time +contributors. Full information can be found in the [Hacktoberfest meta-issue][05]. To be successful with these tasks, you should: - Have a general understanding of PowerShell syntax - Have an understanding of [splatting][06] - Be able to read and follow the [PowerShell-Docs style guide][07] and [Editorial checklist][08] -- Basic familiarity with Markdown +- Have basic familiarity with Markdown -Before contributing should read the meta-issue. When you are ready to start, open a new issue using -the Hacktoberfest issue template (linked below): +Before contributing should read the meta-issue. When you're ready to start, open a new issue using +the Hacktoberfest issue template by using one of the following links: - [MicrosoftDocs/PowerShell-Docs][09] - [MicrosoftDocs/PowerShell-Docs-DSC][10] @@ -47,21 +47,19 @@ To have a successful contribution to an open source Microsoft Learn repository, and impactful PR. The following examples from the official Hacktoberfest site are considered **_low-quality contributions_**: -- PRs that are automated (for example, scripted opening PRs to remove whitespace, fix typos, or - optimize images) -- PRs that are disruptive (for example, taking someone else's branch or commits and making a PR) -- PRs that are regarded by a project maintainer as a hindrance vs. helping -- A submission that's clearly an attempt to simply +1 your PR count for October - -Finally, one PR to fix a typo is fine, but five PRs to remove a stray whitespace are not. +- PRs containing bulk automated changes + - Example: scripted PRs to remove whitespace, fix common spelling, or optimize images + - Submit an issue first describing the automated changes you want to make +- PRs deemed disruptive (for example, taking someone else's branch or commits and making a PR) +- PRs deemed a hindrance vs. helping +- PRs that are clearly an attempt to increment your PR count for October For more information, see [Hacktoberfest: Values][14]. ### Open a PR -A _PR_ provides a convenient way for a contributor to propose a set of changes. When opening a PR, -specify in the original comment that it's intended to contribute to _hacktoberfest_. Successful PRs -have these common characteristics: +A _PR_ provides a convenient way for a contributor to propose a set of changes. Successful PRs have +these common characteristics: - The PR adds value. - The contributor is receptive to feedback. diff --git a/reference/docs-conceptual/community/contributing/labelling-in-github.md b/reference/docs-conceptual/community/contributing/labelling-in-github.md index 8492269e0cf8..266783e28d64 100644 --- a/reference/docs-conceptual/community/contributing/labelling-in-github.md +++ b/reference/docs-conceptual/community/contributing/labelling-in-github.md @@ -1,14 +1,14 @@ --- description: This article explains how the PowerShell-Docs team uses labels in GitHub. -ms.date: 12/16/2022 -title: Labelling in GitHub +ms.date: 03/30/2025 +title: Labeling in GitHub --- -# Labelling in GitHub +# Labeling in GitHub This article documents how we label issues and pull requests in the PowerShell-Docs repository. -This article is designed to be a job aid for members of the PowerShell-Docs team. It's published -here to provide process transparency for our public contributors. +This article is designed to be a job aid for members of the PowerShell-Docs team. We publish this +information here to provide process transparency for our public contributors. Labels always have a name and a description that is prefixed with their type. @@ -18,11 +18,11 @@ Area labels identify the parts of PowerShell or the documentation that the issue | Label | Related Content | | :----------------------- | :--------------------------------------------------------------------------------------- | -| `area-about` | The `about_*` topic articles. | +| `area-about` | The `about_*` articles. | | `area-archive` | The [Microsoft.PowerShell.Archive][03] module. | | `area-cim` | The [CimCmdlets][01] module. | | `area-community` | Community-facing projects, including the contributor's guide and monthly updates. | -| `area-conceptual` | Conceptual (non-reference) articles. | +| `area-conceptual` | Conceptual articles (not cmdlet reference). | | `area-console` | The console host | | `area-core` | The [Microsoft.PowerShell.Core][04] module. | | `area-crescendo` | The [Crescendo][02] module. | @@ -134,17 +134,17 @@ status labels when they're closed without a related PR. Tag labels add independent context for work items. -| Label | Purpose | -| :------------------------ | :------------------------------------------------------------------------ | -| `in-progress` | Someone is actively working on the item | -| `go-live` | The work item is related to a specific release | -| `doc-a-thon` | The work item is related to a doc-a-thon | -| `up-for-grabs` | Any contributor may volunteer to resolve the work item | -| `hacktoberfest-accepted` | The PR is accepted for inclusion in [#hacktoberfest][17] | -| `hacktoberfest-candidate` | The PR is a candidate for inclusion in [#hacktoberfest][17] | -| `needs-triage` | The issue needs to be triaged by the team before it is ready to be worked | -| `code-of-conduct` | Closed for spam, trolling, or code of conduct violations | -| `do-not-merge` | The PR isn't meant to be merged | +| Label | Purpose | +| :------------------------ | :------------------------------------------------------------------- | +| `in-progress` | Someone is actively working on the item | +| `go-live` | The work item is related to a specific release | +| `doc-a-thon` | The work item is related to a doc-a-thon | +| `up-for-grabs` | Any contributor can volunteer to resolve the work item | +| `hacktoberfest-accepted` | The PR is accepted for inclusion in [#hacktoberfest][17] | +| `hacktoberfest-candidate` | The PR is a candidate for inclusion in [#hacktoberfest][17] | +| `needs-triage` | The issue must be triaged by the team before it's ready to be worked | +| `code-of-conduct` | Closed for spam, trolling, or code of conduct violations | +| `do-not-merge` | The PR isn't meant to be merged | ## Waiting labels diff --git a/reference/docs-conceptual/community/contributing/managing-issues.md b/reference/docs-conceptual/community/contributing/managing-issues.md index 9f494199dcb5..da8c8813866c 100644 --- a/reference/docs-conceptual/community/contributing/managing-issues.md +++ b/reference/docs-conceptual/community/contributing/managing-issues.md @@ -1,13 +1,13 @@ --- description: This article explains how the PowerShell-Docs team manages issues. -ms.date: 11/09/2022 +ms.date: 03/30/2025 title: How we manage issues --- # How we manage issues This article documents how we manage issues in the PowerShell-Docs repository. This article is -designed to be a job aid for members of the PowerShell-Docs team. It's published here to provide -process transparency for our public contributors. +designed to be a job aid for members of the PowerShell-Docs team. We publish this information here +to provide process transparency for our public contributors. ## Sources of issues @@ -20,7 +20,7 @@ process transparency for our public contributors. 80% of new issues are closed within 3 business days. -- Triaged - 1 business days +- Triaged - 1 business day - Fix or change - 10 business days ### Labeling & Milestones @@ -41,8 +41,8 @@ For more information on specific labels, see [Labeling][02]. Issues and PRs should be tagged with the appropriate milestone. If the issue doesn't apply to a specific version, then no milestone is used. PRs and related issues for changes that have yet to be -merged into the PowerShell code base should be assigned to the **Future** milestone. After the code -change has been merged, change the milestone to the appropriate version. +merged into the PowerShell code base should be assigned to the **Future** milestone. After you merge +the change, update the milestone to the appropriate version. | Milestone | Description | | --------- | ----------------------------------------- | @@ -82,7 +82,7 @@ meets weekly to discuss difficult issues need triage and prioritize the work. - Edit the issue to remove any offensive content, if necessary - Enter a comment indicating the issue is spam, close the issue, and then lock it to prevent further comments -- Each violation should be discussed in the weekly triage to determine the need for further action +- Discuss each violation in the regular triage meeting to determine the need for further action [01]: https://github.com/PowerShell/PowerShell/issues/new/choose diff --git a/reference/docs-conceptual/community/contributing/managing-pull-requests.md b/reference/docs-conceptual/community/contributing/managing-pull-requests.md index 27838619d13d..22590fb8bcc2 100644 --- a/reference/docs-conceptual/community/contributing/managing-pull-requests.md +++ b/reference/docs-conceptual/community/contributing/managing-pull-requests.md @@ -1,25 +1,24 @@ --- description: This article explains how the PowerShell-Docs team manages pull requests. -ms.date: 07/25/2022 +ms.date: 03/30/2025 title: How we manage pull requests --- # Managing pull requests This article documents how we manage pull requests in the PowerShell-Docs repository. This article -is designed to be a job aid for members of the PowerShell-Docs team. It's published here to provide -process transparency for our public contributors. +is designed to be a job aid for members of the PowerShell-Docs team. We publish this information +here to provide process transparency for our public contributors. ## Best practices -- The person submitting the PR shouldn't merge the PR without a peer review. +- Request a review. The person submitting the PR shouldn't merge the PR without a peer review. - Assign the peer reviewer when the PR is submitted. Early assignment allows the reviewer to respond sooner with editorial remarks. -- Use comments to describe the nature of the change being submitted. Be sure to @mention the - reviewer. For example, if the change is minor and you don't need a full technical review, explain - this in a comment. -- Reviewers should use the comment suggestion feature, when appropriate, to make it easier for the - author to accept the suggested change. For more information, see - [Reviewing proposed changes in a pull request][1]. +- Use comments to describe the nature of the change being submitted. For example, if the change is + minor, explain the change and that you don't need a full technical review. Be sure to @mention the + reviewer. +- Use the comment suggestion feature to make it easier for the author to accept the suggested + change. For more information, see [Reviewing proposed changes in a pull request][1]. ## PR Process steps @@ -34,7 +33,7 @@ process transparency for our public contributors. 1. Both: Review preview rendering 1. Both: Review validation report - fix warnings and errors 1. Reviewer: Mark review "Approved" -1. Repo Admin: Merge PR (see below for criteria) +1. Repo Maintainer: Merge PR ## Content Reviewer Checklist @@ -47,7 +46,7 @@ See the [editorial checklist][4] for a more comprehensive list. - Validate markdown correctness - See style guide for content-specific formatting rules - Reorganize examples as follows: - - Intro sentence(s) + - Intro paragraph - Code and output - Detailed explanation of code (as necessary) - Check hyperlinks for accuracy @@ -60,12 +59,12 @@ See the [editorial checklist][4] for a more comprehensive list. - Remove locales from URLs - Simplify URLs pointing to `learn.microsoft.com` - Verify versioned content is correct across all versions - - Review the [versioned content change report][5] to see summarized changes + - Review the [versioned content change report][5] ## Branch Merge Process -The `main` branch is the only branch that's merged into `live`. Merges from short-lived (working) -branches should be squashed. +The `main` branch is the only branch that should be merged into `live`. Merges from short-lived +(working) branches should be squashed before merging into `main`. | _Merge from/to_ | _release-branch_ | _main_ | _live_ | | ---------------- | :--------------: | :--------------: | :---------: | @@ -101,10 +100,12 @@ Docs platform, so the values set in these 3 places will be ignored. Please remov ``` When a PR is merged, the HEAD of the target branch is changed. Any open PRs that were based on the -previous HEAD are now outdated. The outdated PR can be merged using Admin rights to override the -merge warnings in GitHub. This is safe to do if the previously merged PRs haven't touched the same -files. Clicking the **Update Branch** button is the safest option. Choose **Update with rebase** -option. For more information see [Updating your pull request branch][9]. +previous HEAD are now outdated. A Maintainer has the right required to override the merge warnings +and merge the outdated PR in GitHub. Merging an outdated PR is safe if the previously merged PRs +didn't touch the same files. + +To update the PR, select the **Update Branch** button. Choose **Update with rebase** option. For +more information, see [Updating your pull request branch][9]. ## Publishing to Live diff --git a/reference/docs-conceptual/community/contributing/overview.md b/reference/docs-conceptual/community/contributing/overview.md index 2eddda33938d..a8378676680c 100644 --- a/reference/docs-conceptual/community/contributing/overview.md +++ b/reference/docs-conceptual/community/contributing/overview.md @@ -1,6 +1,6 @@ --- description: This article outlines the steps required to contribute to the PowerShell documentation. -ms.date: 07/25/2022 +ms.date: 03/30/2025 title: Contributing to PowerShell documentation --- # Contributing to PowerShell documentation @@ -57,13 +57,12 @@ Use the full GitHub workflow when you're making significant changes. If you're n Microsoft, our PR validation system adds a comment to the pull request asking you to sign the online [Contribution Licensing Agreement (CLA)][15]. You must complete this step before we can review or accept your pull request. Signing the CLA is only required the first time you submit a PR in the -repository. You will be asked to sign the CLA for each time you contribute to a new repository. +repository. You might be asked to sign the CLA for each time you contribute to a new repository. ## Code of conduct -All repositories that publish to Microsoft Learn have adopted the -[Microsoft Open Source Code of Conduct][16] or the -[.NET Foundation Code of Conduct][17]. For more +All repositories that publish to Microsoft Learn adhere to the +[Microsoft Open Source Code of Conduct][16] or the [.NET Foundation Code of Conduct][17]. For more information, see the [Code of Conduct FAQ][18]. ## Next steps diff --git a/reference/docs-conceptual/community/contributing/powershell-style-guide.md b/reference/docs-conceptual/community/contributing/powershell-style-guide.md index 7e3f68195cae..f22bf0fcf838 100644 --- a/reference/docs-conceptual/community/contributing/powershell-style-guide.md +++ b/reference/docs-conceptual/community/contributing/powershell-style-guide.md @@ -1,6 +1,6 @@ --- description: This article provides the rules of style for writing PowerShell documentation. -ms.date: 05/09/2024 +ms.date: 03/30/2025 title: PowerShell-Docs style guide --- # PowerShell-Docs style guide @@ -10,8 +10,8 @@ information outlined in the [Overview][10]. ## Formatting command syntax elements -Use the following rules to format elements of the PowerShell language when they are used in a -sentence. +Use the following rules to format elements of the PowerShell language when the elements are used in +a sentence. - Always use the full name for cmdlets and parameters in the proper Pascal case - Only use an alias when you're specifically demonstrating the alias @@ -23,8 +23,8 @@ sentence. - Property names - Parameter names - By default, use the parameter without the hyphen prefix. - - When illustrating the use of a parameter with the hyphen prefix, the parameter should be - wrapped in backticks. + - Use parameter name with the hyphen if you're illustrating syntax. Wrap the parameter in + backticks. For example: @@ -47,7 +47,7 @@ sentence. - File and directory paths - Inline command syntax examples - See [Markdown for code samples][04] - This example show some backtick examples: + This example shows some backtick examples: ~~~markdown The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns @@ -58,7 +58,7 @@ sentence. ``` ~~~ - This examples shows command syntax inline: + This example shows command syntax inline: ```markdown To start the spooler service on a remote computer named DC01, you type: @@ -75,7 +75,7 @@ Markdown supports two different code styles: - **Code spans (inline)** - marked by a single backtick (`` ` ``) character. Used within a paragraph rather than as a standalone block. - **Code blocks** - a multi-line block surrounded by triple-backtick (`` ``` ``) strings. Code - blocks may also have a language label following the backticks. The language label enables syntax + blocks can also have a language label following the backticks. The language label enables syntax highlighting for the contents of the code block. All code blocks should be contained in a code fence. Never use indentation for code blocks. Markdown @@ -83,7 +83,7 @@ allows this pattern but it can be problematic and should be avoided. A code block is one or more lines of code surrounded by a triple-backtick (`` ``` ``) code fence. The code fence markers must be on their own line before and after the code sample. The opening -marker may have an optional language label. The language label enables syntax highlighting on the +marker can have an optional language label. The language label enables syntax highlighting on the rendered webpage. For a full list of supported language tags, see [Fenced code blocks][01] in the centralized @@ -126,10 +126,10 @@ for (; ; ) ### Illustrative examples -Illustrative examples are used to explain a PowerShell concept. In general you should -[Avoid using PowerShell prompts in examples][03]. However, illustrative examples aren't meant to be -copied and pasted for execution. These are most commonly used for simple examples that are easy to -understand. The code block can include the PowerShell prompt and example output. +Illustrative examples are used to explain a PowerShell concept. Yo`u should +[Avoid using PowerShell prompts in examples][03] whenever possible. However, illustrative examples +aren't meant to be copied and pasted for execution. They're most commonly used for simple examples +that are easy to understand. You may include the PowerShell prompt and example output. Here's a simple example illustrating the PowerShell comparison operators. In this case, we don't intend the reader to copy and run this example. Notice that this example uses `PS>` as a simplified @@ -205,8 +205,8 @@ box frame on the web page. The **Output** code box has no syntax highlighting. ### Avoid line continuation in code samples -Avoid using line continuation characters (`` ` ``) in PowerShell code examples. These are hard to -see and can cause problems if there are extra spaces at the end of the line. +Avoid using line continuation characters (`` ` ``) in PowerShell code examples. Backtick characters +are difficult to see and can cause problems if there are extra spaces at the end of the line. - Use PowerShell [splatting][02] to reduce line length for cmdlets that have several parameters. - Take advantage of PowerShell's natural line break opportunities, like after pipe (`|`) characters, @@ -246,14 +246,14 @@ Cmdlet and parameter names must use the proper [Pascal-cased][06] names. ### Using parameters in examples -Avoid using positional parameters. In general, you should always include the parameter name in an -example, even if the parameter is positional. This reduces the chance of confusion in your examples. +Avoid using positional parameters. To reduce the chance of confusion, you should include the +parameter name in an example, even if the parameter is positional. ## Formatting cmdlet reference articles -Cmdlet reference articles have a specific structure. This structure is defined by [PlatyPS][07]. -PlatyPS generates the cmdlet help for PowerShell modules in Markdown. After editing the Markdown -files, PlatyPS is used create the MAML help files used by the `Get-Help` cmdlet. +Cmdlet reference articles have a specific structure. [PlatyPS][07] defines this structure. PlatyPS +generates the cmdlet help for PowerShell modules in Markdown. After you edit the Markdown files, +PlatyPS can create the MAML help files used by the `Get-Help` cmdlet. PlatyPS has a schema that expects a specific structure for cmdlet reference. The PlatyPS [schema document][08] describes this structure. Schema violations cause build errors that must be @@ -322,7 +322,7 @@ Basic formatting guidelines: ``` - Markdown tables - - For `About_*` topics, tables must fit within 76 characters + - For `About_*` articles, tables must fit within 76 characters - If the content doesn't fit within 76 character limit, use bullet lists instead - Use opening and closing `|` characters on each line diff --git a/reference/docs-conceptual/community/contributing/product-terminology.md b/reference/docs-conceptual/community/contributing/product-terminology.md index 8b0fa60ecadf..16491d9b1e31 100644 --- a/reference/docs-conceptual/community/contributing/product-terminology.md +++ b/reference/docs-conceptual/community/contributing/product-terminology.md @@ -1,13 +1,13 @@ --- description: This article contains guidelines for the proper use of product names and terms. -ms.date: 06/20/2024 +ms.date: 03/30/2025 title: Product terminology and branding guidelines --- # Product terminology and branding guidelines -When writing about any product it's important to correctly and consistently use product names and -terminology. This guide defines product names and terminology related to PowerShell. Note the -capitalization of specific words or use cases. +When you write about any product, it's important to use the proper product names and terminology. +This guide defines product names and terminology related to PowerShell. Note the capitalization of +specific words or use cases. ## PowerShell (collective name) @@ -15,8 +15,8 @@ Use **PowerShell** to describe the scripting language and an interactive shell. ### PowerShell (product name) -The cross-platform version of PowerShell that's built on .NET (core), rather than the .NET -Framework. PowerShell can be installed on Windows, Linux, and macOS. +The cross-platform version of PowerShell built on .NET (core), rather than the .NET Framework. +PowerShell can be installed on Windows, Linux, and macOS. ### PowerShell Core (product deprecated) @@ -89,15 +89,13 @@ since ASM is scheduled for retirement. These products are used to manage Azure resources but aren't part of the Azure PowerShell collective product. They should never be described using the "Azure PowerShell" collective name. -- Azure Active Directory PowerShell (AzureAD) - Azure Information Protection PowerShell - Azure Deployment Manager PowerShell - Azure Elastic Database Jobs PowerShell - Azure Service Fabric PowerShell - Azure Stack PowerShell -- Microsoft.Graph PowerShell -- Microsoft.Graph.Entra PowerShell -- MSOnline PowerShell +- Microsoft Graph PowerShell SDK +- Microsoft Entra PowerShell Guidelines diff --git a/reference/docs-conceptual/community/contributing/pull-requests.md b/reference/docs-conceptual/community/contributing/pull-requests.md index 0a1203ecfc01..f6c0dd8945d9 100644 --- a/reference/docs-conceptual/community/contributing/pull-requests.md +++ b/reference/docs-conceptual/community/contributing/pull-requests.md @@ -1,6 +1,6 @@ --- description: This article explains how to submit pull requests to the PowerShell-Docs repository. -ms.date: 07/26/2022 +ms.date: 03/30/2025 title: How to submit pull requests --- # How to submit pull requests @@ -38,12 +38,12 @@ changed files. Large PRs are difficult to review and are more prone to contain e ### Renaming or deleting files -When renaming or deleting files, there must be an issue associated with the PR. That issue must +There must be an issue associated with the PR when you rename or delete files. That issue must discuss the need to rename or delete the files. -Avoid mixing content additions or changes with file renames and deletes. Any file that's renamed or -deleted must be added to the global redirection file. When possible, update any files that link to -the renamed or deleted content, including any TOC files. +Avoid mixing content additions or changes with file renames and deletes. Any file that you rename or +delete must be added to the appropriate redirection file. When possible, update any files that link +to the renamed or deleted content, including any TOC files. ### Avoid editing repository configuration files @@ -65,9 +65,9 @@ configuration files are any files that match one or more of these patterns: - `ThirdPartyNotices` - `tools/**` -For safety and security, if you believe you have discovered a bug or potential improvement for a -repository configuration file, [file an issue][2]. The maintainers will review and implement any -fixes or improvements as needed. +For safety and security, don't change these files. If you think one of these files should be +changed, [file an issue][2]. After the maintainers triage the issue, they'll make the appropriate +changes. ## Use the PR template @@ -123,9 +123,9 @@ If your PR is a work-in-progress, set it to [draft mode][4] or prefix your PR ti ## Expectations Comment -After you submit your PR, a bot will comment on your PR to provide you with resources and to set -expectations for the rest of the process. Always review this comment, even if you've contributed -before, because it contains accurate and up-to-date information. +After you submit your PR, a bot will comment on your PR. The comment provides resources and sets +expectations for the rest of the process. We might update this comment periodically, so always +review the comment, even if this isn't your first contribution. ![example expectation comment][5] @@ -134,29 +134,27 @@ before, because it contains accurate and up-to-date information. The Docs PR validation service is a GitHub app that runs validation rules on your changes. You must fix any errors or warnings reported by the validation service. -You'll see the following behavior: +The following steps outline the validation behavior: 1. You submit a PR. -1. In the GitHub comment that indicates the status of your PR, you'll see the status of "checks" - enabled on the repository. In this example, there are two checks enabled, "Commit Validation" and - "OpenPublishing.Build": +1. In the GitHub comment that indicates the status of the "checks" enabled on the repository. In + this example, there are two checks enabled, "Commit Validation" and "OpenPublishing.Build": ![validation status - some checks failed][6] The build can pass even if commit validation fails. -1. Click **Details** for more information. -1. On the Details page, you'll see all the validation checks that failed, with information about how - to fix the issues. +1. Select **Details** for more information. The **Details** page shows all the validation checks + that failed and includes information about how to fix the issues. 1. When validation succeeds, the following comment is added to the PR: ![Validation status: success][7] > [!NOTE] -> If you are an external (not a Microsoft employee) contributor you don't have access to the +> If you're an external contributor (not a Microsoft employee), you don't have access to the > detailed build reports or preview links. -When the PR is reviewed, you may be asked to make changes or fix validation warning messages. The +When the PR is reviewed, you might be asked to make changes or fix validation warning messages. The PowerShell-Docs team can help you understand validation errors and editorial requirements. ## GitHub Actions @@ -166,14 +164,14 @@ and the reviewers. ### Checklist verification -If your PR is not in [draft mode][4] and is not prefixed with `WIP`, a GitHub Action inspects your -PR to verify that you have checked every item in the PR template's checklist. If this check fails, -the team won't review or merge your PR. The checklist items are mandatory. +If your PR isn't in [draft mode][4] and isn't prefixed with `WIP`, a GitHub Action inspects your PR +to verify that you selected every item in the PR template's checklist. The maintainers won't review +or merge your PR until you complete the checklist. The checklist items are mandatory. ### Authorization verification If your PR targets the `live` branch or modifies any repository configuration files, a GitHub Action -checks your permissions to verify that you are authorized to submit those changes. +checks your permissions to verify that you're authorized to submit those changes. Only repository administrators are authorized to target the `live` branch or modify repository configuration files. @@ -183,8 +181,7 @@ configuration files. If your PR adds, removes, or modifies any versioned content a GitHub Action analyzes your changes and writes a report summarizing the types of changes made to versioned content. -This report is useful for seeing if there are other versions of the file(s) you modified and whether -or not those versions have also been updated in the changeset. +This report can show if there are other versions of the files that you need to update in this PR. To find the versioned content report for your PR: diff --git a/reference/docs-conceptual/community/contributing/quality-improvements.md b/reference/docs-conceptual/community/contributing/quality-improvements.md index 19823e18c45f..ce35b60daaea 100644 --- a/reference/docs-conceptual/community/contributing/quality-improvements.md +++ b/reference/docs-conceptual/community/contributing/quality-improvements.md @@ -1,16 +1,15 @@ --- description: >- This article describes the process for contributing quality improvements to the documentation. -ms.date: 06/28/2023 +ms.date: 03/30/2025 title: Contributing quality improvements --- # Contributing quality improvements For [Hacktoberfest 2022][31], we [piloted a process][19] for contributing quality improvements to -the PowerShell content. This guide continues and generalizes that process, providing a low-friction -way for community members to contribute and collaborate on GitHub through enhancing the quality of -documentation. +the PowerShell content. This guide generalizes that process to define a low-friction way for +community members to improve to the quality of the documentation. We're focusing on these quality areas: @@ -85,12 +84,12 @@ All code samples should follow the [style guidelines][03] for PowerShell content repeated in abbreviated form here for convenience: - All code blocks should be contained in a triple-backtick code fence (`` ``` ``). -- Line length for code blocks is limited to `90` characters except in About topics, where it's - limited to `76` characters. +- Line length for code blocks is limited to `90` characters for cmdlet reference articles. +- Line length for code blocks is limited to `76` characters for `about_*` articles. - Avoid using line continuation characters (`` ` ``) in PowerShell code examples. - Use splatting or natural line break opportunities, like after pipe (`|`) characters, opening braces (`}`), parentheses (`(`), and brackets (`[`) to limit line length. -- Only include the PowerShell prompt for illustrative examples where the code is not intended for +- Only include the PowerShell prompt for illustrative examples where the code isn't intended for copy-pasting. - Don't use aliases in examples unless you're specifically documenting the alias. - Avoid using positional parameters. Use the parameter name, even if the parameter is positional. @@ -109,9 +108,9 @@ here for convenience: - PowerShell module names should be **bold**. - PowerShell keywords and operators should be all lowercase. - Use proper (Pascal) casing for cmdlet names and parameters. -- When referring to a parameter by name, the name should be **bold**. When illustrating the use of - a parameter with the hyphen prefix, the parameter should be wrapped in backticks. -- When showing example usage of an external command, the example should be wrapped in backticks. +- When you refer to a parameter by name, the name should be **bold**. +- Use parameter name with the hyphen if you're illustrating syntax. Wrap the parameter in backticks. +- When you show example usage of an external command, the example should be wrapped in backticks. Always include the file extension of the external command. ## Link references @@ -134,7 +133,7 @@ The [Packages tab][31] displays all available packages in the PowerShell Gallery > [!NOTE] > When you replace an inline link, reflow the content to wrap at 100 characters. You can use the -> [reflow-markdown][30] VS Code extension to do this quickly. +> [reflow-markdown][30] VS Code extension to quickly reflow the paragraph. At the bottom of the file, add a markdown comment before the definition of the links. @@ -163,16 +162,14 @@ Make sure of the line lengths and use the [Reflow Markdown][30] extension to fix ## Spelling -Sometimes, despite our best efforts, typos and misspellings get through and end up in the -documentation. These mistakes make documentation harder to follow and localize. Fixing these -mistakes makes the documentation more readable, especially for non-English speakers who rely on -accurate translations. +Despite our best efforts, typos and misspellings get through and end up in the documentation. These +mistakes make documentation harder to follow and localize. Fixing these mistakes makes the +documentation more readable, especially for non-English speakers who rely on accurate translations. ## Process We encourage you to choose one or more of the quality areas and an article (or group of articles) -to improve. Once you've decided what articles and content areas you want to work on, follow these -steps: +to improve. Use the following steps to guide your work: @@ -200,7 +197,8 @@ steps: - resolves #123 ``` - The content developers will review your work as soon as they can to help you get it merged. + After you submit the PR, the maintainers will review your work and work with you to get it + merged. diff --git a/reference/docs-conceptual/community/contributing/using-github-codespaces.md b/reference/docs-conceptual/community/contributing/using-github-codespaces.md index 4796bb96fa6e..cdfa1f4b3688 100644 --- a/reference/docs-conceptual/community/contributing/using-github-codespaces.md +++ b/reference/docs-conceptual/community/contributing/using-github-codespaces.md @@ -2,7 +2,7 @@ description: >- This article describes the process for contributing to the documentation using GitHub Codespaces as an authoring environment. -ms.date: 05/10/2023 +ms.date: 03/30/2025 title: Contribute using GitHub Codespaces --- @@ -37,17 +37,15 @@ already available for you: ## Cost -GitHub Codespaces can be used for free up to 120 core-hours per month. With the configuration we -recommend in this article, that means up to 60 hours of free usage per month. The monthly usage is +GitHub Codespaces can be used for free up to 120 core-hours per month. The monthly usage is calculated across all your repositories, not just documentation. For more information about pricing, see [About billing for GitHub Codespaces][12]. > [!TIP] -> If you're comfortable using containers and Docker, you can get the same experience as using -> GitHub Codespaces in VS Code by using the devcontainer defined for the PowerShell documentation -> repositories. There's no cost associated with using devcontainers. For more information, see -> the [Dev Containers tutorial][13]. +> If you're comfortable using containers and Docker, you can get the same experience by using the +> devcontainer defined for the PowerShell documentation repositories. There's no cost associated +> with using devcontainers. For more information, see the [Dev Containers tutorial][13]. ## Creating your GitHub Codespace @@ -69,7 +67,7 @@ The UI is based on VS Code and works the same way. To open your GitHub Codespace in the browser, follow these steps: 1. Open [https://github.com/codespaces][14] in your browser. -1. The page lists your codespaces. Find the created codespace for the repository you want to +1. The page lists your Codespaces. Find the created codespace for the repository you want to contribute to and select it. After you select your codespace, GitHub opens it in the same window. From here, you're ready to @@ -91,15 +89,15 @@ writing or editing your contribution. When you want to turn an inline link, like `[some text](destination.md)`, into a reference link like `[some text][01]`, select the link destination in the editor. Then you can either: -1. Right click on the link destination and select "Refactor..." in the context menu. +1. Right-click on the link destination and select "Refactor..." in the context menu. 1. Press Ctrl+Shift+R. -Either action raises the refactoring context menu. Select "Extract to link definition" in the -context menu. This replaces the `(destination.md)` in the link with `[def]`. You can rename the +Either action raises the refactoring context menu. To replace the `(destination.md)` in the link +with `[def]`, select **Extract to link definition** in the context menu. You can rename the definition by typing a name in. For the PowerShell documentation, we use two-digit numerical reference link definitions, like -`[01]` or `[31]`. Only use reference link definitions in about topics and conceptual documentation. +`[01]` or `[31]`. Only use reference link definitions in about articles and conceptual documentation. Don't use reference link definitions in cmdlet reference documentation. ### Fix prose style violations @@ -110,8 +108,8 @@ document with colored squiggles. Hover over a violation to see more information about it. -Select the rule's name in the hover information to open a web page that explains the rule. Select -the rule's filename (ending in `.yml`) to open the rule and review its implementation. +To open a web page that explains the rule, select the rule's name in the hover information. To open +the rule and review its implementation, select the rule's filename (ending in `.yml`). If the rule supports a quick fix, you can select "Quick Fix..." in the hover information for the violation and apply one of the suggested fixes by selecting it from the context menu. You can also @@ -127,9 +125,8 @@ When you review an article in your codespace, Markdownlint automatically checks you open it and as you type. If Markdownlint finds any syntax problems, it highlights them in the document with colored squiggles. -Hover over a violation to see more information about it. - -Select the rule's ID in the hover information to open a web page that explains the rule. +Hover over a violation to see more information about it. To open a web page that explains the rule, +select the rule's ID in the hover information. If the rule supports a quick fix, you can select "Quick Fix..." in the hover information for the violation and apply one of the suggested fixes by selecting it from the context menu. You can also @@ -203,7 +200,7 @@ command. When you select that command, VS Code opens a preview of the active doc preview's style matches the Learn platform. > [!NOTE] -> Site-relative and cross-reference links won't work in the preview. +> Site-relative and cross-reference links don't work in the preview. ### Reflow your content @@ -216,9 +213,9 @@ When using this command for block quotes, make sure the paragraph in the block q reflowing is surrounded by blank lines. Otherwise, the command reflows every paragraph together. > [!CAUTION] -> Don't use this command when editing about topics. The lines in those documents must not be +> Don't use this command when editing about articles. The lines in those documents must not be > longer than 80 characters. There's currently no way for a repository to configure different line -> lengths by folder or filename, so reflow doesn't work for about topic documents. +> lengths by folder or filename, so reflow doesn't work for about article documents. ### Review all problems in a document diff --git a/reference/docs-conceptual/community/digital-art.md b/reference/docs-conceptual/community/digital-art.md index 508ce04f1a6a..69e5ff6ec114 100644 --- a/reference/docs-conceptual/community/digital-art.md +++ b/reference/docs-conceptual/community/digital-art.md @@ -2,7 +2,7 @@ author: sdwheeler description: Download PowerShell related artwork and posters ms.author: sewhee -ms.date: 06/28/2023 +ms.date: 03/30/2025 title: PowerShell Digital Art --- # PowerShell Digital Art diff --git a/reference/docs-conceptual/learn/ps101/10-script-modules.md b/reference/docs-conceptual/learn/ps101/10-script-modules.md index cf2ea109d39e..7dbf1b21a528 100644 --- a/reference/docs-conceptual/learn/ps101/10-script-modules.md +++ b/reference/docs-conceptual/learn/ps101/10-script-modules.md @@ -1,23 +1,24 @@ --- description: Script modules are an easy way to package scripts and functions into a reusable tool. ms.custom: Contributor-mikefrobbins -ms.date: 12/08/2022 +ms.date: 03/27/2025 ms.reviewer: mirobb title: Script modules --- + # Chapter 10 - Script modules -Turning your one-liners and scripts in PowerShell into reusable tools becomes even more important if -it's something that you're going to use frequently. Packaging your functions in a script module -makes them look and feel more professional and makes them easier to share. +If you find yourself using the same PowerShell one-liners or scripts often, turning them into +reusable tools is even more important. Packaging your functions in a script module gives them a more +professional feel and makes them easier to support and share with others. -## Dot-Sourcing Functions +## Dot-sourcing functions -Something that we didn't talk about in the previous chapter is dot-sourcing functions. When a -function in a script isn't part of a module, the only way to load it into memory is to dot-source -the `.ps1` file that it's saved in. +One thing we didn't cover in the previous chapter is dot-sourcing functions. When you define a +function in a script but not part of a module, the only way to load it into memory is by +dot-sourcing its `.ps1` file. -The following function has been saved as `Get-MrPSVersion.ps1`. +For example, save the following function in a file named `Get-MrPSVersion.ps1`. ```powershell function Get-MrPSVersion { @@ -25,93 +26,98 @@ function Get-MrPSVersion { } ``` -When you run the script, nothing happens. +When you run the script, it appears that nothing happens. ```powershell .\Get-MrPSVersion.ps1 ``` -If you try to call the function, it generates an error message. +Attempting to call the function results in an error because it isn't loaded into memory. ```powershell Get-MrPSVersion ``` ```Output -Get-MrPSVersion : The term 'Get-MrPSVersion' is not recognized as the name of a cmdlet, -function, script file, or operable program. Check the spelling of the name, or if a path -was included, verify that the path is correct and try again. +Get-MrPSVersion : The term 'Get-MrPSVersion' is not recognized as the name +of a cmdlet, function, script file, or operable program. Check the spelling +of the name, or if a path was included, verify that the path is correct and +try again. At line:1 char:1 + Get-MrPSVersion - + CategoryInfo : ObjectNotFound: (Get-MrPSVersion:String) [], CommandNotFou - ndException ++ ~~~~~~~~~~~~~~~ + + CategoryInfo : ObjectNotFound: (Get-MrPSVersion:String) [], + CommandNotFoundException + FullyQualifiedErrorId : CommandNotFoundException - ``` -You can determine if functions are loaded into memory by checking to see if they exist on the -**Function** PSDrive. +You can confirm whether functions are loaded into memory by verifying their existence on the +**Function:** PSDrive. ```powershell Get-ChildItem -Path Function:\Get-MrPSVersion ``` ```Output -Get-ChildItem : Cannot find path 'Get-MrPSVersion' because it does not exist. +Get-ChildItem : Cannot find path 'Get-MrPSVersion' because it does not +exist. At line:1 char:1 + Get-ChildItem -Path Function:\Get-MrPSVersion - + CategoryInfo : ObjectNotFound: (Get-MrPSVersion:String) [Get-ChildItem], - ItemNotFoundException - + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : ObjectNotFound: (Get-MrPSVersion:String) [Get + -ChildItem], ItemNotFoundException + + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.Ge + tChildItemCommand ``` -The problem with calling the script that contains the function is that the functions are loaded in -the _Script_ scope. When the script completes, that scope is removed and the function is removed -with it. +The issue with running the script that defines the function is that it loads it into the **Script** +scope. Once the script finishes executing, PowerShell discards that scope along with the function. -The function needs to be loaded into the _Global_ scope. That can be accomplished by dot-sourcing -the script that contains the function. The relative path can be used. +To keep the function available after the script runs, it needs to be loaded into the **Global** +scope. You can accomplish this by dot-sourcing the script file. You can use a relative path for this +purpose. ```powershell . .\Get-MrPSVersion.ps1 ``` -The fully qualified path can also be used. +You can also use the full path to the script when dot-sourcing it. ```powershell . C:\Demo\Get-MrPSVersion.ps1 ``` -If a portion of the path is stored in a variable, it can be combined with the remainder of the path. -There's no reason to use string concatenation to combine the variable together with the remainder of -the path. +If part of the path is stored in a variable, you can combine it with the rest of the path. There's +no need to use string concatenation to do this. ```powershell $Path = 'C:\' . $Path\Get-MrPSVersion.ps1 ``` -Now when I check the **Function** PSDrive, the `Get-MrPSVersion` function exists. +Now, if you check the **Function** PSDrive, you see the `Get-MrPSVersion` function is available. ```powershell Get-ChildItem -Path Function:\Get-MrPSVersion ``` ```Output -CommandType Name Version Source ------------ ---- ------- ------ +CommandType Name Version +----------- ---- ------- Function Get-MrPSVersion ``` -## Script Modules +## Script modules + +In PowerShell, a script module is simply a `.psm1` file that contains one or more functions, just +like a regular script, but with a different file extension. -A script module in PowerShell is simply a file containing one or more functions that's saved as a -`.psm1` file instead of a `.ps1` file. +How do you create a script module? You might assume with a command named something like +`New-Module`. That assumption is a reasonable guess, but that command actually creates a dynamic +module, not a script module. -How do you create a script module? You're probably guessing with a command named something like -`New-Module`. Your assumption would be wrong. While there is a command in PowerShell named -`New-Module`, that command creates a dynamic module, not a script module. Always be sure to read the -help for a command even when you think you've found the command you need. +This scenario is a good reminder to always read the help documentation, even when a command name +looks exactly like what you need. ```powershell help New-Module @@ -124,40 +130,50 @@ NAME SYNOPSIS Creates a new dynamic module that exists only in memory. + SYNTAX - New-Module [-Name] [-ScriptBlock] [-ArgumentList ] - [-AsCustomObject] [-Cmdlet ] [-Function ] [-ReturnResult] - [] + New-Module [-Name] [-ScriptBlock] + [-ArgumentList + ] [-AsCustomObject] [-Cmdlet ] + [-Function ] [-ReturnResult] [] + DESCRIPTION - The New-Module cmdlet creates a dynamic module from a script block. The members of - the dynamic module, such as functions and variables, are immediately available in - the session and remain available until you close the session. + The `New-Module` cmdlet creates a dynamic module from a script block. + The members of the dynamic module, such as functions and variables, are + immediately available in the session and remain available until you + close the session. - Like static modules, by default, the cmdlets and functions in a dynamic module are - exported and the variables and aliases are not. However, you can use the - Export-ModuleMember cmdlet and the parameters of New-Module to override the defaults. + Like static modules, by default, the cmdlets and functions in a dynamic + module are exported and the variables and aliases are not. However, you + can use the Export-ModuleMember cmdlet and the parameters of + `New-Module` to override the defaults. - You can also use the AsCustomObject parameter of New-Module to return the dynamic - module as a custom object. The members of the modules, such as functions, are - implemented as script methods of the custom object instead of being imported into - the session. + You can also use the **AsCustomObject** parameter of `New-Module` to return + the dynamic module as a custom object. The members of the modules, such + as functions, are implemented as script methods of the custom object + instead of being imported into the session. - Dynamic modules exist only in memory, not on disk. Like all modules, the members of - dynamic modules run in a private module scope that is a child of the global scope. - Get-Module cannot get a dynamic module, but Get-Command can get the exported members. + Dynamic modules exist only in memory, not on disk. Like all modules, + the members of dynamic modules run in a private module scope that is a + child of the global scope. Get-Module cannot get a dynamic module, but + Get-Command can get the exported members. + + To make a dynamic module available to `Get-Module`, pipe a `New-Module` + command to Import-Module, or pipe the module object that `New-Module` + returns to `Import-Module`. This action adds the dynamic module to the + `Get-Module` list, but it does not save the module to disk or make it + persistent. - To make a dynamic module available to Get-Module , pipe a New-Module command to - Import-Module, or pipe the module object that New-Module returns to Import-Module . - This action adds the dynamic module to the Get-Module list, but it does not save the - module to disk or make it persistent. RELATED LINKS - Online Version: http://go.microsoft.com/fwlink/?LinkId=821495 + Online Version: https://learn.microsoft.com/powershell/module/microsoft. + powershell.core/new-module?view=powershell-5.1&WT.mc_id=ps-gethelp Export-ModuleMember Get-Module Import-Module Remove-Module + about_Modules REMARKS To see the examples, type: "Get-Help New-Module -Examples". @@ -166,9 +182,11 @@ REMARKS For online help, type: "Get-Help New-Module -Online" ``` -In the previous chapter, I mentioned that functions should use approved verbs otherwise they'll -generate a warning message when the module is imported. The following code uses the `New-Module` -cmdlet to create a dynamic module in memory. This module demonstrates the unapproved verb warning. +The previous chapter mentioned that functions should use approved verbs. Otherwise, PowerShell +generates a warning when the module is imported. + +The following example uses the `New-Module` cmdlet to create a dynamic module in memory, +specifically to demonstrate what happens when you don't use an approved verb. ```powershell New-Module -Name MyModule -ScriptBlock { @@ -190,10 +208,11 @@ unapproved verbs, run the Import-Module command again with the Verbose parameter list of approved verbs, type Get-Verb. ``` -Just to reiterate, although the `New-Module` cmdlet was used in the previous example, that's not the +Although you used the `New-Module` cmdlet in the previous example, as mentioned before, it's not the command for creating script modules in PowerShell. -Save the following two functions in a file named `MyScriptModule.psm1`. +To create a script module, save your functions in a `.psm1` file. For example, save the following +two functions in a file named `MyScriptModule.psm1`. ```powershell function Get-MrPSVersion { @@ -205,53 +224,61 @@ function Get-MrComputerName { } ``` -Try to call one of the functions. +Try to run one of the functions. ```powershell Get-MrComputerName ``` +When you call the function, you receive an error saying PowerShell can't find it. Like before, +checking the **Function:** PSDrive confirms that it isn't loaded into memory. + ```Output -Get-MrComputerName : The term 'Get-MrComputerName' is not recognized as the name of a -cmdlet, function, script file, or operable program. Check the spelling of the name, or -if a path was included, verify that the path is correct and try again. +Get-MrComputerName : The term 'Get-MrComputerName' is not recognized as the +name of a cmdlet, function, script file, or operable program. Check the +spelling of the name, or if a path was included, verify that the path is +correct and try again. At line:1 char:1 + Get-MrComputerName - + CategoryInfo : ObjectNotFound: (Get-MrComputerName:String) [], CommandNot - FoundException ++ ~~~~~~~~~~~~~~~~~~ + + CategoryInfo : ObjectNotFound: (Get-MrComputerName:String) [ + ], CommandNotFoundException + FullyQualifiedErrorId : CommandNotFoundException ``` -An error message is generated saying the function can't be found. You could also check the -**Function** PSDrive just like before and you'll find that it doesn't exist there either. - -You could manually import the file with the `Import-Module` cmdlet. +To make the function available, you can manually import the `MyScriptModule.psm1` file using the +`Import-Module` cmdlet. ```powershell Import-Module C:\MyScriptModule.psm1 ``` -The module autoloading feature was introduced in PowerShell version 3. To take advantage of module -autoloading, a script module needs to be saved in a folder with the same base name as the `.psm1` -file and in a location specified in `$env:PSModulePath`. +PowerShell introduced module autoloading in version 3. To take advantage of this feature, the script +module must be saved in a folder with the same base name as the `.psm1` file. That folder must be +located in one of the directories specified in the `$env:PSModulePath` environment variable. ```powershell $env:PSModulePath ``` +The output of `$env:PSModulePath` is difficult to read. + ```Output -C:\Users\mike-ladm\Documents\WindowsPowerShell\Modules;C:\Program Files\WindowsPowerShell\ -Modules;C:\Windows\system32\WindowsPowerShell\v1.0\Modules;C:\Program Files (x86)\Microsof -t SQL Server\130\Tools\PowerShell\Modules\ +C:\Users\mike-ladm\Documents\WindowsPowerShell\Modules;C:\Program Files\Wind +owsPowerShell\Modules;C:\Windows\system32\WindowsPowerShell\v1.0\Modules;C:\ +Program Files (x86)\Microsoft SQL Server\130\Tools\PowerShell\Modules\ ``` -The results are difficult to read. Since the paths are separated by a semicolon, you can split the -results to return each path on a separate line. This makes them easier to read. +To make the results more readable, split the paths on the semicolon path separator so each one +appears on its own line. ```powershell $env:PSModulePath -split ';' ``` +The first three paths in the list are the default module locations. SQL Server Management Studio +added the last path when you installed it. + ```Output C:\Users\mike-ladm\Documents\WindowsPowerShell\Modules C:\Program Files\WindowsPowerShell\Modules @@ -259,63 +286,84 @@ C:\Windows\system32\WindowsPowerShell\v1.0\Modules C:\Program Files (x86)\Microsoft SQL Server\130\Tools\PowerShell\Modules\ ``` -The first three paths in the list are the default. When SQL Server Management Studio was installed, -it added the last path. For module autoloading to work, the `MyScriptModule.psm1` file needs to be -located in a folder named `MyScriptModule` directly inside one of those paths. +For module autoloading to work, you must place the `MyScriptModule.psm1` file must in a folder named +`MyScriptModule`, and that folder must reside directly inside one of the paths listed in +`$env:PSModulePath`. + +Not all those paths are equally useful. For example, the current user path on my system isn't the +first one in the list. That's because I sign in to Windows with a different account than the one I +use to run PowerShell. So, it doesn't point to my user's documents folder. -Not so fast. For me, my current user path isn't the first one in the list. I almost never use that -path since I log into Windows with a different user than the one I use to run PowerShell. That means -it's not located in my normal Documents folder. +The second path is the **AllUsers** path, which is where I store all of my modules. -The second path is the **AllUsers** path. This is the location where I store all of my modules. +The third path points to `C:\Windows\System32`, a protected system location. Only Microsoft should +be placing modules there, as it falls under the operating system's directory structure. -The third path is underneath `C:\Windows\System32`. Only Microsoft should be storing modules in that -location since it resides within the operating systems folder. +Once you place the `.psm1` file in an appropriate folder within one of these paths, PowerShell +automatically loads the module the first time you call one of its commands. -Once the `.psm1` file is located in the correct path, the module will load automatically when one of -its commands is called. +## Module manifests -## Module Manifests +Every module should include a module manifest, which is a `.psd1` file containing metadata about the +module. While the `.psd1` extension is used for manifests, not all `.psd1` files are module +manifests. You can also use them for other purposes, such as defining environment data in a DSC +configuration. -All modules should have a module manifest. A module manifest contains metadata about your module. -The file extension for a module manifest file is `.psd1`. Not all files with a `.psd1` extension are -module manifests. They can also be used for things such as storing the environmental portion of a -DSC configuration. `New-ModuleManifest` is used to create a module manifest. **Path** is the only -value that's required. However, the module won't work if **RootModule** isn't specified. It's a good -idea to specify **Author** and **Description** in case you decide to upload your module to a NuGet -repository with PowerShellGet since those values are required in that scenario. +You can create a module manifest using the `New-ModuleManifest` cmdlet. The only required parameter +is **Path**, but for the module to work correctly, you must also specify the **RootModule** +parameter. -The version of a module without a manifest is 0.0. This is a dead giveaway that the module doesn't -have a manifest. +It's a best practice to include values like **Author** and **Description**, especially if you plan +to publish your module to a NuGet repository using **PowerShellGet**. These fields are required in +that scenario. + +One quick way to tell if a module lacks a manifest is to check its version. ```powershell Get-Module -Name MyScriptModule ``` +A version number of `0.0` is a clear sign that the module lacks a manifest. + ```Output ModuleType Version Name ExportedCommands ---------- ------- ---- ---------------- -Script 0.0 myscriptmodule {Get-MrComputerName, Get-MrP... +Script 0.0 MyScriptModule {Get-MrComputer... ``` -The module manifest can be created with all of the recommended information. +You should include all recommended details when creating a module manifest to ensure your module is +well-documented and ready for sharing or publishing. ```powershell -New-ModuleManifest -Path $env:ProgramFiles\WindowsPowerShell\Modules\MyScriptModule\MyScriptModule.psd1 -RootModule MyScriptModule -Author 'Mike F Robbins' -Description 'MyScriptModule' -CompanyName 'mikefrobbins.com' +$moduleManifestParams = @{ + Path = "$env:ProgramFiles\WindowsPowerShell\Modules\MyScriptModule\MyScriptModule.psd1" + RootModule = 'MyScriptModule' + Author = 'Mike F. Robbins' + Description = 'MyScriptModule' + CompanyName = 'mikefrobbins.com' +} + +New-ModuleManifest @moduleManifestParams ``` -If any of this information is missed during the initial creation of the module manifest, it can be -added or updated later using `Update-ModuleManifest`. Don't recreate the manifest using -`New-ModuleManifest` once it's already created because the GUID will change. +If you omit any values when initially creating the module manifest, you can add or update it later +using the `Update-ModuleManifest` cmdlet. Avoid recreating the manifest with `New-ModuleManifest` +once you create it, as doing so generates a new GUID. -## Defining Public and Private Functions +## Defining public and private functions -You may have helper functions that you may want to be private and only accessible by other functions -within the module. They are not intended to be accessible to users of your module. There are a -couple of different ways to accomplish this. +Sometimes, your module might include helper functions you don't want to expose to users. These +private functions are used internally by other functions in the module but aren't exposed to users. +There are a few ways to handle this scenario. -If you're not following the best practices and only have a `.psm1` file, then your only option is to -use the `Export-ModuleMember` cmdlet. +If you're not following best practices and only have a `.psm1` file without a proper module +structure, your only option is to control visibility using the `Export-ModuleMember` cmdlet. This +option lets you explicitly define which functions should be exposed directly from within the `.psm1` +script module file, keeping everything else private by default. + +In the following example, only the `Get-MrPSVersion` function is exposed to users of your module, +while the `Get-MrComputerName` function remains accessible internally to other functions within the +module. ```powershell function Get-MrPSVersion { @@ -329,53 +377,53 @@ function Get-MrComputerName { Export-ModuleMember -Function Get-MrPSVersion ``` -In the previous example, only the `Get-MrPSVersion` function is available to the users of your -module, but the `Get-MrComputerName` function is available to other functions within the module -itself. +Determine what commands are available publicly in the **MyScriptModule** module. ```powershell Get-Command -Module MyScriptModule ``` ```Output -CommandType Name Version Source ------------ ---- ------- ------ -Function Get-MrPSVersion 1.0 MyScriptModule +CommandType Name Version +----------- ---- ------- +Function Get-MrPSVersion 1.0 ``` -If you've added a module manifest to your module (and you should), then I recommend specifying the -individual functions you want to export in the **FunctionsToExport** section of the module manifest. +If you add a module manifest to your module, it's a best practice to explicitly list the functions +you want to export in the **FunctionsToExport** section. This option gives you control over what you +expose to users from the `.psd1` module manifest file. ```powershell FunctionsToExport = 'Get-MrPSVersion' ``` -It's not necessary to use both `Export-ModuleMember` in the `.psm1` file and the -**FunctionsToExport** section of the module manifest. One or the other is sufficient. +You don't need to use both `Export-ModuleMember` in the `.psm1` file and the `FunctionsToExport` +section in the module manifest. Either approach is enough on its own. ## Summary -In this chapter you've learned how to turn your functions into a script module in PowerShell. You've -also learned some of the best practices for creating script modules such as creating a module -manifest for your script module. +In this chapter, you learned how to turn your functions into a script module in PowerShell. You also +explored best practices for creating script modules, including the importance of adding a module +manifest to define metadata and manage exported commands. ## Review 1. How do you create a script module in PowerShell? -1. Why is it important for your functions to use an approved verb? +1. Why is it important to use approved verbs for your function names? 1. How do you create a module manifest in PowerShell? -1. What are the two options for exporting only certain functions from your module? -1. What is required for your modules to load automatically when a command is called? +1. What are the two ways to export only specific functions from a module? +1. What conditions must be met for a module to autoload when you run one of its commands? -## Recommended Reading +## References -- [How to Create PowerShell Script Modules and Module Manifests][How to Create PowerShell Script Modules and Module Manifests] -- [about_Modules][about_Modules] -- [New-ModuleManifest][New-ModuleManifest] -- [Export-ModuleMember][Export-ModuleMember] +- [How to Create PowerShell Script Modules and Module Manifests][create-modules-and-manifests] +- [about_Modules][about-modules] +- [New-ModuleManifest][new-modulemanifest] +- [Export-ModuleMember][export-modulemember] -[How to Create PowerShell Script Modules and Module Manifests]: https://mikefrobbins.com/2013/07/04/how-to-create-powershell-script-modules-and-module-manifests/ -[about_Modules]: /powershell/module/microsoft.powershell.core/about/about_modules -[New-ModuleManifest]: /powershell/module/microsoft.powershell.core/new-modulemanifest -[Export-ModuleMember]: /powershell/module/microsoft.powershell.core/export-modulemember + +[create-modules-and-manifests]: https://mikefrobbins.com/2013/07/04/how-to-create-powershell-script-modules-and-module-manifests/ +[about-modules]: /powershell/module/microsoft.powershell.core/about/about_modules +[new-modulemanifest]: /powershell/module/microsoft.powershell.core/new-modulemanifest +[export-modulemember]: /powershell/module/microsoft.powershell.core/export-modulemember diff --git a/reference/docs-conceptual/learn/ps101/appendix-a.md b/reference/docs-conceptual/learn/ps101/appendix-a.md deleted file mode 100644 index 73bbe62762a3..000000000000 --- a/reference/docs-conceptual/learn/ps101/appendix-a.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -description: This article explains how to read and understand the syntax of a cmdlet as presented by Get-Help. -ms.custom: Contributor-mikefrobbins -ms.date: 11/16/2022 -ms.reviewer: mirobb -title: Appendix A - Help Syntax ---- -# Appendix A - Help Syntax - -The following example shows the **SYNTAX** section of the help for the `Get-EventLog` cmdlet. - -```powershell -help Get-EventLog -``` - -```Output -NAME - Get-EventLog - -SYNOPSIS - Gets the events in an event log, or a list of the event logs, on the local or remote - computers. - - -SYNTAX - Get-EventLog [-LogName] [[-InstanceId] ] [-After ] - [-AsBaseObject] [-Before ] [-ComputerName ] [-EntryType {Error | - Information | FailureAudit | SuccessAudit | Warning}] [-Index ] [-Message - ] [-Newest ] [-Source ] [-UserName ] - [] - - Get-EventLog [-AsString] [-ComputerName ] [-List] [] -``` - -Only the relevant portion of the help is shown in this example. - -The syntax is primarily made up of several sets of opening and closing brackets (`[]`). These have -two different meanings depending on how they're used. Anything contained within square brackets is -optional unless they're a set of empty square brackets `[]`. Empty square brackets only appear -after a datatype such as ``. This means that particular parameter can accept more than -one value of that type. - -The first parameter in the first parameter set of `Get-EventLog` is **LogName**. LogName is -surrounded by square brackets which means that it's a positional parameter. In other words, -specifying the name of the parameter itself is optional as long as it's specified in the correct -position. The information in the angle brackets (`<>`) after the parameter name indicates that it -needs a single **string** value. The entire parameter name and datatype are not surrounded by square -brackets so the **LogName** parameter is required when using this parameter set. - -```powershell -Get-EventLog [-LogName] -``` - -The second parameter is **InstanceId**. Notice that the parameter name and the datatype are both -completely surrounded by square brackets. This means that the **InstanceId** parameter is optional, -not mandatory. Also notice that **InstanceId** is surrounded by its own set of square brackets. As -with the **LogName** parameter, this means the parameter is positional. There's one last set of -square brackets after the datatype. This means that it can accept more than one value in the form of -an array or a comma-separated list. - -``` -[[-InstanceId] ] -``` - -The second parameter set has a **List** parameter. It's a switch parameter because there's no -datatype following the parameter name. When the **List** parameter is specified, the value is -**True**. When it's not specified, the value is **False**. - -``` -[-List] -``` - -The syntax information for a command can also be retrieved using `Get-Command` using the **Syntax** -parameter. This is a handy shortcut that I use all the time. It allows me to quickly learn how to -use a command without having to sift through multiple pages of help information. If I end up needing -more information, then I'll revert to using the actual help content. - -```powershell -Get-Command -Name Get-EventLog -Syntax -``` - -```Output -Get-EventLog [-LogName] [[-InstanceId] ] [-ComputerName ] [-Newest ] - [-After ] [-Before ] [-UserName ] [-Index ] - [-EntryType ] [-Source ] [-Message ] [-AsBaseObject] - [] - -Get-EventLog [-ComputerName ] [-List] [-AsString] [] -``` - -The more you use the help system in PowerShell, the easier remembering all of the different nuances -becomes. Before you know it, using it becomes second nature. diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index c21c3d5abeb2..438e00c09c16 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -70,8 +70,6 @@ items: href: learn/ps101/09-functions.md - name: Script modules href: learn/ps101/10-script-modules.md - - name: Appendix A - Help Syntax - href: learn/ps101/appendix-a.md - name: Optimizing your shell experience items: - name: Overview of the Shell diff --git a/reference/docs-conceptual/windows-powershell/Starting-Windows-PowerShell.md b/reference/docs-conceptual/windows-powershell/Starting-Windows-PowerShell.md index 24b02b093cf9..b3435fab451a 100644 --- a/reference/docs-conceptual/windows-powershell/Starting-Windows-PowerShell.md +++ b/reference/docs-conceptual/windows-powershell/Starting-Windows-PowerShell.md @@ -1,23 +1,23 @@ --- description: This article explains the ways of starting various versions of PowerShell. -ms.date: 03/04/2024 +ms.date: 03/27/2025 title: Starting Windows PowerShell --- # Starting Windows PowerShell -Windows PowerShell is a scripting engine that's embedded into multiple hosts. The most common hosts -you'll start are the interactive command-line `powershell.exe` and the Interactive Scripting -Environment `powershell_ise.exe`. +Windows PowerShell is a scripting engine embedded into multiple hosts. The most common hosts are the +interactive command-line `powershell.exe` and the Interactive Scripting Environment +`powershell_ise.exe`. -## PowerShell has renamed binary +## PowerShell binary name -PowerShell version 6 and higher uses .NET Core. Supported versions are available on Windows, macOS, -and Linux. +PowerShell version 6 and higher uses .NET (Core). Supported versions are available on Windows, +macOS, and Linux. -Beginning in PowerShell 6, the PowerShell binary was renamed `pwsh.exe` for Windows and `pwsh` for -macOS and Linux. You can start PowerShell preview versions using `pwsh-preview`. For more -information, see [About pwsh][04]. +Beginning in PowerShell 6, the PowerShell binary named `pwsh.exe` for Windows and `pwsh` for macOS +and Linux. You can start PowerShell preview versions using `pwsh-preview`. For more information, see +[About pwsh][04]. To find cmdlet reference and installation documentation for PowerShell 7, use the following links: @@ -30,12 +30,12 @@ To find cmdlet reference and installation documentation for PowerShell 7, use th To view content for other PowerShell versions, see [How to use the PowerShell documentation][01]. -### From the Start Menu +### Run from the Start Menu - Open the **Start** menu, type **Windows PowerShell**, select **Windows PowerShell**, then select **Open**. -### At the Command Prompt +### Run from the Command Prompt In Windows Command shell, Windows PowerShell, or Windows PowerShell ISE, to start Windows PowerShell, type: `PowerShell`. @@ -43,7 +43,7 @@ PowerShell, type: `PowerShell`. You can also use the parameters of the `powershell.exe` program to customize the session. For more information, see [about_PowerShell_exe][03]. -### With Administrative privileges (Run as administrator) +### Run with administrative privileges Open the **Start** menu, type **Windows PowerShell**, select **Windows PowerShell**, and then select **Run as administrator**. @@ -52,7 +52,7 @@ select **Run as administrator**. Use any of the following methods to start Windows PowerShell ISE. -### From the Start Menu +### Run from the Start Menu - Open the **Start** menu, type **ISE**, select **Windows PowerShell ISE**, then select **Open**. @@ -61,23 +61,22 @@ Use any of the following methods to start Windows PowerShell ISE. In Windows Command shell, Windows PowerShell, or Windows PowerShell ISE, to start Windows PowerShell, type: `PowerShell_ISE`. In Windows PowerShell, you can use the alias `ise`. -### With Administrative privileges (Run as administrator) +### Run with administrative privileges -Click **Start**, type **ISE**, right-click **Windows PowerShell ISE**, and then click **Run as +Select **Start**, type **ISE**, right-click **Windows PowerShell ISE**, and then click **Run as administrator**. ## Starting the 32-Bit Version of Windows PowerShell -When using a 64-bit computer, **Windows PowerShell (x86)**, a 32-bit version of Windows PowerShell -is installed in addition to the 64-bit version. When you run Windows PowerShell, the 64-bit version -runs by default. +64-bit versions of Windows include a 32-bit version of Windows PowerShell, **Windows PowerShell +(x86)**, in addition to the 64-bit version. The 64-bit version runs by default. However, you might occasionally need to run **Windows PowerShell (x86)**, such as when you're using a module that requires the 32-bit version or when you're connecting remotely to a 32-bit computer. To start a 32-bit version of Windows PowerShell, use any of the following procedures. -- Click **Start**, type **Windows PowerShell**, select **Windows PowerShell (x86)**, then select +- Select **Start**, type **Windows PowerShell**, select **Windows PowerShell (x86)**, then select **Open**. diff --git a/reference/docs-conceptual/windows-powershell/ise/Accessibility-in-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/Accessibility-in-Windows-PowerShell-ISE.md index c63de147996a..25023455ff9c 100644 --- a/reference/docs-conceptual/windows-powershell/ise/Accessibility-in-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/Accessibility-in-Windows-PowerShell-ISE.md @@ -1,6 +1,6 @@ --- description: This topic describes the accessibility features of Windows PowerShell Integrated Scripting Environment (ISE) that you might find helpful. -ms.date: 12/19/2019 +ms.date: 03/27/2025 ms.topic: ui-reference title: Accessibility in Windows PowerShell ISE --- @@ -10,14 +10,14 @@ title: Accessibility in Windows PowerShell ISE This topic describes the accessibility features of Windows PowerShell Integrated Scripting Environment (ISE) that you might find helpful. -- [How to change the size and location of the Console and Script Panes](#how-to-change-the-size-and-location-of-the-console-and-script-panes) -- [Keyboard shortcuts for editing text](#keyboard-shortcuts-for-editing-text) -- [Keyboard shortcuts for running scripts](#keyboard-shortcuts-for-running-scripts) -- [Keyboard shortcuts for customizing the view](#keyboard-shortcuts-for-customizing-the-view) -- [Keyboard shortcuts for debugging scripts](#keyboard-shortcuts-for-debugging-scripts) -- [Keyboard shortcuts for Windows PowerShell tabs](#keyboard-shortcuts-for-windows-powershell-tabs) -- [Keyboard shortcuts for starting and exiting](#keyboard-shortcuts-for-starting-and-exiting) -- [Breakpoint management with cmdlets](#breakpoint-management) +- [How to change the size and location of the Console and Script Panes][04] +- [Keyboard shortcuts for editing text][07] +- [Keyboard shortcuts for running scripts][08] +- [Keyboard shortcuts for customizing the view][05] +- [Keyboard shortcuts for debugging scripts][06] +- [Keyboard shortcuts for Windows PowerShell tabs][10] +- [Keyboard shortcuts for starting and exiting][09] +- [Breakpoint management with cmdlets][03] Microsoft is committed to making its products and services easier for everyone to use. The following topics provide information about the features, products, and services that make Windows PowerShell @@ -29,7 +29,7 @@ make Windows PowerShell ISE more accessible for people with disabilities: - Keyboard Shortcuts - Syntax Coloring Table and the ability to modify several other color settings using the - [$psISE.Options](object-model/The-ISEOptions-Object.md) scripting object. + [$psISE.Options][13] scripting object. - Text Size Change @@ -175,12 +175,24 @@ You can use the following keyboard shortcuts to start the Windows PowerShell con ## Breakpoint Management For the visually impaired, breakpoint information is available through the cmdlets for managing -breakpoints, such as -[Get-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Get-PSBreakpoint) and -[Set-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Set-PSBreakpoint). For more -information please see 'How to manage breakpoints' in -[How to Debug Scripts in the Windows PowerShell ISE](How-to-Debug-Scripts-in-Windows-PowerShell-ISE.md). +breakpoints, such as [Get-PSBreakpoint][01] and [Set-PSBreakpoint][02]. For more information please +see 'How to manage breakpoints' in [How to Debug Scripts in the Windows PowerShell ISE][11]. ## See Also -[Introducing the Windows PowerShell ISE](Introducing-the-Windows-PowerShell-ISE.md) +[Introducing the Windows PowerShell ISE][12] + + +[01]: /powershell/module/Microsoft.PowerShell.Utility/Get-PSBreakpoint +[02]: /powershell/module/Microsoft.PowerShell.Utility/Set-PSBreakpoint +[03]: #breakpoint-management +[04]: #how-to-change-the-size-and-location-of-the-console-and-script-panes +[05]: #keyboard-shortcuts-for-customizing-the-view +[06]: #keyboard-shortcuts-for-debugging-scripts +[07]: #keyboard-shortcuts-for-editing-text +[08]: #keyboard-shortcuts-for-running-scripts +[09]: #keyboard-shortcuts-for-starting-and-exiting +[10]: #keyboard-shortcuts-for-windows-powershell-tabs +[11]: How-to-Debug-Scripts-in-Windows-PowerShell-ISE.md +[12]: Introducing-the-Windows-PowerShell-ISE.md +[13]: object-model/The-ISEOptions-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/Exploring-the-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/Exploring-the-Windows-PowerShell-ISE.md index f8989f9011be..f457df2ce225 100644 --- a/reference/docs-conceptual/windows-powershell/ise/Exploring-the-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/Exploring-the-Windows-PowerShell-ISE.md @@ -1,7 +1,7 @@ --- description: This article is an overview of the features of the Windows PowerShell ISE ms.custom: ISE-F1-page -ms.date: 05/04/2023 +ms.date: 03/27/2025 ms.topic: ui-reference title: Exploring the Windows PowerShell ISE --- @@ -11,26 +11,25 @@ title: Exploring the Windows PowerShell ISE You can use the Windows PowerShell Integrated Scripting Environment (ISE) to create, run, and debug commands and scripts. -![Screenshot of the full ISE window.](media/exploring-the-windows-powershell-ise/full-ise-window.png) +![Screenshot of the full ISE window.][10] -The Windows PowerShell ISE consists of the menu bar, Windows PowerShell tabs, -the toolbar, script tabs, a Script Pane, a Console Pane, a status bar, a text-size slider and -context-sensitive Help. +The Windows PowerShell ISE consists of the menu bar, Windows PowerShell tabs, the toolbar, script +tabs, a Script Pane, a Console Pane, a status bar, a text-size slider and context-sensitive Help. ## Menu Bar The menu bar contains the **File**, **Edit**, **View**, **Tools**, **Debug**, **Add-ons**, and **Help** menus. -![Screenshot of the menu bar.](media/exploring-the-windows-powershell-ise/ise-menu-bar.png) +![Screenshot of the menu bar.][11] The buttons on the menus allow you to perform tasks related to writing and running scripts and -running commands in the Windows PowerShell ISE. Additionally, an [add-on tool][11] may be placed on -the menu bar by running scripts that use the [The ISE Object Model Hierarchy][10]. +running commands in the Windows PowerShell ISE. Additionally, an [add-on tool][17] may be placed on +the menu bar by running scripts that use the [The ISE Object Model Hierarchy][16]. ## Toolbar -![Screenshot of the tool bar.](media/exploring-the-windows-powershell-ise/ise-tool-bar.png) +![Screenshot of the tool bar.][15] The following buttons are located on the toolbar. @@ -58,7 +57,7 @@ The following buttons are located on the toolbar. ## Windows PowerShell Tabs -![Screenshot of the Windows PowerShell tabs.](media/exploring-the-windows-powershell-ise/ise-powershell-tabs.png) +![Screenshot of the Windows PowerShell tabs.][13] A Windows PowerShell tab is the environment in which a Windows PowerShell script runs. You can open new Windows PowerShell tabs in the Windows PowerShell ISE to create separate environments on your @@ -69,7 +68,7 @@ For more information, see [How to Create a PowerShell Tab in Windows PowerShell ## Script Tab -![Screenshot of the script tabs.](media/exploring-the-windows-powershell-ise/ise-script-tabs.png) +![Screenshot of the script tabs.][14] Displays the name of the script you are editing. You can click a script tab to select the script you want to edit. @@ -78,7 +77,7 @@ When you point to the script tab, the fully qualified path to the script file ap ## Script Pane -![Screenshot of the panes and status bar.](media/exploring-the-windows-powershell-ise/ise-panes.png) +![Screenshot of the panes and status bar.][12] Allows you to create and run scripts. You can open, edit and run existing scripts in the Script Pane. For more information, see [How to Write and Run Scripts in the Windows PowerShell ISE][07]. @@ -108,7 +107,7 @@ Increases or decreases the size of the text on the screen. Help for Windows PowerShell ISE is available on Microsoft Learn. You can open the Help by clicking **Windows PowerShell ISE Help** on the **Help** menu or by pressing the F1 key anywhere except when the cursor is on a cmdlet name in either the Script Pane or the Console Pane. From the -**Help** menu you can also run the `Update-Help` cmdlet, and display the Command Window which +**Help** menu you can also run the `Update-Help` cmdlet, and display the Command Window, which assists you in constructing commands by showing you all the parameters for a cmdlet and enabling you to fill in the parameters in an easy-to-use form. @@ -129,5 +128,11 @@ to fill in the parameters in an easy-to-use form. [07]: How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md [08]: Introducing-the-Windows-PowerShell-ISE.md [09]: Keyboard-Shortcuts-for-the-Windows-PowerShell-ISE.md -[10]: object-model/The-ISE-Object-Model-Hierarchy.md -[11]: object-model/The-ISEAddOnTool-Object.md +[10]: media/exploring-the-windows-powershell-ise/full-ise-window.png +[11]: media/exploring-the-windows-powershell-ise/ise-menu-bar.png +[12]: media/exploring-the-windows-powershell-ise/ise-panes.png +[13]: media/exploring-the-windows-powershell-ise/ise-powershell-tabs.png +[14]: media/exploring-the-windows-powershell-ise/ise-script-tabs.png +[15]: media/exploring-the-windows-powershell-ise/ise-tool-bar.png +[16]: object-model/The-ISE-Object-Model-Hierarchy.md +[17]: object-model/The-ISEAddOnTool-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/How-to-Create-a-PowerShell-Tab-in-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/How-to-Create-a-PowerShell-Tab-in-Windows-PowerShell-ISE.md index c24c64e9ee3d..0edaa3a9070b 100644 --- a/reference/docs-conceptual/windows-powershell/ise/How-to-Create-a-PowerShell-Tab-in-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/How-to-Create-a-PowerShell-Tab-in-Windows-PowerShell-ISE.md @@ -1,6 +1,6 @@ --- description: Tabs in the Windows PowerShell Integrated Scripting Environment (ISE) allow you to simultaneously create and use several execution environments within the same application. Each PowerShell tab corresponds to a separate execution environment or session. -ms.date: 10/07/2021 +ms.date: 03/27/2025 ms.topic: ui-reference title: How to Create a PowerShell Tab in Windows PowerShell ISE --- @@ -12,21 +12,20 @@ create and use several execution environments within the same application. Each corresponds to a separate execution environment or session. > [!NOTE] -> Variables, functions, and aliases that you create in one tab do not carry over to another. They +> Variables, functions, and aliases that you create in one tab don't carry over to another. They > are different Windows PowerShell sessions. Use the following steps to open or close a tab in Windows PowerShell. To rename a tab, set the -[DisplayName](object-model/The-PowerShellTab-Object.md#displayname) property on the Windows -PowerShell Tab scripting object. +[DisplayName][04] property on the Windows PowerShell Tab scripting object. ## To create and use a new PowerShell Tab On the **File** menu, click **New PowerShell Tab**. The new PowerShell tab always opens as the -active window. PowerShell tabs are incrementally numbered in the order that they are opened. Each -tab is associated with its own Windows PowerShell console window. You can have up to 32 PowerShell -tabs with their own session open at a time (this is limited to 8 on Windows PowerShell ISE 2.0.) +active window. PowerShell tabs are incrementally numbered in the order that they're opened. Each tab +is associated with its own Windows PowerShell console window. You can have up to 32 PowerShell tabs +with their own session open at a time (this is limited to 8 on Windows PowerShell ISE 2.0.) -Note that clicking the **New** or **Open** icons on the toolbar does not create a new tab with a +Note that clicking the **New** or **Open** icons on the toolbar doesn't create a new tab with a separate session. Instead, those buttons open a new or existing script file on the currently active tab with a session. You can have multiple script files open with each tab and session. The script tabs for a session only appear below the session tabs when the associated session is active. @@ -51,10 +50,15 @@ To close a tab, you can use any of the following techniques: active tab to close the tab. If you have unsaved files open in the PowerShell tab that you are closing, you are prompted to save -or discard them. For more information about how to save a script, see -[How to Save a Script](How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md#how-to-save-a-script). +or discard them. For more information about how to save a script, see [How to Save a Script][02]. ## See Also -- [Introducing the Windows PowerShell ISE](Introducing-the-Windows-PowerShell-ISE.md) -- [How to Use the Console Pane in the Windows PowerShell ISE](How-to-Use-the-Console-Pane-in-the-Windows-PowerShell-ISE.md) +- [Introducing the Windows PowerShell ISE][03] +- [How to Use the Console Pane in the Windows PowerShell ISE][01] + + +[01]: How-to-Use-the-Console-Pane-in-the-Windows-PowerShell-ISE.md +[02]: How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md#how-to-save-a-script +[03]: Introducing-the-Windows-PowerShell-ISE.md +[04]: object-model/The-PowerShellTab-Object.md#displayname diff --git a/reference/docs-conceptual/windows-powershell/ise/How-to-Debug-Scripts-in-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/How-to-Debug-Scripts-in-Windows-PowerShell-ISE.md index 0018b13f5915..d54a8317b71f 100644 --- a/reference/docs-conceptual/windows-powershell/ise/How-to-Debug-Scripts-in-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/How-to-Debug-Scripts-in-Windows-PowerShell-ISE.md @@ -1,6 +1,6 @@ --- description: This article describes how to debug scripts on a local computer by using the Windows PowerShell ISE visual debugging features. -ms.date: 10/07/2021 +ms.date: 03/27/2025 ms.topic: ui-reference title: How to Debug Scripts in Windows PowerShell ISE --- @@ -32,10 +32,9 @@ You can set three types of breakpoints in the Windows PowerShell debugging envir Of these, in the Windows PowerShell ISE debugging environment, only line breakpoints can be set by using the menu or the keyboard shortcuts. The other two types of breakpoints can be set, but they -are set from the Console Pane by using the -[Set-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Set-PSBreakpoint) cmdlet. This -section describes how you can perform debugging tasks in Windows PowerShell ISE by using the menus -where available, and perform a wider range of commands from the Console Pane by using scripting. +are set from the Console Pane by using the [Set-PSBreakpoint][05] cmdlet. This section describes how +you can perform debugging tasks in Windows PowerShell ISE by using the menus where available, and +perform a wider range of commands from the Console Pane by using scripting. ### To set a breakpoint @@ -45,8 +44,7 @@ want to set a line breakpoint, and press F9 or, on the **Debug** menu Breakpoint**. The following script is an example of how you can set a variable breakpoint from the Console Pane by -using the [Set-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Set-PSBreakpoint) -cmdlet. +using the [Set-PSBreakpoint][05] cmdlet. ```powershell # This command sets a breakpoint on the Server variable in the Sample.ps1 script. @@ -58,8 +56,7 @@ Set-PSBreakpoint -Script sample.ps1 -Variable Server Displays all breakpoints in the current Windows PowerShell session. On the **Debug** menu, click **List Breakpoints**. The following script is an example of how you can -list all breakpoints from the Console Pane by using the -[Get-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Get-PSBreakpoint) cmdlet. +list all breakpoints from the Console Pane by using the [Get-PSBreakpoint][03] cmdlet. ```powershell # This command lists all breakpoints in the current session. @@ -70,12 +67,11 @@ Get-PSBreakpoint Removing a breakpoint deletes it. -If you think you might want to use it again later, consider -[Disable a Breakpoint](#disable-a-breakpoint) it instead. Right-click the line where you want to -remove a breakpoint, and then click **ToggleBreakpoint**. Or, click the line where you want to -remove a breakpoint, and on the **Debug** menu, click **Toggle Breakpoint**. The following script is -an example of how to remove a breakpoint with a specified ID from the Console Pane by using the -[Remove-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Remove-PSBreakpoint) cmdlet. +If you think you might want to use it again later, consider [Disable a Breakpoint][06] it instead. +Right-click the line where you want to remove a breakpoint, and then click **ToggleBreakpoint**. Or, +click the line where you want to remove a breakpoint, and on the **Debug** menu, click **Toggle +Breakpoint**. The following script is an example of how to remove a breakpoint with a specified ID +from the Console Pane by using the [Remove-PSBreakpoint][04] cmdlet. ```powershell # This command deletes the breakpoint with breakpoint ID 2. @@ -88,8 +84,7 @@ To remove all breakpoints defined in the current session, on the **Debug** menu, Breakpoints**. The following script is an example of how to remove all breakpoints from the Console Pane by using -the [Remove-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Remove-PSBreakpoint) -cmdlet. +the [Remove-PSBreakpoint][04] cmdlet. ```powershell # This command deletes all of the breakpoints in the current session. @@ -98,14 +93,14 @@ Get-PSBreakpoint | Remove-PSBreakpoint ### Disable a Breakpoint -Disabling a breakpoint does not remove it. It turns it off until it is enabled. To disable a -specific line breakpoint, right-click the line where you want to disable a breakpoint, and then -click **Disable Breakpoint**. +Disabling a breakpoint doesn't remove it. It turns it off until it's enabled. To disable a specific +line breakpoint, right-click the line where you want to disable a breakpoint, and then click +**Disable Breakpoint**. Or, click the line where you want to disable a breakpoint, and press F9 or, on the **Debug** menu, click **Disable Breakpoint**. The following script is an example of how you can -remove a breakpoint with a specified ID from the Console Pane using the -[Disable-PSBreakpoint](/powershell/module/microsoft.powershell.utility/disable-psbreakpoint) cmdlet. +remove a breakpoint with a specified ID from the Console Pane using the [Disable-PSBreakpoint][01] +cmdlet. ```powershell # This command disables the breakpoint with breakpoint ID 0. @@ -114,11 +109,10 @@ Disable-PSBreakpoint -Id 0 ### Disable All Breakpoints -Disabling a breakpoint does not remove it; it turns it off until it is enabled. To disable all +Disabling a breakpoint doesn't remove it; it turns it off until it's enabled. To disable all breakpoints in the current session, on the **Debug** menu, click **Disable all Breakpoints**. The following script is an example of how you can disable all breakpoints from the Console Pane by using -the [Disable-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Disable-PSBreakpoint) -cmdlet. +the [Disable-PSBreakpoint][01] cmdlet. ```powershell # This command disables all breakpoints in the current session. @@ -132,7 +126,7 @@ To enable a specific breakpoint, right-click the line where you want to enable a then click **Enable Breakpoint**. Or, click the line where you want to enable a breakpoint, and then press F9 or, on the **Debug** menu, click **Enable Breakpoint**. The following script is an example of how you can enable specific breakpoints from the Console Pane by using the -[Enable-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Enable-PSBreakpoint) cmdlet. +[Enable-PSBreakpoint][02] cmdlet. ```powershell # This command enables breakpoints with breakpoint IDs 0, 1, and 5. @@ -143,8 +137,7 @@ Enable-PSBreakpoint -Id 0, 1, 5 To enable all breakpoints defined in the current session, on the **Debug** menu, click **Enable all Breakpoints**. The following script is an example of how you can enable all breakpoints from the -Console Pane by using the -[Enable-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Enable-PSBreakpoint) cmdlet. +Console Pane by using the [Enable-PSBreakpoint][02] cmdlet. ```powershell # This command enables all breakpoints in the current session. @@ -154,12 +147,11 @@ Get-PSBreakpoint | Enable-PSBreakpoint ## How to manage a debugging session -Before you start debugging, you must set one or more breakpoints. You cannot set a breakpoint unless +Before you start debugging, you must set one or more breakpoints. You can't set a breakpoint unless the script that you want to debug is saved. For directions on of how to set a breakpoint, see -[How to manage breakpoints](#how-to-manage-breakpoints) or -[Set-PSBreakpoint](/powershell/module/Microsoft.PowerShell.Utility/Set-PSBreakpoint). After you -start debugging, you cannot edit a script until you stop debugging. A script that has one or more -breakpoints set is automatically saved before it is run. +[How to manage breakpoints][07] or [Set-PSBreakpoint][05]. After you start debugging, you can't edit +a script until you stop debugging. A script that has one or more breakpoints set is automatically +saved before it's run. ### To start debugging @@ -177,7 +169,7 @@ further breakpoints are encountered. ### To view the call stack The call stack displays the current run location in the script. If the script is running in a -function that was called by a different function, then that is represented in the display by +function that was called by a different function, then that's represented in the display by additional rows in the output. The bottom-most row displays the original script and the line in it in which a function was called. The next line up shows that function and the line in it in which another function might have been called. The top-most row shows the current context of the current @@ -224,16 +216,12 @@ Pane to find the values of variables and call functions that are defined only in ### To display the values of automatic variables You can use the preceding method to display the value of almost all variables while you are -debugging a script. However, these methods do not work for the following automatic variables. +debugging a script. However, these methods don't work for the following automatic variables. - `$_` - - `$input` - - `$MyInvocation` - - `$PSBoundParameters` - - `$args` If you try to display the value of any of these variables, you get the value of that variable for in @@ -267,4 +255,14 @@ C:\ps-test\MyScript.ps1 ## See Also -[Exploring the Windows PowerShell ISE](exploring-the-windows-powershell-ise.md) +[Exploring the Windows PowerShell ISE][08] + + +[01]: /powershell/module/Microsoft.PowerShell.Utility/Disable-PSBreakpoint +[02]: /powershell/module/Microsoft.PowerShell.Utility/Enable-PSBreakpoint +[03]: /powershell/module/Microsoft.PowerShell.Utility/Get-PSBreakpoint +[04]: /powershell/module/Microsoft.PowerShell.Utility/Remove-PSBreakpoint +[05]: /powershell/module/Microsoft.PowerShell.Utility/Set-PSBreakpoint +[06]: #disable-a-breakpoint +[07]: #how-to-manage-breakpoints +[08]: exploring-the-windows-powershell-ise.md diff --git a/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Profiles-in-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Profiles-in-Windows-PowerShell-ISE.md index db3c2458497e..e5c7ce25cee1 100644 --- a/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Profiles-in-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Profiles-in-Windows-PowerShell-ISE.md @@ -1,15 +1,15 @@ --- description: This article explains how to use Profiles in Windows PowerShell ISE. -ms.date: 10/07/2021 +ms.date: 03/27/2025 title: How to Use Profiles in Windows PowerShell ISE --- # How to Use Profiles in Windows PowerShell ISE -This article explains how to use Profiles in Windows PowerShell® Integrated Scripting Environment -(ISE). We recommend that before performing the tasks in this section, you review -[about_Profiles](/powershell/module/microsoft.powershell.core/about/about_profiles), or in the -Console Pane, type, `Get-Help about_Profiles` and press ENTER. +This article explains how to use Profiles in Windows PowerShell® Integrated Scripting +Environment (ISE). We recommend that before performing the tasks in this section, you review +[about_Profiles][02], or in the Console Pane, type, `Get-Help about_Profiles` and press +ENTER. A profile is a Windows PowerShell ISE script that runs automatically when you start a new session. You can create one or more Windows PowerShell profiles for Windows PowerShell ISE and use them to @@ -20,8 +20,8 @@ available. A profile affects every Windows PowerShell ISE session that you start > [!NOTE] > The Windows PowerShell execution policy determines whether you can run scripts and load a profile. > The default execution policy, "Restricted," prevents all scripts from running, including profiles. -> If you use the "Restricted" policy, the profile cannot load. For more information about execution -> policy, see [about_Execution_Policies](/powershell/module/microsoft.powershell.core/about/about_execution_policies). +> If you use the "Restricted" policy, the profile can't load. For more information about execution +> policy, see [about_Execution_Policies][01]. ## Selecting a profile to use in the Windows PowerShell ISE @@ -31,14 +31,14 @@ Windows PowerShell profiles that apply to all hosts. The profile that you use is determined by how you use Windows PowerShell and Windows PowerShell ISE. - If you use only Windows PowerShell ISE to run Windows PowerShell, then save all your items in one - of the ISE-specific profiles, such as the **CurrentUserCurrentHost** profile for Windows PowerShell - ISE or the **AllUsersCurrentHost** profile for Windows PowerShell ISE. + of the ISE-specific profiles, such as the **CurrentUserCurrentHost** profile for Windows + PowerShell ISE or the **AllUsersCurrentHost** profile for Windows PowerShell ISE. - If you use multiple host programs to run Windows PowerShell, save your functions, aliases, variables, and commands in a profile that affects all host programs, such as the - CurrentUserAllHosts or the **AllUsersAllHosts** profile, and save ISE-specific features, like color - and font customization in the **CurrentUserCurrentHost** profile for Windows PowerShell ISE profile or - the **AllUsersCurrentHost** profile for Windows PowerShell ISE. + CurrentUserAllHosts or the **AllUsersAllHosts** profile, and save ISE-specific features, like + color and font customization in the **CurrentUserCurrentHost** profile for Windows PowerShell ISE + profile or the **AllUsersCurrentHost** profile for Windows PowerShell ISE. The following are profiles that can be created and used in Windows PowerShell ISE. Each profile is saved to its own specific path. @@ -55,42 +55,46 @@ saved to its own specific path. To create a new "Current user, Windows PowerShell ISE" profile, run this command: ```powershell -if (!(Test-Path -Path $PROFILE )) -{ New-Item -Type File -Path $PROFILE -Force } +if (!(Test-Path -Path $PROFILE )) { + New-Item -Type File -Path $PROFILE -Force +} ``` To create a new "All users, Windows PowerShell ISE" profile, run this command: ```powershell -if (!(Test-Path -Path $PROFILE.AllUsersCurrentHost)) -{ New-Item -Type File -Path $PROFILE.AllUsersCurrentHost -Force } +if (!(Test-Path -Path $PROFILE.AllUsersCurrentHost)) { + New-Item -Type File -Path $PROFILE.AllUsersCurrentHost -Force +} ``` To create a new "Current user, All Hosts" profile, run this command: ```powershell -if (!(Test-Path -Path $PROFILE.CurrentUserAllHosts)) -{ New-Item -Type File -Path $PROFILE.CurrentUserAllHosts -Force } +if (!(Test-Path -Path $PROFILE.CurrentUserAllHosts)) { + New-Item -Type File -Path $PROFILE.CurrentUserAllHosts -Force +} ``` To create a new "All users, All Hosts" profile, type: ```powershell -if (!(Test-Path -Path $PROFILE.AllUsersAllHosts)) -{ New-Item -Type File -Path $PROFILE.AllUsersAllHosts -Force } +if (!(Test-Path -Path $PROFILE.AllUsersAllHosts)) { + New-Item -Type File -Path $PROFILE.AllUsersAllHosts -Force +} ``` ## To edit a profile -1. To open the profile, run the command `psEdit` with the variable that specifies the profile you want - to edit. For example, to open the "Current user, Windows PowerShell ISE" profile, type: +1. To open the profile, run the command `psEdit` with the variable that specifies the profile you + want to edit. For example, to open the "Current user, Windows PowerShell ISE" profile, type: `psEdit $PROFILE` 1. Add some items to your profile. The following are a few examples to get you started: - To change the default background color of the Console Pane to blue, in the profile file type: `$psISE.Options.OutputPaneBackground = 'blue'` . For more information about the `$psISE` - variable, see [Windows PowerShell ISE Object Model Reference](object-model/The-ISE-Object-Model-Hierarchy.md). + variable, see [Windows PowerShell ISE Object Model Reference][04]. - To change font size to 20, in the profile file type: `$psISE.Options.FontSize =20` @@ -99,5 +103,11 @@ if (!(Test-Path -Path $PROFILE.AllUsersAllHosts)) ## See Also -- [about_Profiles](/powershell/module/microsoft.powershell.core/about/about_profiles) -- [Introducing the Windows PowerShell ISE](Introducing-the-Windows-PowerShell-ISE.md) +- [about_Profiles][02] +- [Introducing the Windows PowerShell ISE][03] + + +[01]: /powershell/module/microsoft.powershell.core/about/about_execution_policies +[02]: /powershell/module/microsoft.powershell.core/about/about_profiles +[03]: Introducing-the-Windows-PowerShell-ISE.md +[04]: object-model/The-ISE-Object-Model-Hierarchy.md diff --git a/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md b/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md index 7eed23e759a5..c72c4696b6ba 100644 --- a/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md +++ b/reference/docs-conceptual/windows-powershell/ise/How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md @@ -1,6 +1,6 @@ --- description: How to Use Tab Completion in the Script Pane and Console Pane -ms.date: 01/02/2020 +ms.date: 03/27/2025 title: How to Use Tab Completion in the Script Pane and Console Pane --- @@ -11,14 +11,15 @@ Pane. Use the following steps to take advantage of this feature: ## To automatically complete a command entry -In the Command Pane or Script Pane, type a few characters of a command and then press TAB to select -the desired completion text. If multiple items begin with the text that you initially typed, then -continue pressing TAB until the item you want appears. Tab completion can help with typing a cmdlet -name, parameter name, variable name, object property name, or a file path. +In the Command Pane or Script Pane, type a few characters of a command and then press TAB +to select the desired completion text. If multiple items begin with the text that you initially +typed, then continue pressing TAB until the item you want appears. Tab completion can +help with typing a cmdlet name, parameter name, variable name, object property name, or a file path. > [!NOTE] -> In the Script Pane, pressing TAB will automatically complete a command only when you are editing -> `.ps1`, `.psd1`, or `.psm1` files. Tab completion works any time when you are typing in the Command Pane. +> In the Script Pane, pressing TAB will automatically complete a command only when you +> are editing `.ps1`, `.psd1`, or `.psm1` files. Tab completion works any time when you are typing +> in the Command Pane. ## To automatically complete a cmdlet parameter entry @@ -29,5 +30,9 @@ the parameters for the cmdlet in turn. ## See Also -- [Introducing the Windows PowerShell ISE](Introducing-the-Windows-PowerShell-ISE.md) -- [How to Create a PowerShell Tab](How-to-Create-a-PowerShell-Tab-in-Windows-PowerShell-ISE.md) +- [Introducing the Windows PowerShell ISE][02] +- [How to Create a PowerShell Tab][01] + + +[01]: How-to-Create-a-PowerShell-Tab-in-Windows-PowerShell-ISE.md +[02]: Introducing-the-Windows-PowerShell-ISE.md diff --git a/reference/docs-conceptual/windows-powershell/ise/How-to-Use-the-Console-Pane-in-the-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/How-to-Use-the-Console-Pane-in-the-Windows-PowerShell-ISE.md index b05869b8f303..17fceb10b4e9 100644 --- a/reference/docs-conceptual/windows-powershell/ise/How-to-Use-the-Console-Pane-in-the-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/How-to-Use-the-Console-Pane-in-the-Windows-PowerShell-ISE.md @@ -1,6 +1,6 @@ --- description: How to Use the Console Pane in the Windows PowerShell ISE -ms.date: 01/02/2020 +ms.date: 03/27/2025 ms.topic: ui-reference title: How to Use the Console Pane in the Windows PowerShell ISE --- @@ -12,9 +12,8 @@ like the stand-alone Windows PowerShell ISE console window. To run a command in the Console Pane, type a command, and then press ENTER. To enter multiple commands that you want to execute in sequence, type SHIFT+ENTER -between commands. See -[How to Use Tab Completion in the Script Pane and Console Pane](How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md) -for help in typing commands. +between commands. See [How to Use Tab Completion in the Script Pane and Console Pane][01] for help +in typing commands. To stop a command, on the toolbar, click **Stop Operation**, or press CTRL+BREAK. You can also use CTRL+C to stop a command if @@ -37,4 +36,8 @@ in procedures that were needed when they were separate. You can: ## See Also -- [Introducing the Windows PowerShell ISE](Introducing-the-Windows-PowerShell-ISE.md) +- [Introducing the Windows PowerShell ISE][02] + + +[01]: How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md +[02]: Introducing-the-Windows-PowerShell-ISE.md diff --git a/reference/docs-conceptual/windows-powershell/ise/How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md index 2ba4e07f144f..14895b0412c3 100644 --- a/reference/docs-conceptual/windows-powershell/ise/How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md @@ -1,6 +1,6 @@ --- description: This article describes how to create, edit, run, and save scripts in the Script Pane. -ms.date: 10/07/2021 +ms.date: 03/27/2025 title: How to Write and Run Scripts in the Windows PowerShell ISE --- @@ -20,22 +20,20 @@ files. > The Windows PowerShell execution policy determines whether you can run scripts and load Windows > PowerShell profiles and configuration files. The default execution policy, Restricted, prevents > all scripts from running, and prevents loading profiles. To change the execution policy to allow -> profiles to load and be used, see -> [Set-ExecutionPolicy](/powershell/module/microsoft.powershell.security/set-executionpolicy) and -> [about_Signing](/powershell/module/microsoft.powershell.core/about/about_signing). +> profiles to load and be used, see [Set-ExecutionPolicy][02] and [about_Signing][01]. ### To create a new script file -On the toolbar, click **New**, or on the **File** menu, click **New**. The created file appears in -a new file tab under the current PowerShell tab. Remember that the PowerShell tabs are only visible +On the toolbar, click **New**, or on the **File** menu, click **New**. The created file appears in a +new file tab under the current PowerShell tab. Remember that the PowerShell tabs are only visible when there are more than one. By default a file of type script (`.ps1`) is created, but it can be saved with a new name and extension. Multiple script files can be created in the same PowerShell tab. ### To open an existing script -On the toolbar, click **Open**, or on the **File** menu, click **Open**. In the **Open** dialog -box, select the file you want to open. The opened file appears in a new tab. +On the toolbar, click **Open**, or on the **File** menu, click **Open**. In the **Open** dialog box, +select the file you want to open. The opened file appears in a new tab. ### To close a script tab @@ -72,8 +70,8 @@ case CTRL+C maps to the copy function for the selected tex ## How to write and edit text in the Script Pane You can copy, cut, paste, find, and replace text in the Script Pane. You can also undo and redo the -last action you just performed. The keyboard shortcuts for these actions are the same shortcuts -used for all Windows applications. +last action you just performed. The keyboard shortcuts for these actions are the same shortcuts used +for all Windows applications. ### To enter text in the Script Pane @@ -81,7 +79,7 @@ used for all Windows applications. to Script Pane** in the **View** menu. 1. Create a script. Syntax coloring and tab completion provide a richer editing experience in Windows PowerShell ISE. -1. See [How to Use Tab Completion in the Script Pane and Console Pane](How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md) +1. See [How to Use Tab Completion in the Script Pane and Console Pane][04] for details about using the tab completion feature to help in typing. ### To find text in the Script Pane @@ -154,9 +152,8 @@ menu, click **Save**. ### To save a script in ASCII encoding By default, Windows PowerShell ISE saves new script files (`.ps1`), script data files (`.psd1`), and -script module files (`.psm1`) as Unicode (BigEndianUnicode). To save a script in another -encoding, such as ASCII (ANSI), use the **Save** or **SaveAs** methods on the -[$psISE.CurrentFile](object-model/the-ise-object-model-hierarchy.md) object. +script module files (`.psm1`) as Unicode (BigEndianUnicode). To save a script in another encoding, +such as ASCII (ANSI), use the **Save** or **SaveAs** methods on the [$psISE.CurrentFile][05] object. The following command saves a new script as MyScript.ps1 with ASCII encoding. @@ -180,9 +177,16 @@ $psISE.CurrentFile.encoding Windows PowerShell ISE supports the following encoding options: ASCII, BigEndianUnicode, Unicode, UTF32, UTF7, UTF8, and Default. The value of the Default option varies with the system. -Windows PowerShell ISE doesn't change the encoding of script files when you use the Save or -Save As commands. +Windows PowerShell ISE doesn't change the encoding of script files when you use the Save or Save As +commands. ## See Also -- [Exploring the Windows PowerShell ISE](exploring-the-windows-powershell-ise.md) +- [Exploring the Windows PowerShell ISE][03] + + +[01]: /powershell/module/microsoft.powershell.core/about/about_signing +[02]: /powershell/module/microsoft.powershell.security/set-executionpolicy +[03]: exploring-the-windows-powershell-ise.md +[04]: How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md +[05]: object-model/the-ise-object-model-hierarchy.md diff --git a/reference/docs-conceptual/windows-powershell/ise/Introducing-the-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/Introducing-the-Windows-PowerShell-ISE.md index a7da093393e0..78127aaeee03 100644 --- a/reference/docs-conceptual/windows-powershell/ise/Introducing-the-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/Introducing-the-Windows-PowerShell-ISE.md @@ -1,6 +1,6 @@ --- description: The PowerShell ISE is a host application for Windows PowerShell that allows you to run commands and write, test, and debug scripts in a single Windows-based graphic user interface. -ms.date: 10/07/2021 +ms.date: 03/27/2025 ms.topic: overview title: Introducing the Windows PowerShell ISE --- @@ -22,13 +22,12 @@ ISE is supported in all supported versions of Windows PowerShell up to and inclu PowerShell V5.1. > [!NOTE] -> The PowerShell ISE is no longer in active feature development. As a shipping component of -> Windows, it continues to be officially supported for security and high-priority servicing fixes. -> We currently have no plans to remove the ISE from Windows. +> The PowerShell ISE is no longer in active feature development. As a shipping component of Windows, +> it continues to be officially supported for security and high-priority servicing fixes. We +> currently have no plans to remove the ISE from Windows. > > There is no support for the ISE in PowerShell v6 and beyond. Users looking for replacement for the -> ISE should use [Visual Studio Code](https://code.visualstudio.com/) with the -> [PowerShell Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell). +> ISE should use [Visual Studio Code][01] with the [PowerShell Extension][02]. ## Key Features @@ -54,3 +53,7 @@ Alternately, you can type `powershell_ise.exe` in any command shell or in the Ru On the **Help** menu, click **Windows PowerShell Help**. Or, press F1. The file that opens describes Windows PowerShell ISE and Windows PowerShell, including all the help available from the `Get-Help` cmdlet. + + +[01]: https://code.visualstudio.com/ +[02]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell diff --git a/reference/docs-conceptual/windows-powershell/ise/Keyboard-Shortcuts-for-the-Windows-PowerShell-ISE.md b/reference/docs-conceptual/windows-powershell/ise/Keyboard-Shortcuts-for-the-Windows-PowerShell-ISE.md index 265e506fbb68..ddefa089623c 100644 --- a/reference/docs-conceptual/windows-powershell/ise/Keyboard-Shortcuts-for-the-Windows-PowerShell-ISE.md +++ b/reference/docs-conceptual/windows-powershell/ise/Keyboard-Shortcuts-for-the-Windows-PowerShell-ISE.md @@ -1,6 +1,6 @@ --- description: This article is a list of the keyboard shortcuts used in the PowerShell ISE. -ms.date: 03/04/2024 +ms.date: 03/27/2025 ms.topic: ui-reference title: Keyboard Shortcuts for the Windows PowerShell ISE --- diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/Other-Useful-Scripting-Objects.md b/reference/docs-conceptual/windows-powershell/ise/object-model/Other-Useful-Scripting-Objects.md index 55c669dce1a8..9a3b5730f8d4 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/Other-Useful-Scripting-Objects.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/Other-Useful-Scripting-Objects.md @@ -1,23 +1,23 @@ --- description: This article describes objects that provide additional scripting functionality in the Windows PowerShell ISE. -ms.date: 06/05/2017 +ms.date: 03/27/2025 title: Other Useful Scripting Objects --- # Other Useful Scripting Objects The following objects provide additional scripting functionality in Windows PowerShell ISE. They -are not part of the **$psISE** hierarchy. +aren't part of the `$psISE` hierarchy. ## Useful Scripting objects ### $psUnsupportedConsoleApplications There are some limitations on how Windows PowerShell ISE interacts with console applications. A -command or an automation script that requires user intervention might not work the way it works -from the Windows PowerShell console. You might want to block these commands or scripts from running -in the Windows PowerShell ISE Command pane. The **$psUnsupportedConsoleApplications** object keeps -a list of such commands. If you try to run the commands in this list, you get a message that they -are not supported. The following script adds an entry to the list. +command or an automation script that requires user intervention might not work the way it works from +the Windows PowerShell console. You might want to block these commands or scripts from running in +the Windows PowerShell ISE Command pane. The **$psUnsupportedConsoleApplications** object keeps a +list of such commands. If you try to run the commands in this list, you get a message that they +aren't supported. The following script adds an entry to the list. ```powershell # List the unsupported commands @@ -32,10 +32,10 @@ $psUnsupportedConsoleApplications ### $psLocalHelp -This is a dictionary object that maintains a context-sensitive mapping between Help topics and -their associated links in the local compiled HTML Help file. It is used to locate the local Help -for a particular topic. You can add or delete topics from this list. The following code example -shows some example key-value pairs that are contained in `$psLocalHelp`. +This is a dictionary object that maintains a context-sensitive mapping between Help topics and their +associated links in the local compiled HTML Help file. It's used to locate the local Help for a +particular topic. You can add or delete topics from this list. The following code example shows some +example key-value pairs that are contained in `$psLocalHelp`. ```powershell # See the local help map @@ -59,7 +59,7 @@ $psLocalHelp.Add("Get-MyNoun", "C:\MyFolder\MyHelpChm.chm::/html/0198854a-1298-5 ### $psOnlineHelp This is a dictionary object that maintains a context-sensitive mapping between topic titles of Help -topics and their associated external URLs. It is used to locate the Help for a particular topic on +topics and their associated external URLs. It's used to locate the Help for a particular topic on the web. You can add or delete topics from this list. ```powershell @@ -82,4 +82,7 @@ $psOnlineHelp.Add("Get-MyNoun", "https://www.mydomain.com/MyNoun.html") ## See Also -[Purpose of the Windows PowerShell ISE Scripting Object Model](./Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) +[Purpose of the Windows PowerShell ISE Scripting Object Model][01] + + +[01]: ./Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md b/reference/docs-conceptual/windows-powershell/ise/object-model/Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md index 3a2894583699..a430096b69a7 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md @@ -1,6 +1,6 @@ --- description: Purpose of the Windows PowerShell ISE Scripting Object Model -ms.date: 12/31/2019 +ms.date: 03/27/2025 title: Purpose of the Windows PowerShell ISE Scripting Object Model --- @@ -59,4 +59,7 @@ You can use the scripting object model to create keyboard shortcuts for frequent ## See also -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISE Object Model Hierarchy][01] + + +[01]: The-ISE-Object-Model-Hierarchy.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISE-Object-Model-Hierarchy.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISE-Object-Model-Hierarchy.md index c0d38a5e6ffe..5f9f16a92c46 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISE-Object-Model-Hierarchy.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISE-Object-Model-Hierarchy.md @@ -1,6 +1,6 @@ --- description: This article shows the hierarchy of objects that are part of Windows PowerShell ISE. -ms.date: 12/31/2019 +ms.date: 03/27/2025 title: The ISE Object Model Hierarchy --- @@ -12,44 +12,54 @@ an object to take you to the reference documentation for the class that defines ## $psISE Object -The `$psISE` object is the [root object](The-ObjectModelRoot-Object.md) of the Windows PowerShell +The `$psISE` object is the [root object][06] of the Windows PowerShell ISE object hierarchy. Located at the top level, it makes the following objects available for scripting: -## [$psISE.CurrentFile](The-ISEFile-Object.md) +## [$psISE.CurrentFile][04] -The `$psISE.CurrentFile` object is an instance of the [ISEFile](The-ISEFile-Object.md) class. +The `$psISE.CurrentFile` object is an instance of the [ISEFile][04] class. -## [$psISE.CurrentPowerShellTab](The-PowerShellTab-Object.md) +## [$psISE.CurrentPowerShellTab][07] -The `$psISE.CurrentPowerShellTab` object is an instance of the [PowerShellTab](The-PowerShellTab-Object.md) class. +The `$psISE.CurrentPowerShellTab` object is an instance of the [PowerShellTab][07] class. ## $psISE.CurrentVisibleHorizontalTool -The `$psISE.CurrentVisibleHorizontalTool` object is an instance of the [ISEAddOnTool](The-ISEAddOnTool-Object.md) -class. It represents the installed add-on tool that is currently docked to the top edge of the -Windows PowerShell ISE window. +The `$psISE.CurrentVisibleHorizontalTool` object is an instance of the [ISEAddOnTool][03] class. It +represents the installed add-on tool that's currently docked to the top edge of the Windows +PowerShell ISE window. ## $psISE.CurrentVisibleVerticalTool -The `$psISE.CurrentVisibleHorizontalTool` object is an instance of the [ISEAddOnTool](The-ISEAddOnTool-Object.md) -class. It represents the installed add-on tool that is currently docked to the right-hand edge of -the Windows PowerShell ISE window. +The `$psISE.CurrentVisibleHorizontalTool` object is an instance of the [ISEAddOnTool][03] class. It +represents the installed add-on tool that's currently docked to the right-hand edge of the Windows +PowerShell ISE window. -## [$psISE.Options](The-ISEOptions-Object.md) +## [$psISE.Options][05] -The `$psISE.Options` object is an instance of the [ISEOptions](The-ISEOptions-Object.md) class. The -ISEOptions object represents various settings for Windows PowerShell ISE. It is an instance of the +The `$psISE.Options` object is an instance of the [ISEOptions][05] class. The ISEOptions object +represents various settings for Windows PowerShell ISE. It's an instance of the Microsoft.PowerShell.Host.ISE.ISEOptions class. -## [$psISE.PowerShellTabs](The-PowerShellTabCollection-Object.md) +## [$psISE.PowerShellTabs][08] -The `$psISE.PowerShellTabs` object is an instance of the [PowerShellTabCollection](The-PowerShellTabCollection-Object.md) -class. It is a collection of all the currently open PowerShell tabs that represent the available -Windows PowerShell run environments on the local computer or on connected remote computers. Each -member in the collection is an instance of the [PowerShellTab](The-PowerShellTab-Object.md) class. +The `$psISE.PowerShellTabs` object is an instance of the [PowerShellTabCollection][08] class. It's a +collection of all the currently open PowerShell tabs that represent the available Windows PowerShell +run environments on the local computer or on connected remote computers. Each member in the +collection is an instance of the [PowerShellTab][07] class. ## See Also -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-ISEAddOnTool-Object.md +[04]: The-ISEFile-Object.md +[05]: The-ISEOptions-Object.md +[06]: The-ObjectModelRoot-Object.md +[07]: The-PowerShellTab-Object.md +[08]: The-PowerShellTabCollection-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnTool-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnTool-Object.md index bcc815541d90..6a3d1dac3513 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnTool-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnTool-Object.md @@ -1,6 +1,6 @@ --- description: An ISEAddonTool object represents an installed add-on tool that provides additional functionality to Windows PowerShell ISE. -ms.date: 06/05/2017 +ms.date: 03/27/2025 title: The ISEAddOnTool Object --- @@ -16,11 +16,10 @@ vertical pane is docked to the right edge of Windows PowerShell ISE. The horizon to the bottom edge. Each PowerShell tab in Windows PowerShell ISE can have its own set of add-on tools installed. See -[$psISE.CurrentPowerShellTab.HorizontalAddOnTools](The-PowerShellTab-Object.md) and -[$psISE.CurrentPowerShellTab.VerticalAddOnTools](The-PowerShellTab-Object.md) to access the -collection of tools available to the currently selected tab or the same properties on any of the -**PowerShellTab** objects in the [$psISE.PowerShellTabs](The-PowerShellTabCollection-Object.md) -collection object. +[$psISE.CurrentPowerShellTab.HorizontalAddOnTools][04] and +[$psISE.CurrentPowerShellTab.VerticalAddOnTools][04] to access the collection of tools available to +the currently selected tab or the same properties on any of the **PowerShellTab** objects in the +[$psISE.PowerShellTabs][05] collection object. ## Methods @@ -36,7 +35,7 @@ The **Control** property provides read access to many of the details of the Comm ```powershell # View the properties of the Commands add-on tool. -# (assumes that it is visible in the vertical pane) +# (assumes that it's visible in the vertical pane) $psISE.CurrentVisibleVerticalTool.Control ``` @@ -152,10 +151,10 @@ Dispatcher : System.Windows.Threading.Dispatcher Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. The Boolean property that indicates whether the add-on tool is currently visible in its assigned -pane. If it is visible, you can set the **IsVisible** property to `$false` to hide the tool, or set +pane. If it's visible, you can set the **IsVisible** property to `$false` to hide the tool, or set the **IsVisible** property to `$true` to make an add-on tool visible on its PowerShell tab. Note -that after an add-on tool is hidden, it is no longer accessible through the -**CurrentVisibleHorizontalTool** or **CurrentVisibleVerticalTool** objects, and therefore cannot be +that after an add-on tool is hidden, it's no longer accessible through the +**CurrentVisibleHorizontalTool** or **CurrentVisibleVerticalTool** objects, and therefore can't be made visible by using this property on that object. ```powershell @@ -182,6 +181,13 @@ Commands ## See Also -- [The ISEAddOnToolCollection Object](The-ISEAddOnToolCollection-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISEAddOnToolCollection Object][03] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-ISEAddOnToolCollection-Object.md +[04]: The-PowerShellTab-Object.md +[05]: The-PowerShellTabCollection-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnToolCollection-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnToolCollection-Object.md index e40da29044a3..cb3fda24ac6a 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnToolCollection-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEAddOnToolCollection-Object.md @@ -1,6 +1,6 @@ --- description: The ISEAddOnToolCollection object is a collection of **ISEAddOnTool** objects. -ms.date: 12/31/2019 +ms.date: 03/27/2025 title: The ISEAddOnToolCollection Object --- @@ -11,36 +11,33 @@ The **ISEAddOnToolCollection** object is a collection of **ISEAddOnTool** object ## Methods -### Add\( Name, ControlType, \[IsVisible\] \) +### `Add( Name, ControlType, [IsVisible] )` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Adds a new add-on tool to the collection. It returns the newly added add-on tool. Before you run this command, you must install the add-on tool on the local computer and load the assembly. -**Name** - String -Specifies the display name of the add-on tool that is added to Windows PowerShell ISE. - -**ControlType** -Type -Specifies the control that is added. - -**\[IsVisible\]** - optional Boolean -If set to `$true`, the add-on tool is immediately visible in the associated tool pane. +- **Name** - String - Specifies the display name of the add-on tool that's added to Windows PowerShell + ISE. +- **ControlType** - Type - Specifies the control that's added. +- **[IsVisible]** - optional Boolean - If set to `$true`, the add-on tool is immediately visible in + the associated tool pane. ```powershell # Load a DLL with an add-on and then add it to the ISE -[Reflection.Assembly]::LoadFile("C:\test\ISESimpleSolution\ISESimpleSolution.dll") +[Reflection.Assembly]::LoadFile("C:testISESimpleSolutionISESimpleSolution.dll") $psISE.CurrentPowerShellTab.VerticalAddOnTools.Add("Solutions", [ISESimpleSolution.Solution], $true) ``` -### Remove\( Item \) +### `Remove(Item)` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Removes the specified add-on tool from the collection. -**Item** - Microsoft.PowerShell.Host.ISE.ISEAddOnTool -Specifies the object to be removed from Windows PowerShell ISE. +- **Item** - Microsoft.PowerShell.Host.ISE.ISEAddOnTool - Specifies the object to be removed from + Windows PowerShell ISE. ```powershell # Load a DLL with an add-on and then add it to the ISE @@ -48,14 +45,13 @@ Specifies the object to be removed from Windows PowerShell ISE. $psISE.CurrentPowerShellTab.VerticalAddOnTools.Add("Solutions", [ISESimpleSolution.Solution], $true) ``` -### SetSelectedPowerShellTab\( psTab \) +### `SetSelectedPowerShellTab(psTab)` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Selects the PowerShell tab that the **psTab** parameter specifies. -**psTab** - Microsoft.PowerShell.Host.ISE.PowerShellTab -The PowerShell tab to select. +- **psTab** - Microsoft.PowerShell.Host.ISE.PowerShellTab -The PowerShell tab to select. ```powershell $newTab = $psISE.PowerShellTabs.Add() @@ -63,14 +59,13 @@ $newTab = $psISE.PowerShellTabs.Add() $newTab.DisplayName = 'Brand New Tab' ``` -### Remove\( psTab \) +### `Remove(psTab)` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Removes the PowerShell tab that the **psTab** parameter specifies. -**psTab** - Microsoft.PowerShell.Host.ISE.PowerShellTab -The PowerShell tab to remove. +- **psTab** - Microsoft.PowerShell.Host.ISE.PowerShellTab - The PowerShell tab to remove. ```powershell $newTab = $psISE.PowerShellTabs.Add() @@ -82,6 +77,11 @@ $psISE.PowerShellTabs.Remove($newTab) ## See Also -- [The PowerShellTab Object](The-PowerShellTab-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The PowerShellTab Object][03] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-PowerShellTab-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEEditor-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEEditor-Object.md index 89bfbd89ad3d..a28ae56736cc 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEEditor-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEEditor-Object.md @@ -1,19 +1,18 @@ --- description: An ISEEditor object is an instance of the Microsoft.PowerShell.Host.ISE.ISEEditor class. The Console pane is an ISEEditor object. -ms.date: 12/31/2019 +ms.date: 03/27/2025 title: The ISEEditor Object --- # The ISEEditor Object An **ISEEditor** object is an instance of the Microsoft.PowerShell.Host.ISE.ISEEditor class. The -Console pane is an **ISEEditor** object. Each [ISEFile](The-ISEFile-Object.md) object has an -associated **ISEEditor** object. The following sections list the methods and properties of an -**ISEEditor** object. +Console pane is an **ISEEditor** object. Each [ISEFile][04] object has an associated **ISEEditor** +object. The following sections list the methods and properties of an **ISEEditor** object. ## Methods -### Clear\(\) +### `Clear()` Supported in Windows PowerShell ISE 2.0 and later. @@ -24,7 +23,7 @@ Clears the text in the editor. $psISE.CurrentPowerShellTab.ConsolePane.Clear() ``` -### EnsureVisible\(int lineNumber\) +### `EnsureVisible(int lineNumber)` Supported in Windows PowerShell ISE 2.0 and later. @@ -32,15 +31,14 @@ Scrolls the editor so that the line that corresponds to the specified **lineNumb is visible. It throws an exception if the specified line number is outside the range of 1,last line number, which defines the valid line numbers. -**lineNumber** -The number of the line that is to be made visible. +- **lineNumber** - The number of the line that's to be made visible. ```powershell # Scrolls the text in the Script pane so that the fifth line is in view. $psISE.CurrentFile.Editor.EnsureVisible(5) ``` -### Focus\(\) +### `Focus()` Supported in Windows PowerShell ISE 2.0 and later. @@ -51,70 +49,59 @@ Sets the focus to the editor. $psISE.CurrentPowerShellTab.ConsolePane.Focus() ``` -### GetLineLength\(int lineNumber \) +### `GetLineLength(int lineNumber )` Supported in Windows PowerShell ISE 2.0 and later. -Gets the line length as an integer for the line that is specified by the line number. +Gets the line length as an integer for the line that's specified by the line number. -**lineNumber** -The number of the line of which to get the length. - -**Returns** -The line length for the line at the specified line number. +- **lineNumber** - The number of the line of which to get the length. +- **Returns** - The line length for the line at the specified line number. ```powershell # Gets the length of the first line in the text of the Command pane. $psISE.CurrentPowerShellTab.ConsolePane.GetLineLength(1) ``` -### GoToMatch\(\) +### GoToMatch() Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Moves the caret to the matching character if the **CanGoToMatch** property of the editor object is -`$true`, which occurs when the caret is immediately before an opening parenthesis, bracket, or -brace - `(`,`[`,`{` - or immediately after a closing parenthesis, bracket, or brace - `)`,`]`,`}`. The caret -is placed before an opening character or after a closing character. If the **CanGoToMatch** property -is `$false`, then this method does nothing. +`$true`, which occurs when the caret is immediately before an opening parenthesis, bracket, or brace +- `(`,`[`,`{` - or immediately after a closing parenthesis, bracket, or brace - `)`,`]`,`}`. The +caret is placed before an opening character or after a closing character. If the **CanGoToMatch** +property is `$false`, then this method does nothing. ```powershell # Goes to the matching character if CanGoToMatch() is $true $psISE.CurrentPowerShellTab.ConsolePane.GoToMatch() ``` -### InsertText\( text \) +### `InsertText( text )` Supported in Windows PowerShell ISE 2.0 and later. Replaces the selection with text or inserts text at the current caret position. -**text** - String -The text to insert. +- **text** - String - The text to insert. -See the [Scripting Example](#scripting-example) later in this topic. +See the [Scripting Example][01] later in this topic. -### Select\( startLine, startColumn, endLine, endColumn \) +### `Select( startLine, startColumn, endLine, endColumn )` Supported in Windows PowerShell ISE 2.0 and later. Selects the text from the **startLine**, **startColumn**, **endLine**, and **endColumn** parameters. -**startLine** - Integer -The line where the selection starts. - -**startColumn** - Integer -The column within the start line where the selection starts. - -**endLine** - Integer -The line where the selection ends. +- **startLine** - Integer - The line where the selection starts. +- **startColumn** - Integer - The column within the start line where the selection starts. +- **endLine** - Integer - The line where the selection ends. +- **endColumn** - Integer - The column within the end line where the selection ends. -**endColumn** - Integer -The column within the end line where the selection ends. +See the [Scripting Example][01] later in this topic. -See the [Scripting Example](#scripting-example) later in this topic. - -### SelectCaretLine\(\) +### `SelectCaretLine()` Supported in Windows PowerShell ISE 2.0 and later. @@ -127,25 +114,22 @@ $psISE.CurrentFile.Editor.SetCaretPosition(5,1) $psISE.CurrentFile.Editor.SelectCaretLine() ``` -### SetCaretPosition\( lineNumber, columnNumber \) +### `SetCaretPosition( lineNumber, columnNumber )` Supported in Windows PowerShell ISE 2.0 and later. Sets the caret position at the line number and the column number. It throws an exception if either the caret line number or the caret column number are out of their respective valid ranges. -**lineNumber** - Integer -The caret line number. - -**columnNumber** - Integer -The caret column number. +- **lineNumber** - Integer - The caret line number. +- **columnNumber** - Integer - The caret column number. ```powershell # Set the CaretPosition. $psISE.CurrentFile.Editor.SetCaretPosition(5,1) ``` -### ToggleOutliningExpansion\(\) +### `ToggleOutliningExpansion()` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. @@ -164,7 +148,7 @@ Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier ve The read-only Boolean property to indicate whether the caret is next to a parenthesis, bracket, or brace - `()`, `[]`, `{}`. If the caret is immediately before the opening character or immediately -after the closing character of a pair, then this property value is `$true`. Otherwise, it is +after the closing character of a pair, then this property value is `$true`. Otherwise, it's `$false`. ```powershell @@ -222,7 +206,7 @@ Supported in Windows PowerShell ISE 2.0 and later. The read-only property that gets the selected text from the editor. -See the [Scripting Example](#scripting-example) later in this topic. +See the [Scripting Example][01] later in this topic. ### Text @@ -230,7 +214,7 @@ Supported in Windows PowerShell ISE 2.0 and later. The read/write property that gets or sets the text in the editor. -See the [Scripting Example](#scripting-example) later in this topic. +See the [Scripting Example][01] later in this topic. ## Scripting Example @@ -263,7 +247,14 @@ $myEditor.InsertText($selection.ToLower()) ## See Also -- [The ISEFile Object](The-ISEFile-Object.md) -- [The PowerShellTab Object](The-PowerShellTab-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISEFile Object][04] +- [The PowerShellTab Object][05] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][02] +- [The ISE Object Model Hierarchy][03] + + +[01]: #scripting-example +[02]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[03]: The-ISE-Object-Model-Hierarchy.md +[04]: The-ISEFile-Object.md +[05]: The-PowerShellTab-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFile-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFile-Object.md index b601303d2b4e..d603f4855c2e 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFile-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFile-Object.md @@ -1,31 +1,30 @@ --- description: An ISEFile object represents a file in Windows PowerShell ISE. -ms.date: 12/31/2019 +ms.date: 03/27/2025 title: The ISEFile Object --- # The ISEFile Object An **ISEFile** object represents a file in Windows PowerShell Integrated Scripting Environment -(ISE). It is an instance of the **Microsoft.PowerShell.Host.ISE.ISEFile** class. This topic lists -its member methods and member properties. The `$psISE.CurrentFile` and the files in the Files -collection in a PowerShell tab are all instances of the ****Microsoft.PowerShell.Host.ISE.ISEFile** -class. +(ISE). It's an instance of the **Microsoft.PowerShell.Host.ISE.ISEFile** class. This topic lists its +member methods and member properties. The `$psISE.CurrentFile` and the files in the Files collection +in a PowerShell tab are all instances of the **Microsoft.PowerShell.Host.ISE.ISEFile** class. ## Methods -### Save\( \[saveEncoding\] \) +### Save( [saveEncoding] ) Supported in Windows PowerShell ISE 2.0 and later. Saves the file to disk. -`[saveEncoding]` - optional [System.Text.Encoding](/dotnet/api/system.text.encoding) An optional +`[saveEncoding]` - optional [System.Text.Encoding][01] An optional character encoding parameter to be used for the saved file. The default value is **UTF8**. ### Exceptions -- **System.IO.IOException**: The file could not be saved. +- **System.IO.IOException**: The file couldn't be saved. ```powershell # Save the file using the default encoding (UTF8) @@ -39,7 +38,7 @@ $myfile = $psISE.CurrentFile $myfile.Encoding ``` -### SaveAs\(filename, \[saveEncoding\]\) +### SaveAs(filename, [saveEncoding]) Supported in Windows PowerShell ISE 2.0 and later. @@ -48,14 +47,14 @@ Saves the file with the specified file name and encoding. **filename** - String The name to be used to save the file. -`[saveEncoding]` - optional [System.Text.Encoding](/dotnet/api/system.text.encoding) An optional +`[saveEncoding]` - optional [System.Text.Encoding][01] An optional character encoding parameter to be used for the saved file. The default value is **UTF8**. ### Exceptions - **System.ArgumentNullException**: The **filename** parameter is null. - **System.ArgumentException**: The **filename** parameter is empty. -- **System.IO.IOException**: The file could not be saved. +- **System.IO.IOException**: The file couldn't be saved. ```powershell # Save the file with a full path and name. @@ -72,8 +71,8 @@ $psISE.CurrentFile.SaveAs($fullPath, [System.Text.Encoding]::UTF8) Supported in Windows PowerShell ISE 2.0 and later. The read-only property that gets the string that contains the display name of this file. The name is -shown on the **File** tab at the top of the editor. The presence of an asterisk `(*)` at the end of -the name indicates that the file has changes that have not been saved. +shown on the **File** tab at the top of the editor. The presence of an asterisk (`*`) at the end of +the name indicates that the file has changes that haven't been saved. ```powershell # Shows the display name of the file. @@ -84,8 +83,7 @@ $psISE.CurrentFile.DisplayName Supported in Windows PowerShell ISE 2.0 and later. -The read-only property that gets the [editor object](The-ISEEditor-Object.md) that is used for the -specified file. +The read-only property that gets the [editor object][04] that's used for the specified file. ```powershell # Gets the editor and the text. @@ -143,6 +141,13 @@ $psISE.CurrentFile.IsUntitled ## See Also -- [The ISEFileCollectionObject](The-ISEFileCollection-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISEFileCollectionObject][05] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][02] +- [The ISE Object Model Hierarchy][03] + + +[01]: /dotnet/api/system.text.encoding +[02]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[03]: The-ISE-Object-Model-Hierarchy.md +[04]: The-ISEEditor-Object.md +[05]: The-ISEFileCollection-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFileCollection-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFileCollection-Object.md index 6bf1a10f1382..d4461b66f61f 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFileCollection-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEFileCollection-Object.md @@ -1,6 +1,6 @@ --- description: The ISEFileCollection object is a collection of ISEFile objects. -ms.date: 12/31/2019 +ms.date: 03/27/2025 title: The ISEFileCollection Object --- @@ -11,54 +11,56 @@ The **ISEFileCollection** object is a collection of **ISEFile** objects. An exam ## Methods -### Add\( \[FullPath\] \) +### `Add( [FullPath] )` Supported in Windows PowerShell ISE 2.0 and later. Creates and returns a new untitled file and adds it to the collection. The **IsUntitled** property of the newly created file is `$true`. -**\[FullPath\]** - Optional string The fully specified path of the file. An exception is generated -if you include the **FullPath** parameter and a relative path, or if you use a file name instead of -the full path. +- **[FullPath]** - Optional string - The fully specified path of the file. An exception is generated + if you include the **FullPath** parameter and a relative path, or if you use a file name instead + of the full path. ```powershell # Adds a new untitled file to the collection of files in the current PowerShell tab. $newFile = $psISE.CurrentPowerShellTab.Files.Add() -# Adds a file specified by its full path to the collection of files in the current PowerShell tab. +# Adds a file specified by its full path to the collection of files in the current +# PowerShell tab. $psISE.CurrentPowerShellTab.Files.Add("$PSHOME\Examples\profile.ps1") ``` -### Remove\( File, \[Force\] \) +### `Remove( File, [Force] )` Supported in Windows PowerShell ISE 2.0 and later. Removes a specified file from the current PowerShell tab. -**File** - String The ISEFile file that you want to remove from the collection. If the file has not +**File** - String The ISEFile file that you want to remove from the collection. If the file hasn't been saved, this method throws an exception. Use the **Force** switch parameter to force the removal of an unsaved file. -**\[Force\]** - optional Boolean If set to `$true`, grants permission to remove the file even if it -has not been saved after last use. The default is `$false`. +**[Force]** - optional Boolean If set to `$true`, grants permission to remove the file even if it +hasn't been saved after last use. The default is `$false`. ```powershell -# Removes the first opened file from the file collection associated with the current PowerShell tab. -# If the file has not yet been saved, then an exception is generated. +# Removes the first opened file from the file collection associated with the current +# PowerShell tab. If the file hasn't yet been saved, then an exception is generated. $firstfile = $psISE.CurrentPowerShellTab.Files[0] $psISE.CurrentPowerShellTab.Files.Remove($firstfile) -# Removes the first opened file from the file collection associated with the current PowerShell tab, even if it has not been saved. +# Removes the first opened file from the file collection associated with the current +# PowerShell tab, even if it hasn't been saved. $firstfile = $psISE.CurrentPowerShellTab.Files[0] $psISE.CurrentPowerShellTab.Files.Remove($firstfile, $true) ``` -### SetSelectedFile\( selectedFile \) +### `SetSelectedFile( selectedFile )` Supported in Windows PowerShell ISE 2.0 and later. -Selects the file that is specified by the **SelectedFile** parameter. +Selects the file that's specified by the **SelectedFile** parameter. **SelectedFile** - Microsoft.PowerShell.Host.ISE.ISEFile The ISEFile file that you want to select. @@ -71,6 +73,11 @@ $psISE.CurrentPowerShellTab.Files.SetSelectedFile($firstfile) ## See Also -- [The ISEFile Object](The-ISEFile-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISEFile Object][03] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-ISEFile-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItem-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItem-Object.md index 39c66e7ddea6..985de3e7d6cf 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItem-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItem-Object.md @@ -1,6 +1,6 @@ --- description: An ISEMenuItem object is an instance of the Microsoft.PowerShell.Host.ISE.ISEMenuItem class. All menu objects on the **Add-ons** menu are instances of the ISEMenuItem class. -ms.date: 10/05/2021 +ms.date: 03/27/2025 title: The ISEMenuItem Object --- @@ -59,7 +59,7 @@ $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus[0].Shortcut Supported in Windows PowerShell ISE 2.0 and later. -The read-only property that gets the [list of submenus](The-ISEMenuItemCollection-Object.md) of the +The read-only property that gets the [list of submenus][03] of the menu item. ```powershell @@ -80,8 +80,10 @@ following scripting example. $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.Clear() # Add an Add-ons menu item with a shortcut and fast access key. -# Note the use of "_" as opposed to the "&" for mapping to the fast access key letter for the menu item. -$menuAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add('_Process', {Get-Process}, 'Alt+P') +# Note the use of "_" as opposed to the "&" for mapping to the fast access key letter +# for the menu item. +$menuAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add('_Process', + {Get-Process}, 'Alt+P') # Add a nested menu - a parent and a child submenu item. $parentAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.Add('Parent', $null, $null) $parentAdded.SubMenus.Add('_Dir', {dir}, 'Alt+D') @@ -89,6 +91,11 @@ $parentAdded.SubMenus.Add('_Dir', {dir}, 'Alt+D') ## See Also -- [The ISEMenuItemCollection Object](The-ISEMenuItemCollection-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISEMenuItemCollection Object][03] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-ISEMenuItemCollection-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItemCollection-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItemCollection-Object.md index 16eed191652f..eafea3c5ad80 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItemCollection-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEMenuItemCollection-Object.md @@ -1,43 +1,39 @@ --- description: An ISEMenuItemCollection object is a collection of ISEMenuItem objects. -ms.date: 10/05/2021 +ms.date: 03/27/2025 title: The ISEMenuItemCollection Object --- # The ISEMenuItemCollection Object -An **ISEMenuItemCollection** object is a collection of **ISEMenuItem** objects. It is an instance of +An **ISEMenuItemCollection** object is a collection of **ISEMenuItem** objects. It's an instance of the **Microsoft.PowerShell.Host.ISE.ISEMenuItemCollection** class. An example is the -`$psISE.CurrentPowerShellTab.AddOnsMenu.Submenus` object that is used to customize the **Add-On** +`$psISE.CurrentPowerShellTab.AddOnsMenu.Submenus` object that's used to customize the **Add-On** menu in Windows PowerShell® Integrated Scripting Environment (ISE). ## Method -### Add\(string DisplayName, System.Management.Automation.ScriptBlock Action, System.Windows.Input.KeyGesture Shortcut \) +### `Add(DisplayName, Action, Shortcut )` Supported in Windows PowerShell ISE 2.0 and later. Adds a menu item to the collection. -**DisplayName** -The display name of the menu to be added. - -**Action** The **System.Management.Automation.ScriptBlock** object that specifies the action that is -associated with this menu item. - -**Shortcut** -The keyboard shortcut for the action. - -**Returns** -The **ISEMenuItem** object that was just added. +- **DisplayName** - String - The display name of the menu to be added. +- **Action** - System.Management.Automation.ScriptBlock - The object that specifies the action + that's associated with this menu item. +- **Shortcut** - System.Windows.Input.KeyGesture - The keyboard shortcut for the action. +- **Returns** - The **ISEMenuItem** object that was just added. ```powershell # Create an Add-ons menu with a fast access key and a shortcut. -# Note the use of "_" as opposed to the "&" for mapping to the fast access key letter for the menu item. -$menuAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.Add('_Process', {Get-Process}, 'Alt+P') +# Note the use of "_" as opposed to the "&" for mapping to the fast access key +# letter for the menu item. +$menuAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.Add('_Process', + {Get-Process}, 'Alt+P') ``` -### Clear\(\) +### `Clear()` Supported in Windows PowerShell ISE 2.0 and later. @@ -50,6 +46,11 @@ $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.Clear() ## See Also -- [The ISEMenuItem Object](The-ISEMenuItem-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISEMenuItem Object][03] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-ISEMenuItem-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEOptions-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEOptions-Object.md index 19c10ac2f790..53aeb534b6c7 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEOptions-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISEOptions-Object.md @@ -1,31 +1,32 @@ --- description: The ISEOptions object represents various settings for Windows PowerShell ISE. -ms.date: 12/31/2019 +ms.date: 03/27/2025 title: The ISEOptions Object --- # The ISEOptions Object -The **ISEOptions** object represents various settings for Windows PowerShell ISE. It is an instance +The **ISEOptions** object represents various settings for Windows PowerShell ISE. It's an instance of the **Microsoft.PowerShell.Host.ISE.ISEOptions** class. The **ISEOptions** object provides the following methods and properties. ## Methods -### RestoreDefaultConsoleTokenColors\(\) +### `RestoreDefaultConsoleTokenColors()` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Restores the default values of the token colors in the Console pane. ```powershell -# Changes the color of the commands in the Console pane to red and then restores it to its default value. +# Changes the color of the commands in the Console pane to red and then restores +# it to its default value. $psISE.Options.ConsoleTokenColors["Command"] = 'red' $psISE.Options.RestoreDefaultConsoleTokenColors() ``` -### RestoreDefaults\(\) +### `RestoreDefaults()` Supported in Windows PowerShell ISE 2.0 and later. @@ -39,27 +40,29 @@ $psISE.Options.ConsolePaneBackgroundColor = 'orange' $psISE.Options.RestoreDefaults() ``` -### RestoreDefaultTokenColors\(\) +### `RestoreDefaultTokenColors()` Supported in Windows PowerShell ISE 2.0 and later. Restores the default values of the token colors in the Script pane. ```powershell -# Changes the color of the comments in the Script pane to red and then restores it to its default value. +# Changes the color of the comments in the Script pane to red and then restores it +# to its default value. $psISE.Options.TokenColors["Comment"] = 'red' $psISE.Options.RestoreDefaultTokenColors() ``` -### RestoreDefaultXmlTokenColors\(\) +### `RestoreDefaultXmlTokenColors()` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Restores the default values of the token colors for XML elements that are displayed in Windows -PowerShell ISE. Also see [XmlTokenColors](#xmltokencolors). +PowerShell ISE. Also see [XmlTokenColors][09]. ```powershell -# Changes the color of the comments in XML data to red and then restores it to its default value. +# Changes the color of the comments in XML data to red and then restores it +# to its default value. $psISE.Options.XmlTokenColors["Comment"] = 'red' $psISE.Options.RestoreDefaultXmlTokenColors() ``` @@ -81,9 +84,9 @@ $psISE.Options.AutoSaveMinuteInterval = 3 ### CommandPaneBackgroundColor This feature is present in Windows PowerShell ISE 2.0, but was removed or renamed in later versions -of the ISE. For later versions, see [ConsolePaneBackgroundColor](#consolepanebackgroundcolor). +of the ISE. For later versions, see [ConsolePaneBackgroundColor][01]. -Specifies the background color for the Command pane. It is an instance of the +Specifies the background color for the Command pane. It's an instance of the **System.Windows.Media.Color** class. ```powershell @@ -107,7 +110,7 @@ $psISE.Options.CommandPaneUp = $true Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. -Specifies the background color for the Console pane. It is an instance of the +Specifies the background color for the Console pane. It's an instance of the **System.Windows.Media.Color** class. ```powershell @@ -143,11 +146,12 @@ Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier ve Specifies the colors of the IntelliSense tokens in the Windows PowerShell ISE Console pane. This property is a dictionary object that contains name/value pairs of token types and colors for the -Console pane. To change the colors of the IntelliSense tokens in the Script pane, see [TokenColors](#tokencolors). -To reset the colors to the default values, see [RestoreDefaultConsoleTokenColors](#restoredefaultconsoletokencolors). -Token colors can be set for the following: Attribute, Command, CommandArgument, CommandParameter, -Comment, GroupEnd, GroupStart, Keyword, LineContinuation, LoopLabel, Member, NewLine, Number, -Operator, Position, StatementSeparator, String, Type, Unknown, Variable. +Console pane. To change the colors of the IntelliSense tokens in the Script pane, see +[TokenColors][08]. To reset the colors to the default values, see +[RestoreDefaultConsoleTokenColors][05]. Token colors can be set for the following: Attribute, +Command, CommandArgument, CommandParameter, Comment, GroupEnd, GroupStart, Keyword, +LineContinuation, LoopLabel, Member, NewLine, Number, Operator, Position, StatementSeparator, +String, Type, Unknown, Variable. ```powershell # Sets the color of commands to green. @@ -160,11 +164,12 @@ $psISE.Options.ConsoleTokenColors["Keyword"] = 'magenta' Supported in Windows PowerShell ISE 2.0 and later. -Specifies the background color for the debug text that appears in the Console pane. It is an -instance of the **System.Windows.Media.Color** class. +Specifies the background color for the debug text that appears in the Console pane. It's an instance +of the **System.Windows.Media.Color** class. ```powershell -# Changes the background color for the debug text that appears in the Console pane to blue. +# Changes the background color for the debug text that appears in the Console pane +# to blue. $psISE.Options.DebugBackgroundColor = '#0000FF' ``` @@ -172,11 +177,12 @@ $psISE.Options.DebugBackgroundColor = '#0000FF' Supported in Windows PowerShell ISE 2.0 and later. -Specifies the foreground color for the debug text that appears in the Console pane. It is an -instance of the **System.Windows.Media.Color** class. +Specifies the foreground color for the debug text that appears in the Console pane. It's an instance +of the **System.Windows.Media.Color** class. ```powershell -# Changes the foreground color for the debug text that appears in the Console pane to yellow. +# Changes the foreground color for the debug text that appears in the Console +# pane to yellow. $psISE.Options.DebugForegroundColor = 'yellow' ``` @@ -184,7 +190,8 @@ $psISE.Options.DebugForegroundColor = 'yellow' Supported in Windows PowerShell ISE 2.0 and later. -A collection of properties that specify the default values to be used when the Reset methods are used. +A collection of properties that specify the default values to be used when the Reset methods are +used. ```powershell # Displays the name of the default options. This example is from ISE 4.0. @@ -233,7 +240,7 @@ IntellisenseTimeoutInSeconds : 3 Supported in Windows PowerShell ISE 2.0 and later. -Specifies the background color for error text that appears in the Console pane. It is an instance of +Specifies the background color for error text that appears in the Console pane. It's an instance of the **System.Windows.Media.Color** class. ```powershell @@ -245,7 +252,7 @@ $psISE.Options.ErrorBackgroundColor = 'black' Supported in Windows PowerShell ISE 2.0 and later. -Specifies the foreground color for error text that appears in the Console pane. It is an instance of +Specifies the foreground color for error text that appears in the Console pane. It's an instance of the **System.Windows.Media.Color** class. ```powershell @@ -268,7 +275,7 @@ $psISE.Options.FontName = 'Courier New' Supported in Windows PowerShell ISE 2.0 and later. -Specifies the font size as an integer. It is used in the Script pane, the Command pane, and the +Specifies the font size as an integer. It's used in the Script pane, the Command pane, and the Output pane. The valid range of values is 8 through 32. ```powershell @@ -297,16 +304,17 @@ Specifies the number of recently opened files that Windows PowerShell ISE tracks bottom of the **File Open** menu. The default value is 10. The value is an integer. ```powershell -# Changes the number of recently used files that appear at the bottom of the File Open menu to 5. +# Changes the number of recently used files that appear at the bottom of the +# File Open menu to 5. $psISE.Options.MruCount = 5 ``` ### OutputPaneBackgroundColor This feature is present in Windows PowerShell ISE 2.0, but was removed or renamed in later versions -of the ISE. For later versions, see [ConsolePaneBackgroundColor](#consolepanebackgroundcolor). +of the ISE. For later versions, see [ConsolePaneBackgroundColor][01]. -The read/write property that gets or sets the background color for the Output pane itself. It is an +The read/write property that gets or sets the background color for the Output pane itself. It's an instance of the **System.Windows.Media.Color** class. ```powershell @@ -317,7 +325,7 @@ $psISE.Options.OutputPaneForegroundColor = 'gold' ### OutputPaneTextForegroundColor This feature is present in Windows PowerShell ISE 2.0, but was removed or renamed in later versions -of the ISE. For later versions, see [ConsolePaneForegroundColor](#consolepaneforegroundcolor). +of the ISE. For later versions, see [ConsolePaneForegroundColor][02]. The read/write property that changes the foreground color of the text in the Output pane in Windows PowerShell ISE 2.0. @@ -330,7 +338,7 @@ $psISE.Options.OutputPaneTextForegroundColor = 'blue' ### OutputPaneTextBackgroundColor This feature is present in Windows PowerShell ISE 2.0, but was removed or renamed in later versions -of the ISE. For later versions, see [ConsolePaneTextBackgroundColor](#consolepanetextbackgroundcolor). +of the ISE. For later versions, see [ConsolePaneTextBackgroundColor][03]. The read/write property that changes the background color of the text in the Output pane. @@ -343,7 +351,7 @@ $psISE.Options.OutputPaneTextBackgroundColor = 'pink' Supported in Windows PowerShell ISE 2.0 and later. -The read/write property that gets or sets the background color for files. It is an instance of the +The read/write property that gets or sets the background color for files. It's an instance of the **System.Windows.Media.Color** class. ```powershell @@ -355,8 +363,8 @@ $psISE.Options.ScriptPaneBackgroundColor = 'yellow' Supported in Windows PowerShell ISE 2.0 and later. -The read/write property that gets or sets the foreground color for non-script files in the Script pane. -To set the foreground color for script files, use the [TokenColors](#tokencolors). +The read/write property that gets or sets the foreground color for non-script files in the Script +pane. To set the foreground color for script files, use the [TokenColors][08]. ```powershell # Sets the foreground to color of non-script files in the script pane to green. @@ -383,9 +391,9 @@ $psISE.Options.SelectedScriptPaneState = 'Maximized' Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. -Specifies whether the CTRL+J list of snippets includes the starter set that is included in -Windows PowerShell. When set to `$false`, only user-defined snippets appear in the CTRL+J list. -The default value is `$true`. +Specifies whether the CTRL+J list of snippets includes the starter set that's +included in Windows PowerShell. When set to `$false`, only user-defined snippets appear in the +CTRL+J list. The default value is `$true`. ```powershell # Hide the default snippets from the CTRL+J list. @@ -420,7 +428,8 @@ $psISE.Options.ShowIntellisenseInScriptPane = $false Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. -Specifies whether the Script pane displays line numbers in the left margin. The default value is `$true`. +Specifies whether the Script pane displays line numbers in the left margin. The default value is +`$true`. ```powershell # Turn off line numbers in the Script pane. @@ -432,9 +441,9 @@ $psISE.Options.ShowLineNumbers = $false Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Specifies whether the Script pane displays expandable and collapsible brackets next to sections of -code in the left margin. When they are displayed, you can click the minus `-` icons next to a -block of text to collapse it or click the plus `+` icon to expand a block of text. The default -value is `$true`. +code in the left margin. When they're displayed, you can click the minus `-` icons next to a block +of text to collapse it or click the plus `+` icon to expand a block of text. The default value is +`$true`. ```powershell # Turn off outlining in the Script pane. @@ -457,7 +466,7 @@ $psISE.Options.ShowToolBar = $true Supported in Windows PowerShell ISE 2.0 and later. -Specifies whether a warning message appears when a script is saved automatically before it is run. +Specifies whether a warning message appears when a script is saved automatically before it's run. The default value is `$true`. ```powershell @@ -487,11 +496,12 @@ Supported in Windows PowerShell ISE 2.0 and later. Specifies the colors of the IntelliSense tokens in the Windows PowerShell ISE Script pane. This property is a dictionary object that contains name/value pairs of token types and colors for the -Script pane. To change the colors of the IntelliSense tokens in the Console pane, see [ConsoleTokenColors](#consoletokencolors). -To reset the colors to the default values, see [RestoreDefaultTokenColors](#restoredefaulttokencolors). -Token colors can be set for the following: Attribute, Command, CommandArgument, CommandParameter, -Comment, GroupEnd, GroupStart, Keyword, LineContinuation, LoopLabel, Member, NewLine, Number, -Operator, Position, StatementSeparator, String, Type, Unknown, Variable. +Script pane. To change the colors of the IntelliSense tokens in the Console pane, see +[ConsoleTokenColors][04]. To reset the colors to the default values, see +[RestoreDefaultTokenColors][06]. Token colors can be set for the following: Attribute, Command, +CommandArgument, CommandParameter, Comment, GroupEnd, GroupStart, Keyword, LineContinuation, +LoopLabel, Member, NewLine, Number, Operator, Position, StatementSeparator, String, Type, Unknown, +Variable. ```powershell # Sets the color of commands to green. @@ -544,7 +554,7 @@ $psISE.Options.UseLocalHelp = $true Supported in Windows PowerShell ISE 2.0 and later. -Specifies the background color for verbose text that appears in the Console pane. It is a +Specifies the background color for verbose text that appears in the Console pane. It's a **System.Windows.Media.Color** object. ```powershell @@ -556,7 +566,7 @@ $psISE.Options.VerboseBackgroundColor ='#0000FF' Supported in Windows PowerShell ISE 2.0 and later. -Specifies the foreground color for verbose text that appears in the Console pane. It is a +Specifies the foreground color for verbose text that appears in the Console pane. It's a **System.Windows.Media.Color** object. ```powershell @@ -568,7 +578,7 @@ $psISE.Options.VerboseForegroundColor = 'yellow' Supported in Windows PowerShell ISE 2.0 and later. -Specifies the background color for warning text that appears in the Console pane. It is a +Specifies the background color for warning text that appears in the Console pane. It's a **System.Windows.Media.Color** object. ```powershell @@ -580,7 +590,7 @@ $psISE.Options.WarningBackgroundColor = '#0000FF' Supported in Windows PowerShell ISE 2.0 and later. -Specifies the foreground color for warning text that appears in the Output pane. It is a +Specifies the foreground color for warning text that appears in the Output pane. It's a **System.Windows.Media.Color** object. ```powershell @@ -593,10 +603,10 @@ $psISE.Options.WarningForegroundColor = 'yellow' Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Specifies a dictionary object that contains name/value pairs of token types and colors for XML -content that is displayed in Windows PowerShell ISE. Token colors can be set for the following: +content that's displayed in Windows PowerShell ISE. Token colors can be set for the following: Attribute, Command, CommandArgument, CommandParameter, Comment, GroupEnd, GroupStart, Keyword, LineContinuation, LoopLabel, Member, NewLine, Number, Operator, Position, StatementSeparator, -String, Type, Unknown, Variable. Also see [RestoreDefaultXmlTokenColors](#restoredefaultxmltokencolors). +String, Type, Unknown, Variable. Also see [RestoreDefaultXmlTokenColors][07]. ```powershell # Sets the color of XML element names to green. @@ -620,5 +630,18 @@ $psISE.Options.Zoom = 200 ## See Also -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [Purpose of the Windows PowerShell ISE Scripting Object Model][10] +- [The ISE Object Model Hierarchy][11] + + +[01]: #consolepanebackgroundcolor +[02]: #consolepaneforegroundcolor +[03]: #consolepanetextbackgroundcolor +[04]: #consoletokencolors +[05]: #restoredefaultconsoletokencolors +[06]: #restoredefaulttokencolors +[07]: #restoredefaultxmltokencolors +[08]: #tokencolors +[09]: #xmltokencolors +[10]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[11]: The-ISE-Object-Model-Hierarchy.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetCollection-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetCollection-Object.md index b9441da9ab4b..83e1fe21841f 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetCollection-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetCollection-Object.md @@ -1,35 +1,45 @@ --- -description: The ISESnippetCollection object is a collection of ISESnippet objects. The files collection that is associated with a PowerShellTab object is a member of this class. -ms.date: 12/31/2019 +description: The ISESnippetCollection object is a collection of ISESnippet objects. The files collection that's associated with a PowerShellTab object is a member of this class. +ms.date: 03/27/2025 title: The ISESnippetCollection Object --- # The ISESnippetCollection Object The **ISESnippetCollection** object is a collection of **ISESnippet** objects. The files collection -that is associated with a **PowerShellTab** object is a member of this class. An example is the +that's associated with a **PowerShellTab** object is a member of this class. An example is the `$psISE.CurrentPowerShellTab.Files` collection. ## Methods -### Load\( FilePathName \) +### `Load( FilePathName )` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Loads a `snippets.ps1xml` file that contains user-defined snippets. The easiest way to create -snippets is to use the `New-IseSnippet` cmdlet, which automatically stores them in your profile folder -so that they are loaded every time that you start Windows PowerShell ISE. +snippets is to use the `New-IseSnippet` cmdlet, which automatically stores them in your profile +folder so that they're loaded every time that you start Windows PowerShell ISE. -**FilePathName** - String -The path and file name to a `snippets.ps1xml` file that contains snippet definitions. +- **FilePathName** - String - The path and file name to a `snippets.ps1xml` file that contains + snippet definitions. ```powershell # Loads a custom snippet file into the current PowerShell tab. -$SnipFile = Join-Path ( Split-Path $PROFILE) 'Snippets\MySnips.snippets.ps1xml' $psISE.CurrentPowerShellTab.Snippets.Add($SnipPath) +$joinPathSplat = @{ + Path = ( Split-Path $PROFILE) + ChildPath = 'Snippets\MySnips.snippets.ps1xml' + AdditionalChildPath = $psISE.CurrentPowerShellTab.Snippets.Add($SnipPath) +} +$SnipFile = Join-Path @joinPathSplat ``` ## See Also -- [The ISESnippetObject](The-ISESnippetObject.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISESnippetObject][03] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-ISESnippetObject.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetObject.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetObject.md index fdaf28848a7e..426f34f249b1 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetObject.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ISESnippetObject.md @@ -1,6 +1,6 @@ --- description: An ISESnippet object is an instance of the Microsoft.PowerShell.Host.ISE.ISESnippet class. -ms.date: 06/05/2017 +ms.date: 03/27/2025 title: The ISESnippetObject --- @@ -8,8 +8,7 @@ title: The ISESnippetObject An **ISESnippet** object is an instance of the Microsoft.PowerShell.Host.ISE.ISESnippet class. The members of the `$psISE.CurrentPowerShellTab.Snippets` collection are all examples of **ISESnippet** -objects. The easiest way to create a snippet is to use the -[New-IseSnippet](/powershell/module/ISE/New-IseSnippet) cmdlet. +objects. The easiest way to create a snippet is to use the [New-IseSnippet][01] cmdlet. ## Properties @@ -50,6 +49,12 @@ $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus[0].Shortcut ## See Also -- [The ISESnippetCollection Object](The-ISESnippetCollection-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](purpose-of-the-windows-powershell-ise-scripting-object-model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The ISESnippetCollection Object][04] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][02] +- [The ISE Object Model Hierarchy][03] + + +[01]: /powershell/module/ISE/New-IseSnippet +[02]: purpose-of-the-windows-powershell-ise-scripting-object-model.md +[03]: The-ISE-Object-Model-Hierarchy.md +[04]: The-ISESnippetCollection-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ObjectModelRoot-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ObjectModelRoot-Object.md index 4423672f3c6b..4989998d4bdc 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-ObjectModelRoot-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-ObjectModelRoot-Object.md @@ -1,12 +1,12 @@ --- description: The $psISE object, which is the principal root object in PowerShell ISE is an instance of the Microsoft.PowerShell.Host.ISE.ObjectModelRoot class. This topic describes the properties of the ObjectModelRoot object. -ms.date: 08/25/2017 +ms.date: 03/27/2025 title: The ObjectModelRoot Object --- # The ObjectModelRoot Object -The `$psISE` object, which is the principal root object in Windows PowerShell® Integrated Scripting +The `$psISE` object, which is the principal root object in Windows PowerShell Integrated Scripting Environment (ISE) is an instance of the Microsoft.PowerShell.Host.ISE.ObjectModelRoot class. This topic describes the properties of the **ObjectModelRoot** object. @@ -29,15 +29,14 @@ The read-only property that gets the PowerShell tab that has the focus. > Supported in Windows PowerShell ISE 2.0 and later. -The read-only property that gets the currently visible -Windows PowerShell ISE add-on tool that is located in -the horizontal tool pane at the bottom of the editor. +The read-only property that gets the currently visible Windows PowerShell ISE add-on tool that's +located in the horizontal tool pane at the bottom of the editor. ### CurrentVisibleVerticalTool > Supported in Windows PowerShell ISE 2.0 and later. -The read-only property that gets the currently visible Windows PowerShell ISE add-on tool that is +The read-only property that gets the currently visible Windows PowerShell ISE add-on tool that's located in the vertical tool pane on the right side of the editor. ### Options @@ -57,5 +56,9 @@ PowerShell tabs to this object by using scripts or by using the menus in Windows ## See Also -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTab-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTab-Object.md index 5a86a62af581..18bd4fc26c5e 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTab-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTab-Object.md @@ -1,6 +1,6 @@ --- description: The PowerShellTab object represents a Windows PowerShell runtime environment. -ms.date: 06/05/2017 +ms.date: 03/27/2025 title: The PowerShellTab Object --- @@ -10,19 +10,18 @@ The **PowerShellTab** object represents a Windows PowerShell runtime environment ## Methods -### Invoke\( Script \) +### `Invoke( Script )` Supported in Windows PowerShell ISE 2.0 and later. Runs the given script in the PowerShell tab. > [!NOTE] -> This method only works on other PowerShell tabs, not the PowerShell tab from which it is run. It -> does not return any object or value. If the code modifies any variable, then those changes persist +> This method only works on other PowerShell tabs, not the PowerShell tab from which it's run. It +> doesn't return any object or value. If the code modifies any variable, then those changes persist > on the tab against which the command was invoked. -**Script** - System.Management.Automation.ScriptBlock or String -The script block to run. +- **Script** - System.Management.Automation.ScriptBlock or String - The script block to run. ```powershell # Manually create a second PowerShell tab before running this script. @@ -30,29 +29,26 @@ The script block to run. $psISE.PowerShellTabs[1].Invoke({dir}) ``` -### InvokeSynchronous\( Script, \[useNewScope\], millisecondsTimeout \) +### `InvokeSynchronous( Script, [useNewScope], millisecondsTimeout )` Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. Runs the given script in the PowerShell tab. > [!NOTE] -> This method only works on other PowerShell tabs, not the PowerShell tab from which it is run. The -> script block is run and any value that is returned from the script is returned to the run +> This method only works on other PowerShell tabs, not the PowerShell tab from which it's run. The +> script block is run and any value that's returned from the script is returned to the run > environment from which you invoked the command. If the command takes longer to run than the > **millesecondsTimeout** value specifies, then the command fails with an exception: "The operation > has timed out." -**Script** - System.Management.Automation.ScriptBlock or String -The script block to run. - -**\[useNewScope\]** - Optional Boolean that defaults to `$true` -If set to `$true`, then a new scope is created within which to run the command. It does not modify -the runtime environment of the PowerShell tab that is specified by the command. - -**\[millisecondsTimeout\]** - Optional integer that defaults to **500**. -If the command does not finish within the specified time, then the command generates a -**TimeoutException** with the message "The operation has timed out." +- **Script** - System.Management.Automation.ScriptBlock or String - The script block to run. +- **[useNewScope]** - Optional Boolean that defaults to `$true` - If set to `$true`, then a new + scope is created within which to run the command. It doesn't modify the runtime environment of the + PowerShell tab that's specified by the command. +- **[millisecondsTimeout]** - Optional integer that defaults to **500**. - If the command doesn't + finish within the specified time, then the command generates a **TimeoutException** with the + message "The operation has timed out." ```powershell # Create a new PowerShell tab and then switch back to the first @@ -86,7 +82,8 @@ The read-only property that gets the Add-ons menu for the PowerShell tab. $psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Clear() # Create an AddOns menu with an accessor. # Note the use of "_" as opposed to the "&" for mapping to the fast key letter for the menu item. -$menuAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add('_Process', {Get-Process}, 'Alt+P') +$menuAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add('_Process', + {Get-Process}, 'Alt+P') # Add a nested menu. $parentAdded = $psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add('Parent', $null, $null) $parentAdded.SubMenus.Add('_Dir', {dir}, 'Alt+D') @@ -98,13 +95,13 @@ $psISE.CurrentPowerShellTab.AddOnsMenu Supported in Windows PowerShell ISE 2.0 and later. -The read-only Boolean property that returns a `$true` value if a script can be invoked with the [Invoke( Script )](#invoke-script-) -method. +The read-only Boolean property that returns a `$true` value if a script can be invoked with the +[Invoke( Script )][01] method. ```powershell # CanInvoke will be false if the PowerShell # tab is running a script that takes a while, and you -# check its properties from another PowerShell tab. It is +# check its properties from another PowerShell tab. It's # always false if checked on the current PowerShell tab. # Manually create a second PowerShell tab before running this script. # Return to the first tab and type @@ -119,7 +116,7 @@ $secondTab.CanInvoke Supported in Windows PowerShell ISE 3.0 and later, and not present in earlier versions. In Windows PowerShell ISE 2.0 this was named **CommandPane**. -The read-only property that gets the Console pane [editor](The-ISEEditor-Object.md) object. +The read-only property that gets the Console pane [editor][04] object. ```powershell # Gets the Console Pane editor. @@ -130,7 +127,7 @@ $psISE.CurrentPowerShellTab.ConsolePane Supported in Windows PowerShell ISE 2.0 and later. -The read-write property that gets or sets the text that is displayed on the PowerShell tab. By +The read-write property that gets or sets the text that's displayed on the PowerShell tab. By default, tabs are named "PowerShell #", where the # represents a number. ```powershell @@ -154,8 +151,8 @@ $psISE.CurrentPowerShellTab.ExpandedScript = !$psISE.CurrentPowerShellTab.Expand Supported in Windows PowerShell ISE 2.0 and later. -The read-only property that gets the [collection of script files](The-ISEFileCollection-Object.md) -that are open in the PowerShell tab. +The read-only property that gets the [collection of script files][05] that are open in the +PowerShell tab. ```powershell $newFile = $psISE.CurrentPowerShellTab.Files.Add() @@ -170,7 +167,7 @@ This feature is present in Windows PowerShell ISE 2.0, but was removed or rename of the ISE. In later versions of Windows PowerShell ISE, you can use the **ConsolePane** object for the same purposes. -The read-only property that gets the Output pane of the current [editor](The-ISEEditor-Object.md). +The read-only property that gets the Output pane of the current [editor][04]. ```powershell # Clears the text in the Output pane. @@ -181,8 +178,8 @@ $psISE.CurrentPowerShellTab.Output.Clear() Supported in Windows PowerShell ISE 2.0 and later. -The read-only property that gets the current prompt text. Note: the **prompt** function can be -overridden by the user'™s profile. If the result is other than a simple string, then this property +The read-only property that gets the current prompt text. Note: the `prompt` function can be +overridden by the user's profile. If the result is other than a simple string, then this property returns nothing. ```powershell @@ -240,6 +237,14 @@ $psISE.CurrentPowerShellTab.HorizontalAddOnToolsPaneOpened ## See Also -- [The PowerShellTabCollection Object](The-PowerShellTabCollection-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The PowerShellTabCollection Object][06] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][02] +- [The ISE Object Model Hierarchy][03] + + +[01]: #invoke-script- +[02]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[03]: The-ISE-Object-Model-Hierarchy.md +[04]: The-ISEEditor-Object.md +[05]: The-ISEFileCollection-Object.md +[06]: The-PowerShellTabCollection-Object.md diff --git a/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTabCollection-Object.md b/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTabCollection-Object.md index c1f55c291427..51be20ba5caa 100644 --- a/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTabCollection-Object.md +++ b/reference/docs-conceptual/windows-powershell/ise/object-model/The-PowerShellTabCollection-Object.md @@ -1,18 +1,18 @@ --- description: The PowerShellTab collection object is a collection of PowerShellTab objects. Each PowerShellTab object functions as a separate runtime environment. -ms.date: 06/05/2017 +ms.date: 03/27/2025 title: The PowerShellTabCollection Object --- # The PowerShellTabCollection Object The **PowerShellTab** collection object is a collection of **PowerShellTab** objects. Each -**PowerShellTab** object functions as a separate runtime environment. It is an instance of +**PowerShellTab** object functions as a separate runtime environment. It's an instance of Microsoft.PowerShell.Host.ISE.PowerShellTabs class. An example is the `$psISE.PowerShellTabs` object. ## Methods -### Add\(\) +### `Add()` Supported in Windows PowerShell ISE 2.0 and later. @@ -23,14 +23,13 @@ $newTab = $psISE.PowerShellTabs.Add() $newTab.DisplayName = 'Brand New Tab' ``` -### Remove\(Microsoft.PowerShell.Host.ISE.PowerShellTab psTab\) +### `Remove(Microsoft.PowerShell.Host.ISE.PowerShellTab psTab)` Supported in Windows PowerShell ISE 2.0 and later. -Removes the tab that is specified by the **psTab** parameter. +Removes the tab that's specified by the **psTab** parameter. -**psTab** -The PowerShell tab to remove. +- **psTab** - The PowerShell tab to remove. ```powershell $newTab = $psISE.PowerShellTabs.Add() @@ -40,15 +39,14 @@ sleep 5 $psISE.PowerShellTabs.Remove($newTab) ``` -### SetSelectedPowerShellTab\(Microsoft.PowerShell.Host.ISE.PowerShellTab psTab\) +### `SetSelectedPowerShellTab(Microsoft.PowerShell.Host.ISE.PowerShellTab psTab)` Supported in Windows PowerShell ISE 2.0 and later. -Selects the PowerShell tab that is specified by the **psTab** parameter to make it the currently +Selects the PowerShell tab that's specified by the **psTab** parameter to make it the currently active PowerShell tab. -**psTab** -The PowerShell tab to select. +- **psTab** - The PowerShell tab to select. ```powershell # Save the current tab in a variable and rename it @@ -63,6 +61,11 @@ $psISE.PowerShellTabs.SelectedPowerShellTab = $oldTab ## See Also -- [The PowerShellTab Object](The-PowerShellTab-Object.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](The-ISE-Object-Model-Hierarchy.md) +- [The PowerShellTab Object][03] +- [Purpose of the Windows PowerShell ISE Scripting Object Model][01] +- [The ISE Object Model Hierarchy][02] + + +[01]: Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md +[02]: The-ISE-Object-Model-Hierarchy.md +[03]: The-PowerShellTab-Object.md diff --git a/reference/docs-conceptual/windows-powershell/wmf-overview.md b/reference/docs-conceptual/windows-powershell/wmf-overview.md index 4e866776c7bb..dbbdb7a40963 100644 --- a/reference/docs-conceptual/windows-powershell/wmf-overview.md +++ b/reference/docs-conceptual/windows-powershell/wmf-overview.md @@ -1,6 +1,6 @@ --- -description: WMF is a prerequisite for Windows PowerShell. This articles shows the history of WMF versions and provides information about how to find and install WMF. -ms.date: 11/03/2023 +description: WMF is a prerequisite for Windows PowerShell. This article shows the history of WMF versions and provides information about how to find and install WMF. +ms.date: 03/27/2025 ms.topic: overview title: Windows Management Framework (WMF) --- @@ -29,8 +29,8 @@ WMF installation adds and/or updates the following features: ## WMF Release Notes -To learn about various enhancements in PowerShell and other components of a given WMF, please refer -to the links below to review the release notes: +To learn about the enhancements in Windows PowerShell and other components, see the release notes +for each version of WMF: - [WMF 5.1][08] - [WMF 5.0][07] @@ -57,8 +57,8 @@ to the links below to review the release notes: - **Included**: The features of the specified version of WMF were shipped in the indicated version of Windows client or Windows Server. -- **Out of support**: These products are no longer supported by Microsoft. You must upgrade to a - supported version. For more information, see the [Microsoft Lifecycle Policy][06] page. +- **Out of support**: Microsoft no longer supports these products. You must upgrade to a supported + version. For more information, see the [Microsoft Lifecycle Policy][06] page. > [!NOTE] > The version of WMF that shipped in an operating system is supported for the lifetime of support diff --git a/xx.ps1 b/xx.ps1 new file mode 100644 index 000000000000..5f282702bb03 --- /dev/null +++ b/xx.ps1 @@ -0,0 +1 @@ + \ No newline at end of file