UTF8Encoding 建構函式

參考

定義

命名空間:: System.Text

組件:: System.Text.Encoding.Extensions.dll

組件:: mscorlib.dll

組件:: netstandard.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

初始化 UTF8Encoding 類別的新執行個體。

多載

UTF8Encoding()	初始化 UTF8Encoding 類別的新執行個體。
UTF8Encoding(Boolean)	初始化 UTF8Encoding 類別的新執行個體。參數會指定是否提供 Unicode 位元組順序標記。
UTF8Encoding(Boolean, Boolean)	初始化 UTF8Encoding 類別的新執行個體。參數會指定是否提供 Unicode 位元組順序標記，以及是否在偵測到無效的編碼方式時擲回例外狀況。

UTF8Encoding()

初始化 UTF8Encoding 類別的新執行個體。

public:
 UTF8Encoding();

public UTF8Encoding ();

Public Sub New ()

範例

下列範例會建立新的 UTF8Encoding 實例，並顯示其名稱。

using namespace System;
using namespace System::Text;
int main()
{
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   String^ encodingName = utf8->EncodingName;
   Console::WriteLine( "Encoding name: {0}", encodingName );
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        UTF8Encoding utf8 = new UTF8Encoding();
        String encodingName = utf8.EncodingName;
        Console.WriteLine("Encoding name: " + encodingName);
    }
}

Imports System.Text

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        Dim utf8 As New UTF8Encoding()
        Dim encodingName As String = utf8.EncodingName
        Console.WriteLine("Encoding name: " & encodingName)
    End Sub
End Class

備註

此建構函式會建立實例，該實例未提供 Unicode 位元組順序標記，而且在偵測到不正確編碼時不會擲回例外狀況。

警告

基於安全性考慮，建議您呼叫具有 throwOnInvalidBytes 參數的建構函式，並將其值設定為 true ，以啟用錯誤偵測。

另請參閱

GetPreamble()

適用於

UTF8Encoding(Boolean)

初始化 UTF8Encoding 類別的新執行個體。參數會指定是否提供 Unicode 位元組順序標記。

public:
 UTF8Encoding(bool encoderShouldEmitUTF8Identifier);

public UTF8Encoding (bool encoderShouldEmitUTF8Identifier);

new System.Text.UTF8Encoding : bool -> System.Text.UTF8Encoding

Public Sub New (encoderShouldEmitUTF8Identifier As Boolean)

參數

encoderShouldEmitUTF8Identifier: Boolean

true 指定 GetPreamble() 方法會傳回 Unicode 位元組順序標記；否則為 false。

範例

下列範例會建立新的 UTF8Encoding 實例，並指定方法應該發出 GetPreamble Unicode 位元組順序標記前置詞。方法 GetPreamble 接著會傳回 Unicode 位元組順序標記前置詞。

using namespace System;
using namespace System::Text;
using namespace System::Collections;
void ShowArray( Array^ theArray )
{
   IEnumerator^ myEnum = theArray->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Object^ o = safe_cast<Object^>(myEnum->Current);
      Console::Write( "[{0}]", o );
   }

   Console::WriteLine();
}

int main()
{
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   UTF8Encoding^ utf8EmitBOM = gcnew UTF8Encoding( true );
   Console::WriteLine( "utf8 preamble:" );
   ShowArray( utf8->GetPreamble() );
   Console::WriteLine( "utf8EmitBOM:" );
   ShowArray( utf8EmitBOM->GetPreamble() );
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        UTF8Encoding utf8 = new UTF8Encoding();
        UTF8Encoding utf8EmitBOM = new UTF8Encoding(true);

        Console.WriteLine("utf8 preamble:");
        ShowArray(utf8.GetPreamble());

        Console.WriteLine("utf8EmitBOM:");
        ShowArray(utf8EmitBOM.GetPreamble());
    }

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray) {
            Console.Write("[{0}]", o);
        }
        Console.WriteLine();
    }
}

Imports System.Text

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        Dim utf8 As New UTF8Encoding()
        Dim utf8EmitBOM As New UTF8Encoding(True)
        
        Console.WriteLine("utf8 preamble:")
        ShowArray(utf8.GetPreamble())
        
        Console.WriteLine("utf8EmitBOM:")
        ShowArray(utf8EmitBOM.GetPreamble())
    End Sub
    
    
    Public Shared Sub ShowArray(theArray As Array)
        Dim o As Object
        For Each o In  theArray
            Console.Write("[{0}]", o)
        Next o
        Console.WriteLine()
    End Sub
End Class

備註

此建構函式會建立實例，在偵測到不正確編碼時不會擲回例外狀況。

警告

基於安全性考慮，您應該呼叫包含 throwOnInvalidBytes 參數的建構函式，並將其值設定為 true ，以啟用錯誤偵測。

參數 encoderShouldEmitUTF8Identifier 會控制方法的 GetPreamble 作業。如果 true 為，此方法會傳回位元組陣列，其中包含 UTF-8 格式的 Unicode 位元組順序標記 (BOM) 。如果 false 為，則會傳回長度為零的位元組陣列。不過，將設定 encoderShouldEmitUTF8Identifiertrue 為不會讓 GetBytes 方法在位元組陣列開頭加上 BOM，也不會造成 GetByteCount 方法在位元組計數的 BOM 中包含位元組數目。

另請參閱

GetPreamble()

適用於

UTF8Encoding(Boolean, Boolean)

初始化 UTF8Encoding 類別的新執行個體。參數會指定是否提供 Unicode 位元組順序標記，以及是否在偵測到無效的編碼方式時擲回例外狀況。

public:
 UTF8Encoding(bool encoderShouldEmitUTF8Identifier, bool throwOnInvalidBytes);

public UTF8Encoding (bool encoderShouldEmitUTF8Identifier, bool throwOnInvalidBytes);

new System.Text.UTF8Encoding : bool * bool -> System.Text.UTF8Encoding

Public Sub New (encoderShouldEmitUTF8Identifier As Boolean, throwOnInvalidBytes As Boolean)

參數

encoderShouldEmitUTF8Identifier: Boolean

true 指定 GetPreamble() 方法應傳回 Unicode 位元組順序標記；否則為 false。

throwOnInvalidBytes: Boolean

true 表示在偵測到無效的編碼方式時擲回例外狀況；否則為 false。

範例

下列範例會建立新的 UTF8Encoding 實例，指定 GetPreamble 方法不應該發出 Unicode 位元組順序標記前置詞，而且偵測到不正確編碼時，應該擲回例外狀況。此建構函式的行為會與預設 UTF8Encoding() 建構函式進行比較，當偵測到不正確編碼時，不會擲回例外狀況。兩 UTF8Encoding 個實例會編碼字元陣列，其中包含兩個高 Surrogate (U+D801 和 U+D802) 資料列中，這是不正確字元序列;高 Surrogate 應一律接在低 Surrogate 後面。

using namespace System;
using namespace System::Text;

void ShowArray(Array^ theArray)
{
   for each (Byte b in theArray) {
      Console::Write( "{0:X2} ", b);
   }
   Console::WriteLine();
}

int main()
{
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   UTF8Encoding^ utf8ThrowException = gcnew UTF8Encoding(false,true);
   
   // This array contains two high surrogates in a row (\uD801, \uD802).
   array<Char>^chars = {'a','b','c',L'\xD801',L'\xD802','d'};
   
   // The following method call will not throw an exception.
   array<Byte>^bytes = utf8->GetBytes( chars );
   ShowArray( bytes );
   Console::WriteLine();
   
   try {
      
      // The following method call will throw an exception.
      bytes = utf8ThrowException->GetBytes( chars );
   }
   catch (EncoderFallbackException^ e ) {
            Console::WriteLine("{0} exception\nMessage:\n{1}",
                               e->GetType()->Name, e->Message);
   }

}

using System;
using System.Text;

class Example
{
    public static void Main()
    {
        UTF8Encoding utf8 = new UTF8Encoding();
        UTF8Encoding utf8ThrowException = new UTF8Encoding(false, true);

        // Create an array with two high surrogates in a row (\uD801, \uD802).
        Char[] chars = new Char[] {'a', 'b', 'c', '\uD801', '\uD802', 'd'};

        // The following method call will not throw an exception.
        Byte[] bytes = utf8.GetBytes(chars);
        ShowArray(bytes);
        Console.WriteLine();

        try {
            // The following method call will throw an exception.
            bytes = utf8ThrowException.GetBytes(chars);
            ShowArray(bytes);
        }
        catch (EncoderFallbackException e) {
            Console.WriteLine("{0} exception\nMessage:\n{1}",
                              e.GetType().Name, e.Message);
        }
    }

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray)
            Console.Write("{0:X2} ", o);

        Console.WriteLine();
    }
}
// The example displays the following output:
//    61 62 63 EF BF BD EF BF BD 64
//
//    EncoderFallbackException exception
//    Message:
//    Unable to translate Unicode character \uD801 at index 3 to specified code page.

Imports System.Text

Class Example
    Public Shared Sub Main()
        Dim utf8 As New UTF8Encoding()
        Dim utf8ThrowException As New UTF8Encoding(False, True)
        
        ' Create an array with two high surrogates in a row (\uD801, \uD802).
        Dim chars() As Char = {"a"c, "b"c, "c"c, ChrW(&hD801), ChrW(&hD802), "d"c}
        
        ' The following method call will not throw an exception.
        Dim bytes As Byte() = utf8.GetBytes(chars)
        ShowArray(bytes)
        Console.WriteLine()
        
        Try
            ' The following method call will throw an exception.
            bytes = utf8ThrowException.GetBytes(chars)
            ShowArray(bytes)
        Catch e As EncoderFallbackException
            Console.WriteLine("{0} exception{2}Message:{2}{1}",
                              e.GetType().Name, e.Message, vbCrLf)
        End Try
    End Sub
    
    
    Public Shared Sub ShowArray(theArray As Array)
        For Each o In theArray
            Console.Write("{0:X2} ", o)
        Next
        Console.WriteLine()
    End Sub
End Class
' The example displays the following output:
'    61 62 63 EF BF BD EF BF BD 64
'
'    EncoderFallbackException exception
'    Message:
'    Unable to translate Unicode character \uD801 at index 3 to specified code page.

備註

如果 throwOnInvalidBytes 為 true ，則偵測無效位元組序列的方法會 System.ArgumentException 擲回例外狀況。否則，方法不會擲回例外狀況，而且會忽略不正確序列。

警告

基於安全性考慮，您應該呼叫包含 throwOnInvalidBytes 參數的建構函式，並將該參數設定為 true ，以啟用錯誤偵測。

另請參閱

GetPreamble()

適用於

UTF8Encoding 建構函式

定義

多載

UTF8Encoding()

範例

備註

另請參閱

適用於

UTF8Encoding(Boolean)

參數

範例

備註

另請參閱

適用於

UTF8Encoding(Boolean, Boolean)

參數

範例

備註

另請參閱

適用於

其他資源