Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

02/14 PM Publishing #10879

Merged
merged 2 commits into from
Feb 14, 2024
Merged

02/14 PM Publishing #10879

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a61046
Update README for 7.5 (#10874)
sdwheeler Feb 14, 2024
4303089
Update $OutputEncoding (#10877)
jborean93 Feb 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
ms.date: 04/05/2023
ms.date: 02/13/2024
---
# PowerShell Documentation

Expand Down Expand Up @@ -39,6 +39,7 @@ The following list describes the main folders in this repository.
- `7.2` - contains the cmdlet reference and about topics for PowerShell 7.2
- `7.3` - contains the cmdlet reference and about topics for PowerShell 7.3
- `7.4` - contains the cmdlet reference and about topics for PowerShell 7.4
- `7.5` - contains the cmdlet reference and about topics for PowerShell 7.5
- `bread` - contains the TOC used for breadcrumb navigation
- `docs-conceptual` - contains the conceptual articles that are published to the Docs site. In
general, the folder structure mirrors the Table of Contents (TOC).
Expand Down
60 changes: 33 additions & 27 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -978,12 +978,12 @@ Remove-Variable OFS

## $OutputEncoding

Determines the character encoding method that PowerShell uses when it sends
text to other applications.
Determines the character encoding method that PowerShell uses when piping data
into native applications.

For example, if an application returns Unicode strings to PowerShell, you might
need to change the value to **UnicodeEncoding** to send the characters
correctly.
> [!NOTE]
> In the majority of scenarios, the value for `$OutputEncoding` should align
> to the value of `[Console]::InputEncoding`.

The valid values are as follows: Objects derived from an Encoding class, such
as [**ASCIIEncoding**][60],
Expand All @@ -996,51 +996,57 @@ as [**ASCIIEncoding**][60],

### Examples

This example shows how to make the Windows `findstr.exe` command work in
PowerShell on a computer that's localized for a language that uses Unicode
characters, such as Chinese.

The first command finds the value of `$OutputEncoding`. Because the value is an
encoding object, display only its **EncodingName** property.

```powershell
$OutputEncoding.EncodingName
```

In this example, a `findstr.exe` command is used to search for two Chinese
characters that are present in the `Test.txt` file. When this `findstr.exe`
command is run in the Windows Command Prompt (`cmd.exe`), `findstr.exe` finds
the characters in the text file. However, when you run the same `findstr.exe`
command in PowerShell, the characters aren't found because the PowerShell sends
them to `findstr.exe` in ASCII text, instead of in Unicode text.
The remaining examples use the following PowerShell script saved as
`hexdump.ps1` to illustrate the behavior of `$OutputEncoding`.

```powershell
findstr <Unicode-characters>
$inputStream = [Console]::OpenStandardInput()
try {
$buffer = [byte[]]::new(1024)
$read = $inputStream.Read($buffer, 0, $buffer.Length)
$actual = [byte[]]::new($read)
[Array]::Copy($buffer, $actual, $read)
Format-Hex -InputObject $actual
} finally {
$inputStream.Dispose()
}
```

To make the command work in PowerShell, set the value of `$OutputEncoding` to
the value of the **OutputEncoding** property of the console, that's based on
the locale selected for Windows. Because **OutputEncoding** is a static
property of the console, use double-colons (`::`) in the command.
The following example shows how the string value `café` is encoded to bytes
when piped into `hexdump.ps1` created above. It demonstrates that the string
value is encoded using the `windows-1252` encoding scheme which is the default
encoding on the system tested in question.

```powershell
$OutputEncoding = [console]::OutputEncoding
$OutputEncoding.EncodingName
'café' | powershell.exe -File .\hexdump.ps1
```

```Output
OEM United States
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

00000000 63 61 66 3F 0D 0A caf?..
```

After the encoding change, the `findstr.exe` command finds the Unicode
characters.
The following example shows how the bytes change when changing the encoding
to UTF-8. The `é` instead of being encoded to `0x3F` as done by `windows-1252`
it will now become `0xC3 0xA9` due to the UTF-8 encoding being used.

```powershell
findstr <Unicode-characters>
$OutputEncoding = [System.Text.UTF8Encoding]::new()
'café' | powershell.exe -File .\hexdump.ps1
```

```Output
test.txt: <Unicode-characters>
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

00000000 63 61 66 C3 A9 0D 0A café..
```

## $ProgressPreference
Expand Down
62 changes: 35 additions & 27 deletions reference/7.2/Microsoft.PowerShell.Core/About/about_Preference_Variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -866,12 +866,12 @@ Remove-Variable OFS

## $OutputEncoding

Determines the character encoding method that PowerShell uses when it sends
text to other applications.
Determines the character encoding method that PowerShell uses when piping data
into native applications.

For example, if an application returns Unicode strings to PowerShell, you might
need to change the value to **UnicodeEncoding** to send the characters
correctly.
> [!NOTE]
> In the majority of scenarios, the value for `$OutputEncoding` should align
> to the value of `[Console]::InputEncoding`.

The valid values are as follows: Objects derived from an Encoding class, such
as [**ASCIIEncoding**][59], [**UTF7Encoding**][62], [**UTF8Encoding**][63],
Expand All @@ -881,51 +881,59 @@ as [**ASCIIEncoding**][59], [**UTF7Encoding**][62], [**UTF8Encoding**][63],

### Examples

This example shows how to make the Windows `findstr.exe` command work in
PowerShell on a computer that's localized for a language that uses Unicode
characters, such as Chinese.

The first command finds the value of `$OutputEncoding`. Because the value is an
encoding object, display only its **EncodingName** property.

```powershell
$OutputEncoding.EncodingName
```

In this example, a `findstr.exe` command is used to search for two Chinese
characters that are present in the `Test.txt` file. When this `findstr.exe`
command is run in the Windows Command Prompt (`cmd.exe`), `findstr.exe` finds
the characters in the text file. However, when you run the same `findstr.exe`
command in PowerShell, the characters aren't found because the PowerShell sends
them to `findstr.exe` in ASCII text, instead of in Unicode text.
The remaining examples use the following PowerShell script saved as
`hexdump.ps1` to illustrate the behavior of `$OutputEncoding`.

```powershell
findstr <Unicode-characters>
$inputStream = [Console]::OpenStandardInput()
try {
$buffer = [byte[]]::new(1024)
$read = $inputStream.Read($buffer, 0, $buffer.Length)
Format-Hex -InputObject $buffer -Count $read
} finally {
$inputStream.Dispose()
}
```

To make the command work in PowerShell, set the value of `$OutputEncoding` to
the value of the **OutputEncoding** property of the console, that's based on
the locale selected for Windows. Because **OutputEncoding** is a static
property of the console, use double-colons (`::`) in the command.
The following example shows how the string value `café` is encoded to bytes
when piped into `hexdump.ps1` created above. It demonstrates that the string
value is encoded using the [**UTF8Encoding**][63] scheme.

```powershell
$OutputEncoding = [console]::OutputEncoding
$OutputEncoding.EncodingName
'café' | pwsh -File ./hexdump.ps1
```

```Output
OEM United States
Label: Byte[] (System.Byte[]) <28873E25>

Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 63 61 66 C3 A9 0D 0A caf�
```

After the encoding change, the `findstr.exe` command finds the Unicode
characters.
The following example shows how the bytes change when changing the encoding
to [**UnicodeEncoding**][60].

```powershell
findstr <Unicode-characters>
$OutputEncoding = [System.Text.Encoding]::Unicode
'café' | pwsh -File ./hexdump.ps1
```

```Output
test.txt: <Unicode-characters>
Label: Byte[] (System.Byte[]) <515A7DC3>

Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 FF FE 63 00 61 00 66 00 E9 00 0D 00 0A 00 ÿþc a f é � �
```

## $ProgressPreference
Expand Down
62 changes: 35 additions & 27 deletions reference/7.3/Microsoft.PowerShell.Core/About/about_Preference_Variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -872,12 +872,12 @@ Remove-Variable OFS

## $OutputEncoding

Determines the character encoding method that PowerShell uses when it sends
text to other applications.
Determines the character encoding method that PowerShell uses when piping data
into native applications.

For example, if an application returns Unicode strings to PowerShell, you might
need to change the value to **UnicodeEncoding** to send the characters
correctly.
> [!NOTE]
> In the majority of scenarios, the value for `$OutputEncoding` should align
> to the value of `[Console]::InputEncoding`.

The valid values are as follows: Objects derived from an Encoding class, such
as [**ASCIIEncoding**][62], [**UTF7Encoding**][65], [**UTF8Encoding**][66],
Expand All @@ -887,51 +887,59 @@ as [**ASCIIEncoding**][62], [**UTF7Encoding**][65], [**UTF8Encoding**][66],

### Examples

This example shows how to make the Windows `findstr.exe` command work in
PowerShell on a computer that's localized for a language that uses Unicode
characters, such as Chinese.

The first command finds the value of `$OutputEncoding`. Because the value is an
encoding object, display only its **EncodingName** property.

```powershell
$OutputEncoding.EncodingName
```

In this example, a `findstr.exe` command is used to search for two Chinese
characters that are present in the `Test.txt` file. When this `findstr.exe`
command is run in the Windows Command Prompt (`cmd.exe`), `findstr.exe` finds
the characters in the text file. However, when you run the same `findstr.exe`
command in PowerShell, the characters aren't found because the PowerShell sends
them to `findstr.exe` in ASCII text, instead of in Unicode text.
The remaining examples use the following PowerShell script saved as
`hexdump.ps1` to illustrate the behavior of `$OutputEncoding`.

```powershell
findstr <Unicode-characters>
$inputStream = [Console]::OpenStandardInput()
try {
$buffer = [byte[]]::new(1024)
$read = $inputStream.Read($buffer, 0, $buffer.Length)
Format-Hex -InputObject $buffer -Count $read
} finally {
$inputStream.Dispose()
}
```

To make the command work in PowerShell, set the value of `$OutputEncoding` to
the value of the **OutputEncoding** property of the console, that's based on
the locale selected for Windows. Because **OutputEncoding** is a static
property of the console, use double-colons (`::`) in the command.
The following example shows how the string value `café` is encoded to bytes
when piped into `hexdump.ps1` created above. It demonstrates that the string
value is encoded using the [**UTF8Encoding**][63] scheme.

```powershell
$OutputEncoding = [console]::OutputEncoding
$OutputEncoding.EncodingName
'café' | pwsh -File ./hexdump.ps1
```

```Output
OEM United States
Label: Byte[] (System.Byte[]) <28873E25>

Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 63 61 66 C3 A9 0D 0A caf�
```

After the encoding change, the `findstr.exe` command finds the Unicode
characters.
The following example shows how the bytes change when changing the encoding
to [**UnicodeEncoding**][60].

```powershell
findstr <Unicode-characters>
$OutputEncoding = [System.Text.Encoding]::Unicode
'café' | pwsh -File ./hexdump.ps1
```

```Output
test.txt: <Unicode-characters>
Label: Byte[] (System.Byte[]) <515A7DC3>

Offset Bytes Ascii
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
------ ----------------------------------------------- -----
0000000000000000 FF FE 63 00 61 00 66 00 E9 00 0D 00 0A 00 ÿþc a f é � �
```

## $ProgressPreference
Expand Down
Loading