UnicodeEncoding 類別

定義

命名空間:

System.Text

組件:

netstandard.dll, System.Text.Encoding.Extensions.dll

來源:

UnicodeEncoding.cs

代表 Unicode 字元的 UTF-16 編碼。

public ref class UnicodeEncoding : System::Text::Encoding

public class UnicodeEncoding : System.Text.Encoding

type UnicodeEncoding = class
    inherit Encoding

Public Class UnicodeEncoding
Inherits Encoding

繼承

Object

Encoding

UnicodeEncoding

範例

以下範例示範如何利用 UnicodeEncoding 物件將一串 Unicode 字元編碼成位元組陣列。 位元組陣列會被解碼成字串，以證明不會遺失資料。

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        // The encoding.
        UnicodeEncoding unicode = new UnicodeEncoding();
        
        // Create a string that contains Unicode characters.
        String unicodeString =
            "This Unicode string contains two characters " +
            "with codes outside the traditional ASCII code range, " +
            "Pi (\u03a0) and Sigma (\u03a3).";
        Console.WriteLine("Original string:");
        Console.WriteLine(unicodeString);

        // Encode the string.
        Byte[] encodedBytes = unicode.GetBytes(unicodeString);
        Console.WriteLine();
        Console.WriteLine("Encoded bytes:");
        foreach (Byte b in encodedBytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
        
        // Decode bytes back to string.
        // Notice Pi and Sigma characters are still present.
        String decodedString = unicode.GetString(encodedBytes);
        Console.WriteLine();
        Console.WriteLine("Decoded bytes:");
        Console.WriteLine(decodedString);
    }
}

Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class UnicodeEncodingExample
    
    Public Shared Sub Main()
        ' The encoding.
        Dim uni As New UnicodeEncoding()
        
        ' Create a string that contains Unicode characters.
        Dim unicodeString As String = _
            "This Unicode string contains two characters " & _
            "with codes outside the traditional ASCII code range, " & _
            "Pi (" & ChrW(928) & ") and Sigma (" & ChrW(931) & ")."
        Console.WriteLine("Original string:")
        Console.WriteLine(unicodeString)
        
        ' Encode the string.
        Dim encodedBytes As Byte() = uni.GetBytes(unicodeString)
        Console.WriteLine()
        Console.WriteLine("Encoded bytes:")
        Dim b As Byte
        For Each b In  encodedBytes
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine()
        
        ' Decode bytes back to string.
        ' Notice Pi and Sigma characters are still present.
        Dim decodedString As String = uni.GetString(encodedBytes)
        Console.WriteLine()
        Console.WriteLine("Decoded bytes:")
        Console.WriteLine(decodedString)
    End Sub
End Class

以下範例使用與前一個相同的字串，但將編碼的位元組寫入檔案，並在位元組串流前加上位元組順序標記（BOM）。 接著它以兩種不同方式讀取檔案：透過物件 StreamReader 作為文字檔讀取;以及以二進位檔讀取。 如你所料，這兩個新讀的字串都沒有包含BOM。

using System;
using System.IO;
using System.Text;

public class Example
{
   public static void Main()
   {
        // Create a UTF-16 encoding that supports a BOM.
        Encoding unicode = new UnicodeEncoding();

        // A Unicode string with two characters outside an 8-bit code range.
        String unicodeString =
            "This Unicode string has 2 characters outside the " +
            "ASCII range: \n" +
            "Pi (\u03A0)), and Sigma (\u03A3).";
        Console.WriteLine("Original string:");
        Console.WriteLine(unicodeString);
        Console.WriteLine();

        // Encode the string.
        Byte[] encodedBytes = unicode.GetBytes(unicodeString);
        Console.WriteLine("The encoded string has {0} bytes.\n",
                          encodedBytes.Length);

        // Write the bytes to a file with a BOM.
        var fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Create);
        Byte[] bom = unicode.GetPreamble();
        fs.Write(bom, 0, bom.Length);
        fs.Write(encodedBytes, 0, encodedBytes.Length);
        Console.WriteLine("Wrote {0} bytes to the file.\n", fs.Length);
        fs.Close();

        // Open the file using StreamReader.
        var sr = new StreamReader(@".\UTF8Encoding.txt");
        String newString = sr.ReadToEnd();
        sr.Close();
        Console.WriteLine("String read using StreamReader:");
        Console.WriteLine(newString);
        Console.WriteLine();

        // Open the file as a binary file and decode the bytes back to a string.
        fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Open);
        Byte[] bytes = new Byte[fs.Length];
        fs.Read(bytes, 0, (int)fs.Length);
        fs.Close();

        String decodedString = unicode.GetString(bytes);
        Console.WriteLine("Decoded bytes:");
        Console.WriteLine(decodedString);
   }
}
// The example displays the following output:
//    Original string:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).
//
//    The encoded string has 172 bytes.
//
//    Wrote 174 bytes to the file.
//
//    String read using StreamReader:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).
//
//    Decoded bytes:
//    This Unicode string has 2 characters outside the ASCII range:
//    Pi (π), and Sigma (Σ).

Imports System.IO
Imports System.Text

Class Example
    Public Shared Sub Main()
        ' Create a UTF-16 encoding that supports a BOM.
        Dim unicode As New UnicodeEncoding()
        
        ' A Unicode string with two characters outside an 8-bit code range.
        Dim unicodeString As String = _
            "This Unicode string has 2 characters outside the " &
            "ASCII range: " & vbCrLf &
            "Pi (" & ChrW(&h03A0) & "), and Sigma (" & ChrW(&h03A3) & ")."
        Console.WriteLine("Original string:")
        Console.WriteLine(unicodeString)
        Console.WriteLine()
        
        ' Encode the string.
        Dim encodedBytes As Byte() = unicode.GetBytes(unicodeString)
        Console.WriteLine("The encoded string has {0} bytes.",
                          encodedBytes.Length)
        Console.WriteLine()
        
        ' Write the bytes to a file with a BOM.
        Dim fs As New FileStream(".\UnicodeEncoding.txt", FileMode.Create)
        Dim bom() As Byte = unicode.GetPreamble()
        fs.Write(bom, 0, bom.Length)
        fs.Write(encodedBytes, 0, encodedBytes.Length)
        Console.WriteLine("Wrote {0} bytes to the file.", fs.Length)
        fs.Close()
        Console.WriteLine()
        
        ' Open the file using StreamReader.
        Dim sr As New StreamReader(".\UnicodeEncoding.txt")
        Dim newString As String = sr.ReadToEnd()
        sr.Close()
        Console.WriteLine("String read using StreamReader:")
        Console.WriteLine(newString)
        Console.WriteLine()
        
        ' Open the file as a binary file and decode the bytes back to a string.
        fs = new FileStream(".\UnicodeEncoding.txt", FileMode.Open)
        Dim bytes(fs.Length - 1) As Byte
        fs.Read(bytes, 0, fs.Length)
        fs.Close()

        Dim decodedString As String = unicode.GetString(bytes)
        Console.WriteLine("Decoded bytes:")
        Console.WriteLine(decodedString)
    End Sub
End Class
' The example displays the following output:
'    Original string:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).
'
'    The encoded string has 172 bytes.
'
'    Wrote 174 bytes to the file.
'
'    String read using StreamReader:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).
'
'    Decoded bytes:
'    This Unicode string has 2 characters outside the ASCII range:
'    Pi (π), and Sigma (Σ).

備註

編碼是將一組 Unicode 字元轉換成位元組序列的程式。 解碼是將一連串編碼好的位元組轉換成一組 Unicode 字元的過程。

Unicode 標準會為每個支援的文字中的每個字元指派一個代碼點（數字）。 Unicode 轉換格式（UTF）是一種編碼該碼點的方法。 Unicode 標準使用以下 UTF：

• UTF-8，將每個碼點以一到四個位元組的序列表示。

• UTF-16，將每個碼點以一到兩個16位元整數序列表示。

• UTF-32，將每個碼點表示為 32 位元整數。

欲了解更多關於 支援的 UTF 及其他 System.Text編碼的資訊，請參閱 .NET Framework 中的字元編碼。

該 UnicodeEncoding 類別代表一種 UTF-16 編碼。 編碼器可以使用大端序位元組序（最有效位元組優先）或小端序位元組序（最低有效位元組優先）。 例如，拉丁字母 A（代碼點 U+0041）的序列如下（十六進位）：

• 大端序位元組序：00 00 00 41

• 小端序位元組序：41 00 00 00

通常使用特定平台的原生位元組順序來儲存 Unicode 字元會更有效率。 例如，最好在小端平臺上使用小位元組位元組順序，例如 Intel 計算機。 此 UnicodeEncoding 類別對應 Windows 代碼頁 1200（小端位元組序）與 1201（大端序位元組序）。 你可以透過呼叫 BitConverter.IsLittleEndian 該方法來判斷特定架構的「端序性」。

物件可 UnicodeEncoding 選擇性地提供位元組順序標記（BOM），這是一個可加在編碼過程產生的位元組序列前綴的位元組陣列。 如果前導碼包含位元組順序標記（BOM），它有助於解碼器決定位元組順序及轉換格式（UTF）。

如果實 UnicodeEncoding 例設定提供物料清單（BOM），你可以透過呼叫該 GetPreamble 方法來取得;否則，方法會回傳一個空陣列。 請注意，即使 UnicodeEncoding 物件已設定為 BOM 支援，也必須在編碼的位元組流開頭適當地包含 BOM;類別的 UnicodeEncoding 編碼方法不會自動做到這點。

Caution

為了啟用錯誤偵測並提升類別實例的安全，你應該透過呼叫UnicodeEncoding(Boolean, Boolean, Boolean)建構子並將其參數true設throwOnInvalidBytes為 來實例化物件UnicodeEncoding。 在錯誤偵測中，偵測無效字元序列或位元組的方法會拋出一個 ArgumentException。 若沒有錯誤偵測，則不會拋出例外，且無效序列通常會被忽略。

你可以用多種方式實例化一個 UnicodeEncoding 物件，取決於你是否希望它提供位元組順序標記（BOM）、你想要大端還是小端編碼，以及你是否想啟用錯誤偵測。 下表列出了回傳UnicodeEncoding物件的UnicodeEncoding建構子與Encoding屬性。

會員	位元組序	BOM	錯誤偵測
BigEndianUnicode	大端序	是的	不行（替代備用）
Encoding.Unicode	小端序	是的	不行（替代備用）
UnicodeEncoding.UnicodeEncoding()	小端序	是的	不行（替代備用）
UnicodeEncoding(Boolean, Boolean)	Configurable	Configurable	不行（替代備用）
UnicodeEncoding.UnicodeEncoding(Boolean, Boolean, Boolean)	Configurable	Configurable	Configurable

該 GetByteCount 方法決定編碼一組 Unicode 字元的位元組數，並 GetBytes 執行實際編碼。

同樣地，方法 GetCharCount 決定解碼一串位元組的字元數，而 和 GetCharsGetString 方法則執行實際解碼。

對於能在編碼或解碼跨多個區塊的資料（例如以 100,000 字元區段編碼的 100 萬字元字串）時儲存狀態資訊的編碼器或解碼器，分別使用 GetEncoder 和 GetDecoder 屬性。

建構函式

名稱	Description
UnicodeEncoding()	初始化 UnicodeEncoding 類別的新執行個體。
UnicodeEncoding(Boolean, Boolean, Boolean)	初始化 UnicodeEncoding 類別的新執行個體。 參數會指定是否使用大端序位元組序、是否提供 Unicode 位元組序標記，以及當偵測到無效編碼時是否拋出例外。
UnicodeEncoding(Boolean, Boolean)	初始化 UnicodeEncoding 類別的新執行個體。 參數會指定是否使用大端序位元組序，以及方法是否 GetPreamble() 回傳 Unicode 位元組序標記。

欄位

名稱	Description
CharSize	以位元組表示 Unicode 字元大小。 這個場域是一個常數。

屬性

名稱	Description
BodyName	當在衍生類別中覆寫時，會獲得一個可用於郵件代理體標籤的當前編碼名稱。 (繼承來源 Encoding)
CodePage	當在衍生類別中被覆寫時，會獲得目前 Encoding的代碼頁識別碼。 (繼承來源 Encoding)
DecoderFallback	取得或設定 DecoderFallback 當前 Encoding 物件的物件。 (繼承來源 Encoding)
EncoderFallback	取得或設定 EncoderFallback 當前 Encoding 物件的物件。 (繼承來源 Encoding)
EncodingName	當在衍生類別中覆寫時，會得到目前編碼的人類可讀描述。 (繼承來源 Encoding)
HeaderName	當 在衍生類別中被覆寫時，會獲得一個可用於郵件代理標頭標籤的當前編碼名稱。 (繼承來源 Encoding)
IsBrowserDisplay	當 在衍生類別中覆寫時，會獲得一個值，表示瀏覽器客戶端是否可以使用目前的編碼來顯示內容。 (繼承來源 Encoding)
IsBrowserSave	當在衍生類別中覆寫時，會獲得一個值，表示瀏覽器客戶端是否能使用目前的編碼來儲存內容。 (繼承來源 Encoding)
IsMailNewsDisplay	當在派生類別中覆寫時，會獲得一個值，表示目前的編碼是否可用於郵件和新聞用戶端顯示內容。 (繼承來源 Encoding)
IsMailNewsSave	當在衍生類別中覆寫時，會獲得一個值，表示目前的編碼是否能被郵件和新聞客戶端用來儲存內容。 (繼承來源 Encoding)
IsReadOnly	當在衍生類別中覆寫時，會獲得一個值，表示目前編碼是否為唯讀。 (繼承來源 Encoding)
IsSingleByte	當在派生類別中覆寫時，會得到一個值，表示目前編碼是否使用單位元組的碼點。 (繼承來源 Encoding)
Preamble	若此物件設定為提供 Unicode 位元組順序標記，則會獲得 UTF-16 格式編碼的 Unicode 位元組順序標記。
WebName	當在衍生類別中被覆寫時，會獲得目前編碼的名稱，註冊於網際網路號碼分配管理局（IANA）。 (繼承來源 Encoding)
WindowsCodePage	當在衍生類別中覆寫時，會得到與目前編碼最接近的 Windows 作業系統代碼頁。 (繼承來源 Encoding)

方法

名稱	Description
Clone()	當在衍生類別中覆寫時，會產生目前 Encoding 物件的淺層副本。 (繼承來源 Encoding)
Equals(Object)	判斷指定的 Object 是否等於當前 UnicodeEncoding 物件。
GetByteCount(Char[], Int32, Int32)	計算從指定字元陣列編碼一組字元所產生的位元組數。
GetByteCount(Char[])	當在派生類別中覆寫時，會計算將指定字元陣列中所有字元編碼所產生的位元組數。 (繼承來源 Encoding)
GetByteCount(Char*, Int32)	計算從指定字元指標開始編碼一組字元所產生的位元組數。
GetByteCount(ReadOnlySpan<Char>)	當在派生類別中覆寫時，會計算在指定字元區間內編碼字元所產生的位元組數。 (繼承來源 Encoding)
GetByteCount(String, Int32, Int32)	當在派生類別中覆寫時，會計算從指定字串編碼一組字元所產生的位元組數。 (繼承來源 Encoding)
GetByteCount(String)	計算透過編碼指定字串字元所產生的位元組數。
GetBytes(Char[], Int32, Int32, Byte[], Int32)	將指定字元陣列中的一組字元編碼到指定的位元組陣列中。
GetBytes(Char[], Int32, Int32)	當在派生類別中覆寫時，會將指定字元陣列中的一組字元編碼成一串位元組。 (繼承來源 Encoding)
GetBytes(Char[])	當在派生類別中覆寫時，會將指定字元陣列中的所有字元編碼成一串位元組。 (繼承來源 Encoding)
GetBytes(Char*, Int32, Byte*, Int32)	將一組從指定字元指標開始的字元編碼成一串位元組，並從指定位元組指標開始儲存。
GetBytes(ReadOnlySpan<Char>, Span<Byte>)	當在派生類別中覆寫時，會將指定唯讀區間的一組字元編碼到位元組區間。 (繼承來源 Encoding)
GetBytes(String, Int32, Int32, Byte[], Int32)	將指定的 String 一組字元編碼到指定的位元組陣列中。
GetBytes(String, Int32, Int32)	當在派生類別中覆寫時，會將指定字串中指定的 count 字元數編碼到一個位元組陣列中，從指定的 index字串開始。 (繼承來源 Encoding)
GetBytes(String)	當在派生類別中覆寫時，會將指定字串中的所有字元編碼成一串位元組。 (繼承來源 Encoding)
GetCharCount(Byte[], Int32, Int32)	計算從指定位元組陣列解碼一串位元組所產生的字元數。
GetCharCount(Byte[])	當在派生類別中覆寫時，會計算解碼指定位元組陣列中所有位元組所產生的字元數。 (繼承來源 Encoding)
GetCharCount(Byte*, Int32)	透過解碼從指定位元組指標開始的一串位元組來計算字元數。
GetCharCount(ReadOnlySpan<Byte>)	當在衍生類別中覆寫時，會計算出解碼所提供的唯讀位元組區間所產生的字元數。 (繼承來源 Encoding)
GetChars(Byte[], Int32, Int32, Char[], Int32)	將指定位元組陣列的一串位元組解碼到指定的字元陣列。
GetChars(Byte[], Int32, Int32)	當在派生類別中覆寫時，會將指定位元組陣列中的一串位元組解碼成一組字元。 (繼承來源 Encoding)
GetChars(Byte[])	當在派生類別中覆寫時，會將指定位元組陣列中的所有位元組解碼成一組字元。 (繼承來源 Encoding)
GetChars(Byte*, Int32, Char*, Int32)	將從指定位元組指標開始的一串位元組解碼成一組字元，這些字元從指定字元指標開始儲存。
GetChars(ReadOnlySpan<Byte>, Span<Char>)	當在派生類別中覆寫時，會將指定唯讀位元組區間中的所有位元組解碼為字元區間。 (繼承來源 Encoding)
GetDecoder()	取得一個解碼器，能將 UTF-16 編碼的位元組序列轉換為 Unicode 字元序列。
GetEncoder()	取得一個編碼器，能將一串 Unicode 字元轉換成 UTF-16 編碼的位元組序列。
GetHashCode()	傳回目前實例的哈希碼。
GetMaxByteCount(Int32)	計算編碼指定字元數所產生的最大位元組數。
GetMaxCharCount(Int32)	計算解碼指定位元組數後產生的最大字元數。
GetPreamble()	若本實例的建構子請求位元組順序標記，則會回傳一個以 UTF-16 格式編碼的 Unicode 位元組順序標記。
GetString(Byte[], Int32, Int32)	將位元組陣列中的位元組範圍解碼成字串。
GetString(Byte[])	當在衍生類別中覆寫時，會將指定位元組陣列中的所有位元組解碼成一個字串。 (繼承來源 Encoding)
GetString(Byte*, Int32)	當在派生類別中覆寫時，會將從指定位址開始的指定位元組解碼成字串。 (繼承來源 Encoding)
GetString(ReadOnlySpan<Byte>)	當在派生類別中覆寫時，會將指定位元組區間中的所有位元組解碼成一個字串。 (繼承來源 Encoding)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
IsAlwaysNormalized()	會得到一個值，表示目前編碼是否總是正規化，使用預設的正規化形式。 (繼承來源 Encoding)
IsAlwaysNormalized(NormalizationForm)	當在派生類別中覆寫時，會得到一個值，表示目前編碼是否總是被正規化，並使用指定的正規化形式。 (繼承來源 Encoding)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)
TryGetBytes(ReadOnlySpan<Char>, Span<Byte>, Int32)	如果目的地夠大，則會將指定唯讀區段中的一組字元編碼成位元組區間。 (繼承來源 Encoding)
TryGetChars(ReadOnlySpan<Byte>, Span<Char>, Int32)	如果目的地夠大，則會將指定唯讀區段中的一組位元組解碼成字元區間。 (繼承來源 Encoding)

擴充方法

名稱	Description
GetBytes(Encoding, ReadOnlySequence<Char>, IBufferWriter<Byte>)	利用指定ReadOnlySequence<T>條件解碼 byte 至 Encodings，並將結果寫入 writer。
GetBytes(Encoding, ReadOnlySequence<Char>, Span<Byte>)	將指定 ReadOnlySequence<T> 內容編碼為 bytes，並 Encoding 輸出結果為 bytes。
GetBytes(Encoding, ReadOnlySequence<Char>)	將指定 ReadOnlySequence<T> 編碼成 Byte 一個陣列，使用指定的 Encoding。
GetBytes(Encoding, ReadOnlySpan<Char>, IBufferWriter<Byte>)	將指定 ReadOnlySpan<T> 內容編碼為 bytes，使用指定 Encoding 條件，並將結果寫入 writer。
GetChars(Encoding, ReadOnlySequence<Byte>, IBufferWriter<Char>)	利用指定ReadOnlySequence<T>條件解碼 char 至 Encodings，並將結果寫入 writer。
GetChars(Encoding, ReadOnlySequence<Byte>, Span<Char>)	利用指定ReadOnlySequence<T>條件將指定 charEncodings 解碼至 s，並將結果輸出為 chars。
GetChars(Encoding, ReadOnlySpan<Byte>, IBufferWriter<Char>)	利用指定ReadOnlySpan<T>條件解碼 char 至 Encodings，並將結果寫入 writer。
GetString(Encoding, ReadOnlySequence<Byte>)	利用指定的 ReadOnlySequence<T>將 解碼String為 。Encoding

另請參閱

• Encoding
• Encoder
• Decoder
• UTF32Encoding
• UTF8Encoding
• UTF7Encoding
• ASCIIEncoding
• UnicodeCategory
• CharUnicodeInfo
• 理解編碼