UTF8Encoding UTF8Encoding UTF8Encoding UTF8Encoding Constructors

定義

多載

UTF8Encoding() UTF8Encoding() UTF8Encoding()

初始化 UTF8Encoding 類別的新執行個體。Initializes a new instance of the UTF8Encoding class.

UTF8Encoding(Boolean) UTF8Encoding(Boolean) UTF8Encoding(Boolean) UTF8Encoding(Boolean)

初始化 UTF8Encoding 類別的新執行個體。Initializes a new instance of the UTF8Encoding class. 參數會指定是否提供 Unicode 位元組順序標記。A parameter specifies whether to provide a Unicode byte order mark.

UTF8Encoding(Boolean, Boolean) UTF8Encoding(Boolean, Boolean) UTF8Encoding(Boolean, Boolean) UTF8Encoding(Boolean, Boolean)

初始化 UTF8Encoding 類別的新執行個體。Initializes a new instance of the UTF8Encoding class. 參數會指定是否提供 Unicode 位元組順序標記,以及是否在偵測到無效的編碼方式時擲回例外狀況。Parameters specify whether to provide a Unicode byte order mark and whether to throw an exception when an invalid encoding is detected.

UTF8Encoding() UTF8Encoding() UTF8Encoding()

初始化 UTF8Encoding 類別的新執行個體。Initializes a new instance of the UTF8Encoding class.

public:
 UTF8Encoding();
public UTF8Encoding ();
Public Sub New ()

範例

下列範例會建立新UTF8Encoding的實例, 並顯示其名稱。The following example creates a new UTF8Encoding instance and displays its name.

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 位元組順序標記的實例, 而且在偵測到不正確編碼方式時, 不會擲回例外狀況。This constructor creates an instance that does not provide a Unicode byte order mark and does not throw an exception when an invalid encoding is detected.

警告

基於安全性理由, 建議您呼叫具有throwOnInvalidBytes參數的函式, 並將其值設定為true, 以啟用錯誤偵測。For security reasons, we recommend that you enable error detection by calling a constructor with a throwOnInvalidBytes parameter and setting its value to true.

另請參閱

UTF8Encoding(Boolean) UTF8Encoding(Boolean) UTF8Encoding(Boolean) UTF8Encoding(Boolean)

初始化 UTF8Encoding 類別的新執行個體。Initializes a new instance of the UTF8Encoding class. 參數會指定是否提供 Unicode 位元組順序標記。A parameter specifies whether to provide a Unicode byte order mark.

public:
 UTF8Encoding(bool encoderShouldEmitUTF8Identifier);
public UTF8Encoding (bool encoderShouldEmitUTF8Identifier);
new System.Text.UTF8Encoding : bool -> System.Text.UTF8Encoding
Public Sub New (encoderShouldEmitUTF8Identifier As Boolean)

參數

encoderShouldEmitUTF8Identifier
Boolean Boolean Boolean Boolean

true 指定 GetPreamble() 方法會傳回 Unicode 位元組順序標記;否則為 falsetrue to specify that the GetPreamble() method returns a Unicode byte order mark; otherwise, false.

範例

下列範例會建立新UTF8Encoding的實例, 並指定 Unicode 位元組順序標記前置詞應GetPreamble由方法發出。The following example creates a new UTF8Encoding instance and specifies that a Unicode byte order mark prefix should be emitted by the GetPreamble method. 然後GetPreamble , 方法會傳回 Unicode 位元組順序標記前置詞。The GetPreamble method then returns the Unicode byte order mark prefix.

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

備註

當偵測到不正確編碼方式時, 此函式會建立不會擲回例外狀況的實例。This constructor creates an instance that does not throw an exception when an invalid encoding is detected.

警告

基於安全性理由, 您應該呼叫包含throwOnInvalidBytes參數的函式, 並將其值設定為true, 以啟用錯誤偵測。For security reasons, you should enable error detection by calling a constructor that includes a throwOnInvalidBytes parameter and setting its value to true.

參數會控制GetPreamble方法的作業。 encoderShouldEmitUTF8IdentifierThe encoderShouldEmitUTF8Identifier parameter controls the operation of the GetPreamble method. 如果true為, 則方法會傳回包含 utf-8 格式之 Unicode 位元組順序標記 (BOM) 的位元組陣列。If true, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. 如果false為, 則會傳回長度為零的位元組陣列。If false, it returns a zero-length byte array. 不過, 將encoderShouldEmitUTF8Identifier設定true為並不會GetBytes使方法在GetByteCount位元組陣列的開頭加上 bom 的前置詞, 也不會導致方法以位元組計數包含 bom 中的位元組數目。However, setting encoderShouldEmitUTF8Identifier to true does not cause the GetBytes method to prefix the BOM at the beginning of the byte array, nor does it cause the GetByteCount method to include the number of bytes in the BOM in the byte count.

另請參閱

UTF8Encoding(Boolean, Boolean) UTF8Encoding(Boolean, Boolean) UTF8Encoding(Boolean, Boolean) UTF8Encoding(Boolean, Boolean)

初始化 UTF8Encoding 類別的新執行個體。Initializes a new instance of the UTF8Encoding class. 參數會指定是否提供 Unicode 位元組順序標記,以及是否在偵測到無效的編碼方式時擲回例外狀況。Parameters specify whether to provide a Unicode byte order mark and whether to throw an exception when an invalid encoding is detected.

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 Boolean Boolean Boolean

true 指定 GetPreamble() 方法應傳回 Unicode 位元組順序標記;否則為 falsetrue to specify that the GetPreamble() method should return a Unicode byte order mark; otherwise, false.

throwOnInvalidBytes
Boolean Boolean Boolean Boolean

true 表示在偵測到無效的編碼方式時擲回例外狀況;否則為 falsetrue to throw an exception when an invalid encoding is detected; otherwise, false.

範例

下列範例會建立新UTF8Encoding的實例, 指定GetPreamble方法不應發出 Unicode 位元組順序標記前置詞, 而且當偵測到不正確編碼方式時, 應該擲回例外狀況。The following example creates a new UTF8Encoding instance, specifying that the GetPreamble method should not emit a Unicode byte order mark prefix, and an exception should be thrown when an invalid encoding is detected. 此函式的行為會與預設UTF8Encoding()的「檢查程式」進行比較, 當偵測到不正確編碼方式時, 不會擲回例外狀況。The behavior of this constructor is compared to the default UTF8Encoding() constructor, which does not throw an exception when an invalid encoding is detected. 這兩UTF8Encoding個實例會將包含兩個高代理 (U + D801 和 U + D802) 的字元陣列編碼在資料列中, 這是不正確字元序列; 高代理方後面應該一律加上低代理。The two UTF8Encoding instances encode a character array that contains two high surrogates (U+D801 and U+D802) in a row, which is an invalid character sequence; a high surrogate should always be followed by a low 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.

備註

參數會控制GetPreamble方法的作業。 encoderShouldEmitUTF8IdentifierThe encoderShouldEmitUTF8Identifier parameter controls the operation of the GetPreamble method. 如果true為, 則方法會傳回包含 utf-8 格式之 Unicode 位元組順序標記 (BOM) 的位元組陣列。If true, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. 如果false為, 則會傳回長度為零的位元組陣列。If false, it returns a zero-length byte array. 不過, 將encoderShouldEmitUTF8Identifier設定true為並不會GetBytes使方法在GetByteCount位元組陣列的開頭加上 bom 的前置詞, 也不會導致方法以位元組計數包含 bom 中的位元組數目。However, setting encoderShouldEmitUTF8Identifier to true does not cause the GetBytes method to prefix the BOM at the beginning of the byte array, nor does it cause the GetByteCount method to include the number of bytes in the BOM in the byte count.

如果throwOnInvalidBytestrue, 則偵測到System.ArgumentException無效位元組序列的方法會擲回例外狀況。If throwOnInvalidBytes is true, a method that detects an invalid byte sequence throws an System.ArgumentException exception. 否則, 方法不會擲回例外狀況, 而且會忽略不正確序列。Otherwise, the method does not throw an exception, and the invalid sequence is ignored.

警告

基於安全性理由, 您應該藉由呼叫包含throwOnInvalidBytes參數的函式, 並將該參數設定為true, 來啟用錯誤偵測。For security reasons, you should enable error detection by calling a constructor that includes a throwOnInvalidBytes parameter and setting that parameter to true.

另請參閱

適用於