From b97c590ac28f95fcb349f142e056cdc311df1c1b Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 25 Oct 2023 10:02:29 -0500 Subject: [PATCH] (MAINT) Cleanup `Set-Alias` This change updates the `Set-Alias` reference documentation, cleaning up syntax, grammar, and example code. --- .../Microsoft.PowerShell.Utility/Set-Alias.md | 88 +++++++++++-------- .../Microsoft.PowerShell.Utility/Set-Alias.md | 88 +++++++++++-------- .../Microsoft.PowerShell.Utility/Set-Alias.md | 88 +++++++++++-------- .../Microsoft.PowerShell.Utility/Set-Alias.md | 86 +++++++++++------- 4 files changed, 211 insertions(+), 139 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Set-Alias.md b/reference/5.1/Microsoft.PowerShell.Utility/Set-Alias.md index 0f687c6f986c..1650adb1747a 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Set-Alias.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Set-Alias.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 10/25/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-alias?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Alias @@ -25,14 +25,15 @@ Set-Alias [-Name] [-Value] [-Description ] [-Option Set-Alias -Name loc -Value Get-Location -Option ReadOnly -PassThru | Format-List -Property * +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly Description : Name : loc CommandType : Alias +``` -PS> Set-Alias -Name loc -Value Get-Location -Option ReadOnly -Description 'Displays the current directory' -Force -PassThru | Format-List -Property * +```powershell +$Parameters = @{ + Name = 'loc' + Value = (Get-Location) + Option = 'ReadOnly' + Description = 'Displays the current directory' + Force = $true + PassThru = $true +} +Set-Alias @Parameters | Format-List -Property * +``` +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly @@ -117,12 +133,12 @@ The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The * specifies the alias's name, `loc`. The **Value** parameter specifies the `Get-Location` cmdlet that the alias runs. The **Option** parameter specifies the **ReadOnly** value. The **PassThru** parameter represents the alias object and sends the object down the pipeline to the `Format-List` -cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that all of the -properties are displayed. The example output shows a partial list of those properties. +cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that every property +is displayed. The example output shows a partial list of those properties. The `loc` alias is changed with the addition of two parameters. **Description** adds text to explain the alias's purpose. The **Force** parameter is needed because the `loc` alias is read-only. If the -**Force** parameter is not used, the change fails. +**Force** parameter isn't used, the change fails. ### Example 4: Create an alias to an executable file @@ -140,19 +156,20 @@ Alias np -> notepad.exe The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The **Name** parameter specifies the alias's name, `np`. The **Value** parameter specifies the path and application name -**C:\Windows\notepad.exe**. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` -alias is associated with **notepad.exe**. +`C:\Windows\notepad.exe`. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` +alias is associated with `notepad.exe`. -To run the alias, type `np` on the PowerShell command line to open **notepad.exe**. +To run the alias, type `np` on the PowerShell command line to open `notepad.exe`. ### Example 5: Create an alias for a command with parameters This example shows how to assign an alias to a command with parameters. -You can create an alias for a cmdlet, such as `Set-Location`. You cannot create an alias for a +You can create an alias for a cmdlet, such as `Set-Location`. You can't create an alias for a command with parameters and values, such as `Set-Location -Path C:\Windows\System32`. To create an alias for a command, create a function that includes the command, and then create an alias to the -function. For more information, see [about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). +function. For more information, see +[about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). ``` Function CD32 {Set-Location -Path C:\Windows\System32} @@ -174,21 +191,21 @@ the directory `C:\Windows\System32`. This example shows how to assign multiple options using the **Option** parameter. -Using the example above we will set the alias `Go` as `ReadOnly` and `Private`. +Continuing from the previous example, set the alias `Go` as `ReadOnly` and `Private`. ```powershell Set-Alias -Name Go -Option ReadOnly, Private ``` -The alias `Go` should already exist. After running the command above, the alias is not be able to -be changed without using the **Force** parameter and is only available in the current scope. +The alias `Go` should already exist. After running the command, the alias can't be changed without +using the **Force** parameter and is only available in the current scope. ## PARAMETERS ### -Description Specifies a description of the alias. You can type any string. If the description includes spaces, -enclose it single quotation marks. +enclose it in single quotation marks. ```yaml Type: System.String @@ -207,7 +224,7 @@ Accept wildcard characters: False Use the **Force** parameter to change or delete an alias that has the **Option** parameter set to **ReadOnly**. -The **Force** parameter cannot change or delete an alias with the **Option** parameter set to +The **Force** parameter can't change or delete an alias with the **Option** parameter set to **Constant**. ```yaml @@ -224,8 +241,8 @@ Accept wildcard characters: False ### -Name -Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. Alias names -cannot be numeric, such as 123. +Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. +Alias names can't be numeric, such as 123. ```yaml Type: System.String @@ -248,15 +265,15 @@ session, type `Get-Alias | Format-Table -Property Name, Options -Autosize`. The acceptable values for this parameter are as follows: - `AllScope` - The alias is copied to any new scopes that are created. -- `Constant` - Cannot be changed or deleted. +- `Constant` - Can't be changed or deleted. - `None` - Sets no options and is the default. - `Private` - The alias is available only in the current scope. -- `ReadOnly` - Cannot be changed or deleted unless the **Force** parameter is used. +- `ReadOnly` - Can't be changed or deleted unless the **Force** parameter is used. - `Unspecified` These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the **Option** parameter as an -array of values or as a comma-separated string of those values. The cmdlet will combine the values +array of values or as a comma-separated string of those values. The cmdlet combines the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values. @@ -276,7 +293,7 @@ Accept wildcard characters: False ### -PassThru Returns an object that represents the alias. Use a format cmdlet such as `Format-List` to display -the object. By default, `Set-Alias` does not generate any output. +the object. By default, `Set-Alias` doesn't generate any output. ```yaml Type: System.Management.Automation.SwitchParameter @@ -292,16 +309,16 @@ Accept wildcard characters: False ### -Scope -Specifies the scope in which this alias is valid. The default value is **Local**. For more -information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). +Specifies the scope this alias is valid in. The default value is **Local**. For more information, +see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). The acceptable values are as follows: -- Global -- Local -- Private -- Numbered scopes -- Script +- `Global` +- `Local` +- `Private` +- `Numbered scopes` +- `Script` ```yaml Type: System.String @@ -351,7 +368,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -369,7 +386,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -400,7 +418,7 @@ cmdlet displays the aliases available in a PowerShell session. To create a new alias, use `Set-Alias` or `New-Alias`. To remove an alias use the `Remove-Item` cmdlet. For example, `Remove-Item -Path Alias:aliasname`. -To create an alias that is available in each PowerShell session, add it to your PowerShell profile. +To create an alias that's available in each PowerShell session, add it to your PowerShell profile. For more information, see [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). An alias can be saved and reused in another PowerShell session by doing an export and import. To diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Set-Alias.md b/reference/7.2/Microsoft.PowerShell.Utility/Set-Alias.md index 554f68abf274..eba6674e28d4 100644 --- a/reference/7.2/Microsoft.PowerShell.Utility/Set-Alias.md +++ b/reference/7.2/Microsoft.PowerShell.Utility/Set-Alias.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 10/25/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-alias?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Alias @@ -25,14 +25,15 @@ Set-Alias [-Name] [-Value] [-Description ] [-Option Set-Alias -Name loc -Value Get-Location -Option ReadOnly -PassThru | Format-List -Property * +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly Description : Name : loc CommandType : Alias +``` -PS> Set-Alias -Name loc -Value Get-Location -Option ReadOnly -Description 'Displays the current directory' -Force -PassThru | Format-List -Property * +```powershell +$Parameters = @{ + Name = 'loc' + Value = (Get-Location) + Option = 'ReadOnly' + Description = 'Displays the current directory' + Force = $true + PassThru = $true +} +Set-Alias @Parameters | Format-List -Property * +``` +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly @@ -117,12 +133,12 @@ The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The * specifies the alias's name, `loc`. The **Value** parameter specifies the `Get-Location` cmdlet that the alias runs. The **Option** parameter specifies the **ReadOnly** value. The **PassThru** parameter represents the alias object and sends the object down the pipeline to the `Format-List` -cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that all of the -properties are displayed. The example output shows a partial list of those properties. +cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that every property +is displayed. The example output shows a partial list of those properties. The `loc` alias is changed with the addition of two parameters. **Description** adds text to explain the alias's purpose. The **Force** parameter is needed because the `loc` alias is read-only. If the -**Force** parameter is not used, the change fails. +**Force** parameter isn't used, the change fails. ### Example 4: Create an alias to an executable file @@ -140,19 +156,20 @@ Alias np -> notepad.exe The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The **Name** parameter specifies the alias's name, `np`. The **Value** parameter specifies the path and application name -**C:\Windows\notepad.exe**. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` -alias is associated with **notepad.exe**. +`C:\Windows\notepad.exe`. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` +alias is associated with `notepad.exe`. -To run the alias, type `np` on the PowerShell command line to open **notepad.exe**. +To run the alias, type `np` on the PowerShell command line to open `notepad.exe`. ### Example 5: Create an alias for a command with parameters This example shows how to assign an alias to a command with parameters. -You can create an alias for a cmdlet, such as `Set-Location`. You cannot create an alias for a +You can create an alias for a cmdlet, such as `Set-Location`. You can't create an alias for a command with parameters and values, such as `Set-Location -Path C:\Windows\System32`. To create an alias for a command, create a function that includes the command, and then create an alias to the -function. For more information, see [about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). +function. For more information, see +[about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). ``` Function CD32 {Set-Location -Path C:\Windows\System32} @@ -174,21 +191,21 @@ the directory `C:\Windows\System32`. This example shows how to assign multiple options using the **Option** parameter. -Using the example above we will set the alias `Go` as `ReadOnly` and `Private`. +Continuing from the previous example, set the alias `Go` as `ReadOnly` and `Private`. ```powershell Set-Alias -Name Go -Option ReadOnly, Private ``` -The alias `Go` should already exist. After running the command above, the alias is not be able to -be changed without using the **Force** parameter and is only available in the current scope. +The alias `Go` should already exist. After running the command, the alias can't be changed without +using the **Force** parameter and is only available in the current scope. ## PARAMETERS ### -Description Specifies a description of the alias. You can type any string. If the description includes spaces, -enclose it single quotation marks. +enclose it in single quotation marks. ```yaml Type: System.String @@ -207,7 +224,7 @@ Accept wildcard characters: False Use the **Force** parameter to change or delete an alias that has the **Option** parameter set to **ReadOnly**. -The **Force** parameter cannot change or delete an alias with the **Option** parameter set to +The **Force** parameter can't change or delete an alias with the **Option** parameter set to **Constant**. ```yaml @@ -224,8 +241,8 @@ Accept wildcard characters: False ### -Name -Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. Alias names -cannot be numeric, such as 123. +Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. +Alias names can't be numeric, such as 123. ```yaml Type: System.String @@ -248,15 +265,15 @@ session, type `Get-Alias | Format-Table -Property Name, Options -Autosize`. The acceptable values for this parameter are as follows: - `AllScope` - The alias is copied to any new scopes that are created. -- `Constant` - Cannot be changed or deleted. +- `Constant` - Can't be changed or deleted. - `None` - Sets no options and is the default. - `Private` - The alias is available only in the current scope. -- `ReadOnly` - Cannot be changed or deleted unless the **Force** parameter is used. +- `ReadOnly` - Can't be changed or deleted unless the **Force** parameter is used. - `Unspecified` These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the **Option** parameter as an -array of values or as a comma-separated string of those values. The cmdlet will combine the values +array of values or as a comma-separated string of those values. The cmdlet combines the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values. @@ -276,7 +293,7 @@ Accept wildcard characters: False ### -PassThru Returns an object that represents the alias. Use a format cmdlet such as `Format-List` to display -the object. By default, `Set-Alias` does not generate any output. +the object. By default, `Set-Alias` doesn't generate any output. ```yaml Type: System.Management.Automation.SwitchParameter @@ -292,16 +309,16 @@ Accept wildcard characters: False ### -Scope -Specifies the scope in which this alias is valid. The default value is **Local**. For more -information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). +Specifies the scope this alias is valid in. The default value is **Local**. For more information, +see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). The acceptable values are as follows: -- Global -- Local -- Private -- Numbered scopes -- Script +- `Global` +- `Local` +- `Private` +- `Numbered scopes` +- `Script` ```yaml Type: System.String @@ -351,7 +368,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -369,7 +386,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -403,7 +421,7 @@ use the `Remove-Alias` cmdlet. `Remove-Item` is accepted for backwards compatibi scripts created with prior versions of PowerShell. Use a command such as `Remove-Item -Path Alias:aliasname`. -To create an alias that is available in each PowerShell session, add it to your PowerShell profile. +To create an alias that's available in each PowerShell session, add it to your PowerShell profile. For more information, see [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). An alias can be saved and reused in another PowerShell session by doing an export and import. To diff --git a/reference/7.3/Microsoft.PowerShell.Utility/Set-Alias.md b/reference/7.3/Microsoft.PowerShell.Utility/Set-Alias.md index 4280096271a4..e1fdc05075d8 100644 --- a/reference/7.3/Microsoft.PowerShell.Utility/Set-Alias.md +++ b/reference/7.3/Microsoft.PowerShell.Utility/Set-Alias.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 10/25/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-alias?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Alias @@ -25,14 +25,15 @@ Set-Alias [-Name] [-Value] [-Description ] [-Option Set-Alias -Name loc -Value Get-Location -Option ReadOnly -PassThru | Format-List -Property * +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly Description : Name : loc CommandType : Alias +``` -PS> Set-Alias -Name loc -Value Get-Location -Option ReadOnly -Description 'Displays the current directory' -Force -PassThru | Format-List -Property * +```powershell +$Parameters = @{ + Name = 'loc' + Value = (Get-Location) + Option = 'ReadOnly' + Description = 'Displays the current directory' + Force = $true + PassThru = $true +} +Set-Alias @Parameters | Format-List -Property * +``` +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly @@ -117,12 +133,12 @@ The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The * specifies the alias's name, `loc`. The **Value** parameter specifies the `Get-Location` cmdlet that the alias runs. The **Option** parameter specifies the **ReadOnly** value. The **PassThru** parameter represents the alias object and sends the object down the pipeline to the `Format-List` -cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that all of the -properties are displayed. The example output shows a partial list of those properties. +cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that every property +is displayed. The example output shows a partial list of those properties. The `loc` alias is changed with the addition of two parameters. **Description** adds text to explain the alias's purpose. The **Force** parameter is needed because the `loc` alias is read-only. If the -**Force** parameter is not used, the change fails. +**Force** parameter isn't used, the change fails. ### Example 4: Create an alias to an executable file @@ -140,19 +156,20 @@ Alias np -> notepad.exe The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The **Name** parameter specifies the alias's name, `np`. The **Value** parameter specifies the path and application name -**C:\Windows\notepad.exe**. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` -alias is associated with **notepad.exe**. +`C:\Windows\notepad.exe`. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` +alias is associated with `notepad.exe`. -To run the alias, type `np` on the PowerShell command line to open **notepad.exe**. +To run the alias, type `np` on the PowerShell command line to open `notepad.exe`. ### Example 5: Create an alias for a command with parameters This example shows how to assign an alias to a command with parameters. -You can create an alias for a cmdlet, such as `Set-Location`. You cannot create an alias for a +You can create an alias for a cmdlet, such as `Set-Location`. You can't create an alias for a command with parameters and values, such as `Set-Location -Path C:\Windows\System32`. To create an alias for a command, create a function that includes the command, and then create an alias to the -function. For more information, see [about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). +function. For more information, see +[about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). ``` Function CD32 {Set-Location -Path C:\Windows\System32} @@ -174,21 +191,21 @@ the directory `C:\Windows\System32`. This example shows how to assign multiple options using the **Option** parameter. -Using the example above we will set the alias `Go` as `ReadOnly` and `Private`. +Continuing from the previous example, set the alias `Go` as `ReadOnly` and `Private`. ```powershell Set-Alias -Name Go -Option ReadOnly, Private ``` -The alias `Go` should already exist. After running the command above, the alias is not be able to -be changed without using the **Force** parameter and is only available in the current scope. +The alias `Go` should already exist. After running the command, the alias can't be changed without +using the **Force** parameter and is only available in the current scope. ## PARAMETERS ### -Description Specifies a description of the alias. You can type any string. If the description includes spaces, -enclose it single quotation marks. +enclose it in single quotation marks. ```yaml Type: System.String @@ -207,7 +224,7 @@ Accept wildcard characters: False Use the **Force** parameter to change or delete an alias that has the **Option** parameter set to **ReadOnly**. -The **Force** parameter cannot change or delete an alias with the **Option** parameter set to +The **Force** parameter can't change or delete an alias with the **Option** parameter set to **Constant**. ```yaml @@ -224,8 +241,8 @@ Accept wildcard characters: False ### -Name -Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. Alias names -cannot be numeric, such as 123. +Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. +Alias names can't be numeric, such as 123. ```yaml Type: System.String @@ -248,15 +265,15 @@ session, type `Get-Alias | Format-Table -Property Name, Options -Autosize`. The acceptable values for this parameter are as follows: - `AllScope` - The alias is copied to any new scopes that are created. -- `Constant` - Cannot be changed or deleted. +- `Constant` - Can't be changed or deleted. - `None` - Sets no options and is the default. - `Private` - The alias is available only in the current scope. -- `ReadOnly` - Cannot be changed or deleted unless the **Force** parameter is used. +- `ReadOnly` - Can't be changed or deleted unless the **Force** parameter is used. - `Unspecified` These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the **Option** parameter as an -array of values or as a comma-separated string of those values. The cmdlet will combine the values +array of values or as a comma-separated string of those values. The cmdlet combines the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values. @@ -276,7 +293,7 @@ Accept wildcard characters: False ### -PassThru Returns an object that represents the alias. Use a format cmdlet such as `Format-List` to display -the object. By default, `Set-Alias` does not generate any output. +the object. By default, `Set-Alias` doesn't generate any output. ```yaml Type: System.Management.Automation.SwitchParameter @@ -292,16 +309,16 @@ Accept wildcard characters: False ### -Scope -Specifies the scope in which this alias is valid. The default value is **Local**. For more -information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). +Specifies the scope this alias is valid in. The default value is **Local**. For more information, +see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). The acceptable values are as follows: -- Global -- Local -- Private -- Numbered scopes -- Script +- `Global` +- `Local` +- `Private` +- `Numbered scopes` +- `Script` ```yaml Type: System.String @@ -351,7 +368,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -369,7 +386,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -403,7 +421,7 @@ use the `Remove-Alias` cmdlet. `Remove-Item` is accepted for backwards compatibi scripts created with prior versions of PowerShell. Use a command such as `Remove-Item -Path Alias:aliasname`. -To create an alias that is available in each PowerShell session, add it to your PowerShell profile. +To create an alias that's available in each PowerShell session, add it to your PowerShell profile. For more information, see [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). An alias can be saved and reused in another PowerShell session by doing an export and import. To diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Set-Alias.md b/reference/7.4/Microsoft.PowerShell.Utility/Set-Alias.md index 5869c8b167b0..8f2e695a984f 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Set-Alias.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Set-Alias.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 10/25/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-alias?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Alias @@ -25,14 +25,15 @@ Set-Alias [-Name] [-Value] [-Description ] [-Option Set-Alias -Name loc -Value Get-Location -Option ReadOnly -PassThru | Format-List -Property * +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly Description : Name : loc CommandType : Alias +``` -PS> Set-Alias -Name loc -Value Get-Location -Option ReadOnly -Description 'Displays the current directory' -Force -PassThru | Format-List -Property * +```powershell +$Parameters = @{ + Name = 'loc' + Value = (Get-Location) + Option = 'ReadOnly' + Description = 'Displays the current directory' + Force = $true + PassThru = $true +} +Set-Alias @Parameters | Format-List -Property * +``` +```Output DisplayName : loc -> Get-Location Definition : Get-Location Options : ReadOnly @@ -117,12 +133,12 @@ The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The * specifies the alias's name, `loc`. The **Value** parameter specifies the `Get-Location` cmdlet that the alias runs. The **Option** parameter specifies the **ReadOnly** value. The **PassThru** parameter represents the alias object and sends the object down the pipeline to the `Format-List` -cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that all of the -properties are displayed. The example output shows a partial list of those properties. +cmdlet. `Format-List` uses the **Property** parameter with an asterisk (`*`) so that every property +is displayed. The example output shows a partial list of those properties. The `loc` alias is changed with the addition of two parameters. **Description** adds text to explain the alias's purpose. The **Force** parameter is needed because the `loc` alias is read-only. If the -**Force** parameter is not used, the change fails. +**Force** parameter isn't used, the change fails. ### Example 4: Create an alias to an executable file @@ -140,19 +156,20 @@ Alias np -> notepad.exe The `Set-Alias` cmdlet creates an alias in the current PowerShell session. The **Name** parameter specifies the alias's name, `np`. The **Value** parameter specifies the path and application name -**C:\Windows\notepad.exe**. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` -alias is associated with **notepad.exe**. +`C:\Windows\notepad.exe`. The `Get-Alias` cmdlet uses the **Name** parameter to show that the `np` +alias is associated with `notepad.exe`. -To run the alias, type `np` on the PowerShell command line to open **notepad.exe**. +To run the alias, type `np` on the PowerShell command line to open `notepad.exe`. ### Example 5: Create an alias for a command with parameters This example shows how to assign an alias to a command with parameters. -You can create an alias for a cmdlet, such as `Set-Location`. You cannot create an alias for a +You can create an alias for a cmdlet, such as `Set-Location`. You can't create an alias for a command with parameters and values, such as `Set-Location -Path C:\Windows\System32`. To create an alias for a command, create a function that includes the command, and then create an alias to the -function. For more information, see [about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). +function. For more information, see +[about_Functions](../Microsoft.PowerShell.Core/about/about_Functions.md). ``` Function CD32 {Set-Location -Path C:\Windows\System32} @@ -174,14 +191,14 @@ the directory `C:\Windows\System32`. This example shows how to assign multiple options using the **Option** parameter. -Using the example above we will set the alias `Go` as `ReadOnly` and `Private`. +Continuing from the previous example, set the alias `Go` as `ReadOnly` and `Private`. ```powershell Set-Alias -Name Go -Option ReadOnly, Private ``` -The alias `Go` should already exist. After running the command above, the alias is not be able to -be changed without using the **Force** parameter and is only available in the current scope. +The alias `Go` should already exist. After running the command, the alias can't be changed without +using the **Force** parameter and is only available in the current scope. ## PARAMETERS @@ -207,7 +224,7 @@ Accept wildcard characters: False Use the **Force** parameter to change or delete an alias that has the **Option** parameter set to **ReadOnly**. -The **Force** parameter cannot change or delete an alias with the **Option** parameter set to +The **Force** parameter can't change or delete an alias with the **Option** parameter set to **Constant**. ```yaml @@ -224,8 +241,8 @@ Accept wildcard characters: False ### -Name -Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. Alias names -cannot be numeric, such as 123. +Specifies the name of a new alias. An alias name can contain alphanumeric characters and hyphens. +Alias names can't be numeric, such as 123. ```yaml Type: System.String @@ -248,15 +265,15 @@ session, type `Get-Alias | Format-Table -Property Name, Options -Autosize`. The acceptable values for this parameter are as follows: - `AllScope` - The alias is copied to any new scopes that are created. -- `Constant` - Cannot be changed or deleted. +- `Constant` - Can't be changed or deleted. - `None` - Sets no options and is the default. - `Private` - The alias is available only in the current scope. -- `ReadOnly` - Cannot be changed or deleted unless the **Force** parameter is used. +- `ReadOnly` - Can't be changed or deleted unless the **Force** parameter is used. - `Unspecified` These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the **Option** parameter as an -array of values or as a comma-separated string of those values. The cmdlet will combine the values +array of values or as a comma-separated string of those values. The cmdlet combines the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values. @@ -276,7 +293,7 @@ Accept wildcard characters: False ### -PassThru Returns an object that represents the alias. Use a format cmdlet such as `Format-List` to display -the object. By default, `Set-Alias` does not generate any output. +the object. By default, `Set-Alias` doesn't generate any output. ```yaml Type: System.Management.Automation.SwitchParameter @@ -292,16 +309,16 @@ Accept wildcard characters: False ### -Scope -Specifies the scope in which this alias is valid. The default value is **Local**. For more -information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). +Specifies the scope this alias is valid in. The default value is **Local**. For more information, +see [about_Scopes](../Microsoft.PowerShell.Core/About/about_Scopes.md). The acceptable values are as follows: -- Global -- Local -- Private -- Numbered scopes -- Script +- `Global` +- `Local` +- `Private` +- `Numbered scopes` +- `Script` ```yaml Type: System.String @@ -351,7 +368,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -369,7 +386,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -403,7 +421,7 @@ use the `Remove-Alias` cmdlet. `Remove-Item` is accepted for backwards compatibi scripts created with prior versions of PowerShell. Use a command such as `Remove-Item -Path Alias:aliasname`. -To create an alias that is available in each PowerShell session, add it to your PowerShell profile. +To create an alias that's available in each PowerShell session, add it to your PowerShell profile. For more information, see [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). An alias can be saved and reused in another PowerShell session by doing an export and import. To