System.Text.Encoding 類別

本文提供此 API 參考文件的補充備註。

Encoding 類別表示字元編碼方式。

編碼是將一組 Unicode 字元轉換成位元組序列的處理程序。 相反地，譯碼是將編碼位元組序列轉換成一組 Unicode 字元的程式。 如需 Unicode 轉換格式 #UTF 和其他支援的 Encoding編碼資訊，請參閱 .NET 中的字元編碼。

Encoding 是要在 Unicode 字元上運作，而不是任意二進位數據，例如位元組陣列。 如果您必須將任意二進位數據編碼為文字，則應該使用 uuencode 之類的通訊協定，此通訊協定是由 之類的 Convert.ToBase64CharArray方法實作。

.NET 提供 類別的 Encoding 下列實作，以支援目前的 Unicode 編碼和其他編碼：

• ASCIIEncoding 將 Unicode 字元編碼為單一 7 位 ASCII 字元。 此編碼只支援U+0000與U+007F之間的字元值。 代碼頁 20127。 也可以透過 ASCII 屬性取得。

• UTF7Encoding 使用UTF-7編碼來編碼 Unicode 字元。 此編碼支援所有 Unicode 字元值。 代碼頁 65000。 也可以透過 UTF7 屬性取得。

• UTF8Encoding 使用UTF-8編碼來編碼 Unicode 字元。 此編碼支援所有 Unicode 字元值。 代碼頁 65001。 也可以透過 UTF8 屬性取得。

• UnicodeEncoding 使用UTF-16編碼來編碼Unicode字元。 支援小端和大端位元組順序。 也可以透過 Unicode 屬性和 BigEndianUnicode 屬性取得。

• UTF32Encoding 使用UTF-32編碼來編碼 Unicode 字元。 支援小 endian （代碼頁 12000） 和 big endian （代碼頁 12001） 位元組順序。 也可以透過 UTF32 屬性取得。

類別 Encoding 主要用來在不同的編碼和 Unicode 之間轉換。 通常其中一個衍生的 Unicode 類別是應用程式的正確選擇。

GetEncoding使用 方法來取得其他編碼方式，並呼叫 GetEncodings 方法以取得所有編碼的清單。

編碼清單

下表列出 .NET 支援的編碼方式。 它會列出每個編碼的代碼頁碼，以及編碼的 EncodingInfo.Name 和 EncodingInfo.DisplayName 屬性的值。 .NET Framework 支援、.NET Core 支援或 .NET 5 及更新版本支援數據行中的複選標記表示不論基礎平台為何，該 .NET 實作原生支持代碼頁。 針對 .NET Framework，數據表中列出的其他編碼可用性取決於操作系統。 針對 .NET Core 和 .NET 5 和更新版本，可以使用 類別或衍生自 System.Text.EncodingProvider 類別來取得System.Text.CodePagesEncodingProvider其他編碼。

下列範例會呼叫 GetEncoding(Int32) 和 GetEncoding(String) 方法來取得希臘文 （Windows） 代碼頁編碼。 它會比較 Encoding 方法呼叫所傳回的物件，以顯示它們相等，然後對應會顯示希臘文字母表中每個字元的 Unicode 字碼點和對應的代碼頁值。

using System;
using System.Text;

public class Example
{
   public static void Main()
   {
      Encoding enc = Encoding.GetEncoding(1253);
      Encoding altEnc = Encoding.GetEncoding("windows-1253");
      Console.WriteLine("{0} = Code Page {1}: {2}", enc.EncodingName,
                        altEnc.CodePage, enc.Equals(altEnc));
      string greekAlphabet = "Α α Β β Γ γ Δ δ Ε ε Ζ ζ Η η " +
                             "Θ θ Ι ι Κ κ Λ λ Μ μ Ν ν Ξ ξ " +
                             "Ο ο Π π Ρ ρ Σ σ ς Τ τ Υ υ " +
                             "Φ φ Χ χ Ψ ψ Ω ω";
      Console.OutputEncoding = Encoding.UTF8;
      byte[] bytes = enc.GetBytes(greekAlphabet);
      Console.WriteLine("{0,-12} {1,20} {2,20:X2}", "Character",
                        "Unicode Code Point", "Code Page 1253");
      for (int ctr = 0; ctr < bytes.Length; ctr++) {
         if (greekAlphabet[ctr].Equals(' '))
            continue;

         Console.WriteLine("{0,-12} {1,20} {2,20:X2}", greekAlphabet[ctr],
                           GetCodePoint(greekAlphabet[ctr]), bytes[ctr]);
      }
   }

   private static string GetCodePoint(char ch)
   {
      string retVal = "u+";
      byte[] bytes = Encoding.Unicode.GetBytes(ch.ToString());
      for (int ctr = bytes.Length - 1; ctr >= 0; ctr--)
         retVal += bytes[ctr].ToString("X2");

      return retVal;
   }
}
// The example displays the following output:
//       Character      Unicode Code Point       Code Page 1253
//       Α                          u+0391                   C1
//       α                          u+03B1                   E1
//       Β                          u+0392                   C2
//       β                          u+03B2                   E2
//       Γ                          u+0393                   C3
//       γ                          u+03B3                   E3
//       Δ                          u+0394                   C4
//       δ                          u+03B4                   E4
//       Ε                          u+0395                   C5
//       ε                          u+03B5                   E5
//       Ζ                          u+0396                   C6
//       ζ                          u+03B6                   E6
//       Η                          u+0397                   C7
//       η                          u+03B7                   E7
//       Θ                          u+0398                   C8
//       θ                          u+03B8                   E8
//       Ι                          u+0399                   C9
//       ι                          u+03B9                   E9
//       Κ                          u+039A                   CA
//       κ                          u+03BA                   EA
//       Λ                          u+039B                   CB
//       λ                          u+03BB                   EB
//       Μ                          u+039C                   CC
//       μ                          u+03BC                   EC
//       Ν                          u+039D                   CD
//       ν                          u+03BD                   ED
//       Ξ                          u+039E                   CE
//       ξ                          u+03BE                   EE
//       Ο                          u+039F                   CF
//       ο                          u+03BF                   EF
//       Π                          u+03A0                   D0
//       π                          u+03C0                   F0
//       Ρ                          u+03A1                   D1
//       ρ                          u+03C1                   F1
//       Σ                          u+03A3                   D3
//       σ                          u+03C3                   F3
//       ς                          u+03C2                   F2
//       Τ                          u+03A4                   D4
//       τ                          u+03C4                   F4
//       Υ                          u+03A5                   D5
//       υ                          u+03C5                   F5
//       Φ                          u+03A6                   D6
//       φ                          u+03C6                   F6
//       Χ                          u+03A7                   D7
//       χ                          u+03C7                   F7
//       Ψ                          u+03A8                   D8
//       ψ                          u+03C8                   F8
//       Ω                          u+03A9                   D9
//       ω                          u+03C9                   F9

Imports System.Text

Module Example
   Public Sub Main()
      Dim enc As Encoding = Encoding.GetEncoding(1253)
      Dim altEnc As Encoding = Encoding.GetEncoding("windows-1253")
      Console.WriteLine("{0} = Code Page {1}: {2}", enc.EncodingName,
                        altEnc.CodePage, enc.Equals(altEnc))
      Dim greekAlphabet As String = "Α α Β β Γ γ Δ δ Ε ε Ζ ζ Η η " +
                                    "Θ θ Ι ι Κ κ Λ λ Μ μ Ν ν Ξ ξ " +
                                    "Ο ο Π π Ρ ρ Σ σ ς Τ τ Υ υ " +
                                    "Φ φ Χ χ Ψ ψ Ω ω"
      Console.OutputEncoding = Encoding.UTF8
      Dim bytes() As Byte = enc.GetBytes(greekAlphabet)
      Console.WriteLine("{0,-12} {1,20} {2,20:X2}", "Character",
                        "Unicode Code Point", "Code Page 1253")
      For ctr As Integer = 0 To bytes.Length - 1
         If greekAlphabet(ctr).Equals(" "c) Then Continue For

         Console.WriteLine("{0,-12} {1,20} {2,20:X2}", greekAlphabet(ctr),
                           GetCodePoint(greekAlphabet(ctr)), bytes(ctr))
      Next

   End Sub
   
   Private Function GetCodePoint(ch As String) As String
      Dim retVal As String = "u+"
      Dim bytes() As Byte = Encoding.Unicode.GetBytes(ch)
      For ctr As Integer = bytes.Length - 1 To 0 Step -1
         retVal += bytes(ctr).ToString("X2")
      Next
      Return retVal
   End Function
End Module
' The example displays the following output:
'    Character      Unicode Code Point       Code Page 1253
'    Α                          u+0391                   C1
'    α                          u+03B1                   E1
'    Β                          u+0392                   C2
'    β                          u+03B2                   E2
'    Γ                          u+0393                   C3
'    γ                          u+03B3                   E3
'    Δ                          u+0394                   C4
'    δ                          u+03B4                   E4
'    Ε                          u+0395                   C5
'    ε                          u+03B5                   E5
'    Ζ                          u+0396                   C6
'    ζ                          u+03B6                   E6
'    Η                          u+0397                   C7
'    η                          u+03B7                   E7
'    Θ                          u+0398                   C8
'    θ                          u+03B8                   E8
'    Ι                          u+0399                   C9
'    ι                          u+03B9                   E9
'    Κ                          u+039A                   CA
'    κ                          u+03BA                   EA
'    Λ                          u+039B                   CB
'    λ                          u+03BB                   EB
'    Μ                          u+039C                   CC
'    μ                          u+03BC                   EC
'    Ν                          u+039D                   CD
'    ν                          u+03BD                   ED
'    Ξ                          u+039E                   CE
'    ξ                          u+03BE                   EE
'    Ο                          u+039F                   CF
'    ο                          u+03BF                   EF
'    Π                          u+03A0                   D0
'    π                          u+03C0                   F0
'    Ρ                          u+03A1                   D1
'    ρ                          u+03C1                   F1
'    Σ                          u+03A3                   D3
'    σ                          u+03C3                   F3
'    ς                          u+03C2                   F2
'    Τ                          u+03A4                   D4
'    τ                          u+03C4                   F4
'    Υ                          u+03A5                   D5
'    υ                          u+03C5                   F5
'    Φ                          u+03A6                   D6
'    φ                          u+03C6                   F6
'    Χ                          u+03A7                   D7
'    χ                          u+03C7                   F7
'    Ψ                          u+03A8                   D8
'    ψ                          u+03C8                   F8
'    Ω                          u+03A9                   D9
'    ω                          u+03C9                   F9

如果要轉換的資料僅適用於循序區塊（例如從資料流讀取的數據），或資料量太大而需要分割成較小的區塊，則您應該分別使用 Decoder 衍生類別的 方法或 EncoderGetEncoder 方法所提供的 GetDecoder 。

UTF-16 和 UTF-32 編碼器可以使用大位元組位元組順序（最顯著位元組優先）或小位元組位元組順序（最不重要位元組優先）。 例如，拉丁大寫字母 A （U+0041） 會串行化如下（十六進位）：

• UTF-16 大位元組位元組順序：00 41
• UTF-16 小端位元組順序：41 00
• UTF-32 big endian byte order： 00 00 00 41
• UTF-32 小端位元組順序：41 00 00 00

使用原生位元節順序來儲存 Unicode 字元通常更有效率。 例如，最好在小端平臺上使用小位元組位元組順序，例如 Intel 計算機。

方法 GetPreamble 會擷取位元組陣列，其中包含位元組順序標記 （BOM）。 如果這個位元組數位前面加上編碼數據流，它可協助譯碼器識別所使用的編碼格式。

如需位元組順序和位元組順序標記的詳細資訊，請參閱 Unicode 首頁上的 Unicode 標準。

請注意，編碼類別允許錯誤：

• 以無訊息方式變更為 “？” 字元。
• 使用「最適合」字元。
• 透過使用 EncoderFallback 和 DecoderFallback 類別搭配U+FFFD Unicode 取代字元，變更為應用程式特定行為。

您應該在任何數據流錯誤上擲回例外狀況。 當適用或使用和 DecoderExceptionFallback 類別時，應用程式會使用EncoderExceptionFallback“throwonerror” 旗標。 通常不建議使用最佳配適後援，因為它可能會導致數據遺失或混淆，而且比簡單的字元取代速度慢。 針對 ANSI 編碼，最適合的行為是預設值。