System.Convert 類別

發行項
01/08/2024

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

靜態 Convert 類別包含的方法，主要用來支援在 .NET 中轉換基底數據類型。支援的基底類型為 Boolean、、、Byte SByte、Int16、Int32、、Int64、UInt64 UInt32 UInt16 Single、 Decimal DateTime Double和。String Char 此外，類別 Convert 也包含支援其他類型的轉換的方法。

從基底型別來回轉換

轉換方法存在，可將每個基底類型轉換成所有其他基底類型。不過，特定轉換方法的實際呼叫可能會產生五個結果中的一個，視運行時間基底型別的值和目標基底類型而定。這五個結果如下：

沒有轉換。當嘗試從型別轉換成本身時，就會發生這種情況（例如，藉由使用類型的Int32自變數呼叫 Convert.ToInt32(Int32) ）。在此情況下，方法只會傳回原始類型的實例。
InvalidCastException。當不支援特定轉換時，就會發生這種情況。 InvalidCastException會針對下列轉換擲回。
- 轉換 Char 為、、Single、 Double Decimal或 DateTime。 Boolean
- 從 Boolean、Single、、 Double Decimal或 DateTime 轉換成 Char。
- 從 DateTime 轉換成任何其他類型，但除外 String。
- 從任何其他型別轉換，但除外 String，轉換為 DateTime。
FormatException。當嘗試將字串值轉換成任何其他基底類型失敗時，就會發生這種情況，因為字串的格式不正確。下列轉換會擲回例外狀況：
- 要轉換成 Boolean 值的字串不等於 Boolean.TrueString 或 Boolean.FalseString。
- 要轉換成 Char 值的字串包含多個字元。
- 要轉換成任何數值類型的字串無法辨識為有效的數位。
- 要轉換成的 DateTime 字串無法辨識為有效的日期和時間值。
成功轉換。針對先前結果中未列出的兩個不同基底類型之間的轉換，所有擴大轉換，以及不會導致數據遺失的所有縮小轉換都會成功，而且方法會傳回目標基底類型的值。
OverflowException。當縮小轉換導致數據遺失時，就會發生這種情況。例如，嘗試將值為10000 Byte 的實例轉換成Int32類型會OverflowException擲回，因為10000超出數據類型的範圍Byte。

如果數值類型的轉換導致有效位數遺失，則不會擲回例外狀況（也就是遺失一些最小有效位數）。不過，如果結果大於特定轉換方法的傳回值類型，則會擲回例外狀況。

例如，當轉換成 Single時Double，可能會遺失精確度，但不會擲回例外狀況。不過，如果的大小 Double 太大而無法以 Single表示，則會擲回溢位例外狀況。

非十進位數

類別 Convert 包含靜態方法，您可以呼叫以將整數值轉換成非十進位字元串表示法，以及將代表非十進位數的字串轉換成整數值。每個轉換方法都包含一個 base 自變數，可讓您指定數字系統;二進位（基底 2）、八進位（基底 8）和十六進位（基底 16），以及十進位（基底 10）。有一組方法可將每個符合CLS規範的基本整數型別轉換成字元串，一個將字串轉換成每個基本整數類型：

ToString(Byte, Int32) 和 ToByte(String, Int32)，將位元組值轉換成指定基底中的字串，以及從字串轉換。
ToString(Int16, Int32) 和 ToInt16(String, Int32)，將16位帶正負號的整數轉換成指定基底中的字串和字串。
ToString(Int32, Int32) 和 ToInt32(String, Int32)，將32位帶正負號的整數轉換成指定基底中的字串和字串。
ToString(Int64, Int32) 和 ToInt64(String, Int32)，將64位帶正負號的整數轉換成指定基底中的字串和字串。
ToSByte(String, Int32)，將指定格式之位元組值的字串表示轉換成帶正負號的位元組。
ToUInt16(String, Int32)，將指定格式之整數的字串表示轉換成不帶正負號的16位整數。
ToUInt32(String, Int32)，將指定格式之整數的字串表示轉換為不帶正負號的 32 位整數。
ToUInt64(String, Int32)，將指定格式之整數的字串表示轉換為不帶正負號的64位整數。

下列範例會將的值 Int16.MaxValue 轉換成所有支持數值格式的字串。然後，它會將字串值轉換回 Int16 值。

using System;

public class Example
{
   public static void Main()
   {
      int[] baseValues = { 2, 8, 10, 16 };
      short value = Int16.MaxValue;
      foreach (var baseValue in baseValues) {
         String s = Convert.ToString(value, baseValue);
         short value2 = Convert.ToInt16(s, baseValue);

         Console.WriteLine("{0} --> {1} (base {2}) --> {3}",
                           value, s, baseValue, value2);
      }
   }
}
// The example displays the following output:
//     32767 --> 111111111111111 (base 2) --> 32767
//     32767 --> 77777 (base 8) --> 32767
//     32767 --> 32767 (base 10) --> 32767
//     32767 --> 7fff (base 16) --> 32767

open System

let baseValues = [ 2; 8; 10; 16 ]
let value = Int16.MaxValue
for baseValue in baseValues do
    let s = Convert.ToString(value, baseValue)
    let value2 = Convert.ToInt16(s, baseValue)
    printfn $"{value} --> {s} (base {baseValue}) --> {value2}"

// The example displays the following output:
//     32767 --> 111111111111111 (base 2) --> 32767
//     32767 --> 77777 (base 8) --> 32767
//     32767 --> 32767 (base 10) --> 32767
//     32767 --> 7fff (base 16) --> 32767

Module Example2
    Public Sub Main()
        Dim baseValues() As Integer = {2, 8, 10, 16}
        Dim value As Short = Int16.MaxValue
        For Each baseValue In baseValues
            Dim s As String = Convert.ToString(value, baseValue)
            Dim value2 As Short = Convert.ToInt16(s, baseValue)

            Console.WriteLine("{0} --> {1} (base {2}) --> {3}",
                           value, s, baseValue, value2)
        Next
    End Sub
End Module
' The example displays the following output:
'     32767 --> 111111111111111 (base 2) --> 32767
'     32767 --> 77777 (base 8) --> 32767
'     32767 --> 32767 (base 10) --> 32767
'     32767 --> 7fff (base 16) --> 32767

從自定義物件轉換成基底類型

除了支援基底類型之間的轉換之外， Convert 方法還支援將任何自定義類型轉換成任何基底類型。若要這樣做，自定義類型必須實 IConvertible 作介面，這個介面會定義將實作型別轉換成每個基底型別的方法。特定型別不支援的轉換應該會擲回 InvalidCastException。

ChangeType當方法傳遞自定義類型做為其第一個參數時，或當Convert.To Type 方法（例如 Convert.ToInt32(Object) 或 Convert.ToDouble(Object, IFormatProvider) 被呼叫，並傳遞自定義類型的實例做為其第一個參數時，Convert方法接著會呼叫自定義類型的IConvertible實作來執行轉換。如需詳細資訊，請參閱 .NET 中的類型轉換。

特定文化特性的格式資訊

所有基底類型轉換方法和 ChangeType 方法都包含具有類型 IFormatProvider參數的多載。例如， Convert.ToBoolean 方法有下列兩個多載：

參數 IFormatProvider 可以提供特定文化特性的格式資訊，以協助轉換程式。不過，大部分基底類型轉換方法都會忽略它。它只能由下列基底類型轉換方法使用。如果自nullIFormatProvider變數傳遞至這些方法，CultureInfo則會使用代表目前文化特性的物件。

透過將值轉換成數值型別的方法。具有 IFormatProvider 型 String 別和 IFormatProvider的參數的多載會使用參數。多載也會使用具有型 Object 別參數的多載，如果 IFormatProvider 對象的運行時間類型是，則為 String。
透過將值轉換成日期和時間的方法。具有 IFormatProvider 型 String 別和 IFormatProvider的參數的多載會使用參數。多載也會使用具有型 Object 別參數的多載，如果 IFormatProvider 對象的運行時間類型是，則為 String。
Convert.ToString由包含參數的多載，IFormatProvider以及將數值轉換成字串或DateTime將值轉換成字串的多載。

不過，任何實 IConvertible 作的使用者定義型別都可以使用 IFormatProvider 參數。

Base64 編碼

Base64 編碼會將二進位數據轉換成字串。透過只能傳輸 7 位字元的數據通道，可以輕鬆地透過以base-64位數表示的數據。類別 Convert 包含下列支援base64編碼的方法：一組方法支援將位元組數位轉換成 String 或來回轉換 Unicode 字元數組，其中包含base-64數位字元。

ToBase64String，可將位元組陣列轉換成base64編碼的字串。
ToBase64CharArray，可將位元組陣列轉換成base64編碼的字元陣列。
FromBase64String，可將base64編碼的字串轉換成位元組陣列。
FromBase64CharArray，可將base64編碼的字元陣列轉換成位元組陣列。

其他常見的轉換

您可以使用其他 .NET 類別來執行類別靜態方法不支援的某些 Convert 轉換。包括：

轉換成位元組陣組

類別 BitConverter 提供方法，可將基本數值類型（包括 Boolean）轉換成位元組陣列，以及從位元組數位轉換回基本數據類型。
字元編碼和譯碼

類別 Encoding 及其衍生類別（例如 UnicodeEncoding 和 UTF8Encoding）提供方法來編碼字元陣列或字串（也就是說，將它們轉換成特定編碼中的位元組數位），以及譯碼編碼位元組陣列（也就是將位元組陣列轉換成 UTF16 編碼的 Unicode 字元）。如需詳細資訊，請參閱 .NET 中的字元編碼。

範例

下列範例示範類別中的 Convert 一些轉換方法，包括 ToInt32、 ToBoolean和 ToString。

double dNumber = 23.15;

try {
    // Returns 23
    int    iNumber = System.Convert.ToInt32(dNumber);
}
catch (System.OverflowException) {
    System.Console.WriteLine(
                "Overflow in double to int conversion.");
}
// Returns True
bool   bNumber = System.Convert.ToBoolean(dNumber);

// Returns "23.15"
string strNumber = System.Convert.ToString(dNumber);

try {
    // Returns '2'
    char chrNumber = System.Convert.ToChar(strNumber[0]);
}
catch (System.ArgumentNullException) {
    System.Console.WriteLine("String is null");
}
catch (System.FormatException) {
    System.Console.WriteLine("String length is greater than 1.");
}

// System.Console.ReadLine() returns a string and it
// must be converted.
int newInteger = 0;
try {
    System.Console.WriteLine("Enter an integer:");
    newInteger = System.Convert.ToInt32(
                        System.Console.ReadLine());
}
catch (System.ArgumentNullException) {
    System.Console.WriteLine("String is null.");
}
catch (System.FormatException) {
    System.Console.WriteLine("String does not consist of an " +
                    "optional sign followed by a series of digits.");
}
catch (System.OverflowException) {
    System.Console.WriteLine(
    "Overflow in string to int conversion.");
}

System.Console.WriteLine("Your integer as a double is {0}",
                         System.Convert.ToDouble(newInteger));

let dNumber = 23.15

try
    // Returns 23
    Convert.ToInt32 dNumber
    |> ignore
with :? OverflowException ->
    printfn "Overflow in double to int conversion."
// Returns True
let bNumber = System.Convert.ToBoolean dNumber

// Returns "23.15"
let strNumber = System.Convert.ToString dNumber

try
    // Returns '2'
    System.Convert.ToChar strNumber[0]
    |> ignore
with
| :? ArgumentNullException ->
    printfn "String is null"
| :? FormatException ->
    printfn "String length is greater than 1."

// System.Console.ReadLine() returns a string and it
// must be converted.
let newInteger =
    try
        printfn "Enter an integer:"
        System.Convert.ToInt32(Console.ReadLine())
    with
    | :? ArgumentNullException ->
        printfn "String is null."
        0
    | :? FormatException ->
        printfn "String does not consist of an optional sign followed by a series of digits."
        0
    | :? OverflowException ->
        printfn "Overflow in string to int conversion."
        0

printfn $"Your integer as a double is {System.Convert.ToDouble newInteger}"

Dim dNumber As Double
dNumber = 23.15

Try
   ' Returns 23
   Dim iNumber As Integer
   iNumber = System.Convert.ToInt32(dNumber)
Catch exp As System.OverflowException
   System.Console.WriteLine("Overflow in double to int conversion.")
End Try

' Returns True
Dim bNumber As Boolean
bNumber = System.Convert.ToBoolean(dNumber)

' Returns "23.15"
Dim strNumber As String
strNumber = System.Convert.ToString(dNumber)

Try
   ' Returns '2'
   Dim chrNumber As Char
   chrNumber = System.Convert.ToChar(strNumber.Chars(1))
Catch exp As System.ArgumentNullException
   System.Console.WriteLine("String is null.")
Catch exp As System.FormatException
   System.Console.WriteLine("String length is greater than 1.")
End Try

' System.Console.ReadLine() returns a string and it
' must be converted.
Dim newInteger As Integer
newInteger = 0
Try
   System.Console.WriteLine("Enter an integer:")
   newInteger = System.Convert.ToInt32(System.Console.ReadLine())
Catch exp As System.ArgumentNullException
   System.Console.WriteLine("String is null.")
Catch exp As System.FormatException
   System.Console.WriteLine("String does not consist of an " + _
       "optional sign followed by a series of digits.")
Catch exp As System.OverflowException
   System.Console.WriteLine("Overflow in string to int conversion.")
End Try

System.Console.WriteLine("Your integer as a double is {0}", _
                         System.Convert.ToDouble(newInteger))

共用方式為