Compartilhar via


Type Conversion in the .NET Framework for Silverlight

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Every value has an associated type, which defines attributes such as the amount of space allocated to the value, the range of possible values it can have, and the members that it makes available. Many values can be expressed as more than one type. For example, the value 4 can be expressed as an integer or a floating-point value. Type conversion creates a value in a new type that is equivalent to the value of an old type, but does not necessarily preserve the identity (or exact value) of the original object.

The .NET Framework provides several features that support type conversion. These include the following:

  • The Implicit operator, which defines the available widening conversions between types.

  • The Explicit operator, which defines the available narrowing conversions between types.

  • The IConvertible interface, which defines conversions to each of the base .NET Framework data types.

  • The Convert class, which provides a set of methods that implement the methods in the IConvertible interface.

  • The TypeConverter class, which is a base class that can be extended to support the conversion of a specified type to any other type.

Implicit Conversion with the Implicit Operator

Widening conversions involve the creation of a new value from the value of an existing type that has either a more restrictive range or a more restricted member list than the target type. Because a widening conversion cannot result in data loss, compilers can handle the conversion implicitly or transparently, without requiring the use of an explicit conversion method or a casting operator.

NoteNote:

Although code that performs an explicit conversion can call a conversion method or use a casting operator, their use is not required by compilers that support implicit conversions.

For example, the Decimal type supports implicit conversions from Byte, Char, Int16, Int32, Int64, SByte, UInt16, UInt32, and UInt64 values. The following example illustrates some of these implicit conversions in assigning values to a Decimal variable.

Dim byteValue As Byte = 16
Dim shortValue As Short = -1024
Dim intValue As Integer = -1034000
Dim longValue As Long = CLng(1024^6)

Dim decimalValue As Decimal

decimalValue = byteValue
outputBlock.Text &= String.Format("After assigning a {0} value, the Decimal value is {1}.", _
                    byteValue.GetType().Name, decimalValue) & vbCrLf

decimalValue = shortValue
outputBlock.Text &= String.Format("After assigning a {0} value, the Decimal value is {1}.", _
                    shortValue.GetType().Name, decimalValue) & vbCrLf

decimalValue = intValue
outputBlock.Text &= String.Format("After assigning a {0} value, the Decimal value is {1}.", _
                    intValue.GetType().Name, decimalValue) & vbCrLf

decimalValue = longValue
outputBlock.Text &= String.Format("After assigning a {0} value, the Decimal value is {1}.", _
                    longValue.GetType().Name, decimalValue) & vbCrLf
' The example displays the following output:
'       After assigning a Byte value, the Decimal value is 16.
'       After assigning a Int16 value, the Decimal value is -1024.
'       After assigning a Int32 value, the Decimal value is -1034000.
'       After assigning a Int64 value, the Decimal value is 1152921504606946976.
byte byteValue = 16;
short shortValue = -1024;
int intValue = -1034000;
long longValue = 1152921504606846976;

decimal decimalValue;

decimalValue = byteValue;
outputBlock.Text += String.Format("After assigning a {0} value, the Decimal value is {1}.\n", 
                    byteValue.GetType().Name, decimalValue); 

decimalValue = shortValue;
outputBlock.Text += String.Format("After assigning a {0} value, the Decimal value is {1}.\n", 
                    shortValue.GetType().Name, decimalValue); 

decimalValue = intValue;
outputBlock.Text += String.Format("After assigning a {0} value, the Decimal value is {1}.\n", 
                    intValue.GetType().Name, decimalValue); 

decimalValue = longValue;
outputBlock.Text += String.Format("After assigning a {0} value, the Decimal value is {1}.\n", 
                    longValue.GetType().Name, decimalValue); 
// The example displays the following output:
//       After assigning a Byte value, the Decimal value is 16.
//       After assigning a Int16 value, the Decimal value is -1024.
//       After assigning a Int32 value, the Decimal value is -1034000.
//       After assigning a Int64 value, the Decimal value is 1152921504606946976.

If a particular language compiler supports custom overloaded operators, you can also define implicit conversions in your own custom types. The following example provides a partial implementation of a signed byte data type named ByteWithSign that uses sign-and-magnitude representation. It supports implicit conversion of Byte and SByte values to ByteWithSign values.

Public Structure ByteWithSign
   Private signValue As SByte 
   Private value As Byte

   Public Overloads Shared Widening Operator CType(value As SByte) As ByteWithSign
      Dim newValue As ByteWithSign
      newValue.signValue = CSByte(Math.Sign(value))
      newValue.value = CByte(Math.Abs(value))
      Return newValue
   End Operator  

   Public Overloads Shared Widening Operator CType(value As Byte) As ByteWithSign
      Dim NewValue As ByteWithSign
      newValue.signValue = 1
      newValue.value = value
      Return newValue
   End Operator

   Public Overrides Function ToString() As String 
      Return (signValue * value).ToString()
   End Function
End Structure
public struct ByteWithSign
{
   private SByte signValue; 
   private Byte value;

   public static implicit operator ByteWithSign(SByte value) 
   {
      ByteWithSign newValue;
      newValue.signValue = (SByte) Math.Sign(value);
      newValue.value = (byte) Math.Abs(value);
      return newValue;
   }  

   public static implicit operator ByteWithSign(Byte value)
   {
      ByteWithSign  newValue;
      newValue.signValue = 1;
      newValue.value = value;
      return newValue;
   }

   public override string ToString()
   { 
      return (signValue * value).ToString();
   }
}

Client code can then declare a ByteWithSign variable and assign it Byte and SByte values without performing any explicit conversions or using any casting operators, as the following example shows.

Module Example
   Public Sub Demo(outputBlock As System.Windows.Controls.TextBlock)
      Dim sbyteValue As SByte = -120
      Dim value As ByteWithSign = sbyteValue
      outputBlock.Text &= value.ToString() & vbCrLf 
      value = Byte.MaxValue
      outputBlock.Text &= value.ToString() & vbCrLf 
   End Sub
End Module
' The example displays the following output:
'       -120
'       255
public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      SByte sbyteValue = -120;
      ByteWithSign value = sbyteValue;
      outputBlock.Text += value + "\n";
      value = Byte.MaxValue;
      outputBlock.Text += value + "\n";
   }
}
// The example displays the following output:
//       -120
//       255

Explicit Conversion with the Explicit Operator

Narrowing conversions involve the creation of a new value from the value of an existing type that has either a greater range or a larger member list than the target type. Because a narrowing conversion can result in a loss of data, compilers often require that the conversion be made explicit through a call to a conversion method or a casting operator. That is, the conversion must be handled explicitly in developer code.

NoteNote:

The major purpose of requiring a conversion method or casting operator for narrowing conversions is to make the developer aware of the possibility of data loss or an OverflowException so that it can be handled in code. Some compilers can relax this requirement, however. For example, in Visual Basic, if Option Strict is off (its default setting), the Visual Basic compiler tries to perform narrowing conversions implicitly.

For example, the UInt32, Int64, and UInt64 data types all have ranges that exceed that the Int32 data type, as the following table shows.

Type

Comparison with range of Int32

Int64

Int64.MaxValue is greater than Int32.MaxValue, and Int64.MinValue is less than (has a greater negative range than) Int32.MinValue.

UInt32

UInt32.MaxValue is greater than Int32.MaxValue.

UInt64

UInt64.MaxValue is greater than Int32.MaxValue.

To handle such narrowing conversions, the .NET Framework allows types to define an Explicit operator. Individual language compilers can then implement this operator using their own syntax. The following example illustrates the use of language features to handle the explicit conversion of these potentially out-of-range integer values to Int32 values.

Dim number1 As Long = Integer.MaxValue + 20L
Dim number2 As UInteger = Integer.MaxValue - 1000
Dim number3 As ULong = Integer.MaxValue

Dim intNumber As Integer

Try
   intNumber = CInt(number1)
   outputBlock.Text &= String.Format("After assigning a {0} value, the Integer value is {1}.", _ 
                       number1.GetType().Name, intNumber) & vbCrLf
Catch e As OverflowException
   If number1 > Integer.MaxValue Then
      outputBlock.Text &= String.Format("Conversion failed: {0} exceeds {1}.", _ 
                                        number1, Integer.MaxValue) & vbCrLf
   Else
      outputBlock.Text &= String.Format("Conversion failed: {0} is less than {1}.\n", _ 
                                        number1, Integer.MinValue) & vbCrLf
   End If
End Try

Try
   intNumber = CInt(number2)
   outputBlock.Text &= String.Format("After assigning a {0} value, the Integer value is {1}.", _ 
                       number2.GetType().Name, intNumber) & vbCrLf
Catch e As OverflowException
   outputBlock.Text &= String.Format("Conversion failed: {0} exceeds {1}.", _ 
                                     number2, Integer.MaxValue) & vbCrLf
End Try

Try
   intNumber = CInt(number3)
   outputBlock.Text &= String.Format("After assigning a {0} value, the Integer value is {1}.", _ 
                       number3.GetType().Name, intNumber) & vbCrLf
Catch e As OverflowException
   outputBlock.Text &= String.Format("Conversion failed: {0} exceeds {1}.", _
                                     number1, Integer.MaxValue) & vbCrLf
End Try
' The example displays the following output:
'    Conversion failed: 2147483667 exceeds 2147483647.
'    After assigning a UInt32 value, the Integer value is 2147482647.
'    After assigning a UInt64 value, the Integer value is 2147483647.
long number1 = int.MaxValue + 20L;
uint number2 = int.MaxValue - 1000;
ulong number3 = int.MaxValue;

int intNumber;

try {
   intNumber = checked((int) number1);
   outputBlock.Text += String.Format("After assigning a {0} value, the Integer value is {1}.\n", 
                       number1.GetType().Name, intNumber); 
}
catch (OverflowException) {
   if (number1 > int.MaxValue)
      outputBlock.Text += String.Format("Conversion failed: {0} exceeds {1}.\n", 
                                        number1, int.MaxValue);
   else
      outputBlock.Text += String.Format("Conversion failed: {0} is less than {1}.\n", 
                                        number1, int.MinValue);
}

try {
   intNumber = checked((int) number2);
   outputBlock.Text += String.Format("After assigning a {0} value, the Integer value is {1}.\n", 
                       number2.GetType().Name, intNumber); 
}
catch (OverflowException) {
   outputBlock.Text += String.Format("Conversion failed: {0} exceeds {1}.\n", 
                                     number2, int.MaxValue);
}

try {
   intNumber = checked((int) number3);
   outputBlock.Text += String.Format("After assigning a {0} value, the Integer value is {1}.\n", 
                       number3.GetType().Name, intNumber); 
}
catch (OverflowException) {
   outputBlock.Text += String.Format("Conversion failed: {0} exceeds {1}.\n", 
                                     number1, int.MaxValue);
}

// The example displays the following output:
//    Conversion failed: 2147483667 exceeds 2147483647.
//    After assigning a UInt32 value, the Integer value is 2147482647.
//    After assigning a UInt64 value, the Integer value is 2147483647.

If a particular language compiler supports custom overloaded operators, you can also define explicit conversions in your own custom types. The following example provides a partial implementation of a signed byte data type named ByteWithSign that uses sign-and-magnitude representation. It supports explicit conversion of Int32 and UInt32 values to ByteWithSign values.

Public Structure ByteWithSign
   Private signValue As SByte 
   Private value As Byte

   Private Const MaxValue As Byte = Byte.MaxValue
   Private Const MinValue As Integer = -1 * Byte.MaxValue

   Public Overloads Shared Narrowing Operator CType(value As Integer) As ByteWithSign
      ' Check for overflow.
      If value > ByteWithSign.MaxValue Or value < ByteWithSign.MinValue Then
         Throw New OverflowException(String.Format("'{0}' is out of range of the ByteWithSign data type.", value))
      End If

      Dim newValue As ByteWithSign

      newValue.signValue = CSByte(Math.Sign(value))
      newValue.value = CByte(Math.Abs(value))
      Return newValue
   End Operator

   Public Overloads Shared Narrowing Operator CType(value As UInteger) As ByteWithSign
      If value > ByteWithSign.MaxValue Then 
         Throw New OverflowException(String.Format("'{0}' is out of range of the ByteWithSign data type.", value))
      End If

      Dim NewValue As ByteWithSign

      newValue.signValue = 1
      newValue.value = CByte(value)
      Return newValue
   End Operator

   Public Overrides Function ToString() As String 
      Return (signValue * value).ToString()
   End Function
End Structure
public struct ByteWithSign
{
   private SByte signValue; 
   private Byte value;

   private const byte MaxValue = byte.MaxValue;
   private const int MinValue = -1 * byte.MaxValue;

   public static explicit operator ByteWithSign(int value) 
   {
      // Check for overflow.
      if (value > ByteWithSign.MaxValue || value < ByteWithSign.MinValue)
         throw new OverflowException(String.Format("'{0}' is out of range of the ByteWithSign data type.", 
                                                   value));

      ByteWithSign newValue;
      newValue.signValue = (SByte) Math.Sign(value);
      newValue.value = (byte) Math.Abs(value);
      return newValue;
   }  

   public static explicit operator ByteWithSign(uint value)
   {
      if (value > ByteWithSign.MaxValue) 
         throw new OverflowException(String.Format("'{0}' is out of range of the ByteWithSign data type.", 
                                                   value));

      ByteWithSign newValue;
      newValue.signValue = 1;
      newValue.value = (byte) value;
      return newValue;
   }

   public override string ToString()
   { 
      return (signValue * value).ToString();
   }
}

Client code can then declare a ByteWithSign variable and assign it Int32 and UInt32 values if the assignments includes a casting operator or a conversion method, as the following example shows.

Module Example
   Public Sub Demo(outputBlock As System.Windows.Controls.TextBlock)
      Dim value As ByteWithSign

      Try  
         Dim intValue As Integer = -120
         value = CType(intValue, ByteWithSign)
         outputBlock.Text &= value.ToString() & vbCrLf 
      Catch e As OverflowException
         outputBlock.Text &= e.Message & vbCrLf
      End Try

      Try
         Dim uintValue As UInteger = 1024
         value = CType(uintValue, ByteWithSign)
         outputBlock.Text &= value.ToString() & vbCrLf 
      Catch e As OverflowException
         outputBlock.Text &= e.Message & vbCrLf
      End Try
   End Sub
End Module
' The example displays the following output:
'       -120
'       '1024' is out of range of the ByteWithSign data type.
public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      ByteWithSign value;

      try {
         int intValue = -120;
         value = (ByteWithSign) intValue;
         outputBlock.Text += value + "\n";
      }
      catch (OverflowException e) {
         outputBlock.Text += e.Message + "\n";
      }

      try {
         uint uintValue = 1024;
         value = (ByteWithSign) uintValue;
         outputBlock.Text += value + "\n";
      }
      catch (OverflowException e) {
          outputBlock.Text += e.Message + "\n";
      }
   }
}
// The example displays the following output:
//       -120
//       '1024' is out of range of the ByteWithSign data type.

The IConvertible Interface

To support the conversion of any type to a common language runtime base type, the .NET Framework provides the IConvertible interface. The implementing type is required to provide the following:

  • A method that returns the TypeCode of the implementing type.

  • Methods to convert the implementing type to each of the common language runtime base types (Boolean, Byte, DateTime, Decimal, Double, and so on).

  • A generalized conversion method to convert an instance of the implementing type to another specified type. Conversions that are not supported should throw an InvalidCastException.

Each of the common language runtime base types (that is, the Boolean, Byte, Char, DateTime, Decimal, Double, Int16, Int32, Int64, SByte, Single, String, UInt16, UInt32, and UInt64), as well as the DBNull and Enum types, implement the IConvertible interface. However, these are explicit interface implementations; the conversion method can be called only through an IConvertible interface variable, as the following code shows. This code converts an Int32 value to its equivalent Char value.

Dim codePoint As Integer = 1067
Dim iConv As IConvertible = codePoint
Dim ch As Char = iConv.ToChar(Nothing)
outputBlock.Text += String.Format("Converted {0} to {1}.", codePoint, ch)
int codePoint = 1067;
IConvertible iConv = codePoint;
char ch = iConv.ToChar(null);
outputBlock.Text += String.Format("Converted {0} to {1}.", codePoint, ch);

The requirement that the conversion method be called on its interface rather than on the implementing type makes explicit interface implementations relatively expensive. Instead, the recommended method of converting between common language runtime base types is to call the appropriate member of the Convert class. For details, see The Convert Class.

NoteNote:

In addition to the IConvertible interface and the Convert class provided by the .NET Framework, individual languages may also provide ways to perform conversions. For example, C# uses casting operators; Visual Basic uses compiler-implemented conversion functions such as CType, CInt, and DirectCast.

For the most part, the IConvertible interface is designed to support conversion between the base types in the .NET Framework. However, the interface can also be implemented by a custom type to support conversion of that type to other custom types. For details, see Custom Conversions with the ChangeType Method.

The Convert Class

Although each base type's IConvertible interface implementation can be called to perform a type conversion, calling the methods of the Convert class is the recommended language-neutral way to convert from one base type to another. In addition, the Convert.ChangeType(Object, Type, IFormatProvider) method can be used to convert from a specified custom type to another type.

Conversions Between Base Types

The System.Convert class provides a language-neutral way to perform conversions between base types and is available to all languages that target the common language runtime. It supports both widening and narrowing conversions, and throws an InvalidCastException for conversions that are not supported (such as the conversion of a DateTime value to an integer value). Narrowing conversions are performed in a checked context and an OverflowException is thrown if the conversion fails.

Important noteImportant Note:

Because the Convert class includes methods to convert to and from each base type, it eliminates the need to call each base type's IConvertible explicit interface implementation.

The following example illustrates the use of the System.Convert class to perform several widening and narrowing conversions between .NET Framework base types.

' Convert an Int32 value to a Decimal (a widening conversion).
Dim integralValue As Integer = 12534
Dim decimalValue As Decimal = Convert.ToDecimal(integralValue)
outputBlock.Text += String.Format("Converted the {0} value {1} to " + _ 
                                  "the {2} value {3:N2}.", _
                                  integralValue.GetType().Name, _
                                  integralValue, _
                                  decimalValue.GetType().Name, _
                                  decimalValue) + vbCrLf
' Convert a Byte value to an Int32 value (a widening conversion).
Dim byteValue As Byte = Byte.MaxValue
Dim integralValue2 As Integer = Convert.ToInt32(byteValue)                                  
outputBlock.Text += String.Format("Converted the {0} value {1} to " + _ 
                                  "the {2} value {3:G}.", _
                                  byteValue.GetType().Name, _
                                  byteValue, _
                                  integralValue2.GetType().Name, _
                                  integralValue2) + vbCrLf

' Convert a Double value to an Int32 value (a narrowing conversion).
Dim doubleValue As Double = 16.32513e12
Try
   Dim longValue As Long = Convert.ToInt64(doubleValue)
   outputBlock.Text += String.Format("Converted the {0} value {1:E} to " + _ 
                                     "the {2} value {3:N0}.", _
                                     doubleValue.GetType().Name, _
                                     doubleValue, _
                                     longValue.GetType().Name, _
                                     longValue) + vbCrLf
Catch e As OverflowException
   outputBlock.Text += String.Format("Unable to convert the {0:E} value {1}.", _
                                     doubleValue.GetType().Name, doubleValue) + vbCrLf
End Try                                                             

' Convert a signed byte to a byte (a narrowing conversion).     
Dim sbyteValue As SByte = -16
Try
   Dim byteValue2 As Byte = Convert.ToByte(sbyteValue)
   outputBlock.Text += String.Format("Converted the {0} value {1} to " + _ 
                                     "the {2} value {3:G}.", _
                                     sbyteValue.GetType().Name, _
                                     sbyteValue, _
                                     byteValue2.GetType().Name, _
                                     byteValue2) + vbCrLf
Catch e As OverflowException
   outputBlock.Text += String.Format("Unable to convert the {0} value {1}.", _
                                     sbyteValue.GetType().Name, sbyteValue) + vbCrLf
End Try 
' The example displays the following output:
'       Converted the Int32 value 12534 to the Decimal value 12,534.00.
'       Converted the Byte value 255 to the Int32 value 255.
'       Converted the Double value 1.632513E+013 to the Int64 value 16,325,130,000,000.
'       Unable to convert the SByte value -16.                                                                  
// Convert an Int32 value to a Decimal (a widening conversion).
int integralValue = 12534;
decimal decimalValue = Convert.ToDecimal(integralValue);
outputBlock.Text += String.Format("Converted the {0} value {1} to " +  
                                  "the {2} value {3:N2}.\n", 
                                  integralValue.GetType().Name, 
                                  integralValue, 
                                  decimalValue.GetType().Name, 
                                  decimalValue);
// Convert a Byte value to an Int32 value (a widening conversion).
byte byteValue = Byte.MaxValue;
int integralValue2 = Convert.ToInt32(byteValue);                                  
outputBlock.Text += String.Format("Converted the {0} value {1} to " +  
                                  "the {2} value {3:G}.\n", 
                                  byteValue.GetType().Name, 
                                  byteValue, 
                                  integralValue2.GetType().Name, 
                                  integralValue2);

// Convert a Double value to an Int32 value (a narrowing conversion).
double doubleValue = 16.32513e12;
try {
   long longValue = Convert.ToInt64(doubleValue);
   outputBlock.Text += String.Format("Converted the {0} value {1:E} to " +  
                                     "the {2} value {3:N0}.\n", 
                                     doubleValue.GetType().Name, 
                                     doubleValue, 
                                     longValue.GetType().Name, 
                                     longValue);
}
catch (OverflowException) {
   outputBlock.Text += String.Format("Unable to convert the {0:E} value {1}.\n", 
                                     doubleValue.GetType().Name, doubleValue);
}

// Convert a signed byte to a byte (a narrowing conversion).     
sbyte sbyteValue = -16;
try {
   byte byteValue2 = Convert.ToByte(sbyteValue);
   outputBlock.Text += String.Format("Converted the {0} value {1} to " +  
                                     "the {2} value {3:G}.\n", 
                                     sbyteValue.GetType().Name, 
                                     sbyteValue, 
                                     byteValue2.GetType().Name, 
                                     byteValue2);
}
catch (OverflowException) {
   outputBlock.Text += String.Format("Unable to convert the {0} value {1}.\n", 
                                     sbyteValue.GetType().Name, sbyteValue);
}                                         
// The example displays the following output:
//       Converted the Int32 value 12534 to the Decimal value 12,534.00.
//       Converted the Byte value 255 to the Int32 value 255.
//       Converted the Double value 1.632513E+013 to the Int64 value 16,325,130,000,000.
//       Unable to convert the SByte value -16.                                                                  

In some cases, particularly when converting to and from floating-point values, a conversion may involve a loss of precision, even though it does not throw an OverflowException. The following example illustrates this loss of precision. In the first case, a Decimal value has less precision (fewer significant digits) when converted to a Double. In the second case, a Double value is rounded from 42.72 to 43 in order to complete the conversion.

Dim doubleValue As Double 

' Convert a Double to a Decimal.
Dim decimalValue As Decimal = 13956810.96702888123451471211d
doubleValue = Convert.ToDouble(decimalValue)
outputBlock.Text += String.Format("{0} converted to {1}.", decimalValue, doubleValue) + vbCrLf

doubleValue = 42.72
Try
   Dim integerValue As Integer = Convert.ToInt32(doubleValue)
   outputBlock.Text += String.Format("{0} converted to {1}.", _
                                     doubleValue, integerValue) + vbCrLf
Catch e As OverflowException
   outputBlock.Text += String.Format("Unable to convert {0} to an integer.", _
                                     doubleValue) + vbCrLf
End Try   
' The example displays the following output:
'       13956810.96702888123451471211 converted to 13956810.9670289.
'       42.72 converted to 43.
double doubleValue; 

// Convert a Double to a Decimal.
decimal decimalValue = 13956810.96702888123451471211m;
doubleValue = Convert.ToDouble(decimalValue);
outputBlock.Text += String.Format("{0} converted to {1}.\n", decimalValue, doubleValue);

doubleValue = 42.72;
try {
   int integerValue = Convert.ToInt32(doubleValue);
   outputBlock.Text += String.Format("{0} converted to {1}.\n", 
                                     doubleValue, integerValue);
}
catch (OverflowException) {      
   outputBlock.Text += String.Format("Unable to convert {0} to an integer.\n", 
                                     doubleValue);
}   
// The example displays the following output:
//       13956810.96702888123451471211 converted to 13956810.9670289.
//       42.72 converted to 43.

For a table that lists both the widening and narrowing conversions supported by the Convert class, see Type Conversion Tables.

Custom Conversions with the ChangeType Method

In addition to supporting conversions to each of the base types, the Convert class can be used to convert a custom type to one or more predefined types. This conversion is performed by the Convert.ChangeType(Object, Type, IFormatProvider) method, which in turn wraps a call to the IConvertible.ToType method of the value parameter. This means that object represented by the value parameter must provide an implementation of the IConvertible interface.

The following example illustrates a possible implementation of the IConvertible interface that allows a TemperatureCelsius object to be converted to a TemperatureFahrenheit object and vice versa. The example defines a base class, Temperature, that implements the IConvertible interface and overrides the Object.ToString method. The derived TemperatureCelsius and TemperatureFahrenheit classes each override the ToType and the ToString methods of the base class.

Public MustInherit Class Temperature
   Implements IConvertible

   Protected temp As Decimal

   Public Sub New(temperature As Decimal)
      Me.temp = temperature
   End Sub

   Public Property Value As Decimal
      Get 
         Return Me.temp
      End Get
      Set
         Me.temp = Value
      End Set   
   End Property

   Public Overrides Function ToString() As String
      Return temp.ToString() & "º"
   End Function

   ' IConvertible implementations.
   Public Function GetTypeCode() As TypeCode Implements IConvertible.GetTypeCode
      Return TypeCode.Object
   End Function   

   Public Function ToBoolean(provider As IFormatProvider) As Boolean Implements IConvertible.ToBoolean
      Throw New InvalidCastException(String.Format("Temperature-to-Boolean conversion is not supported."))
   End Function

   Public Function ToByte(provider As IFormatProvider) As Byte Implements IConvertible.ToByte
      If temp < Byte.MinValue Or temp > Byte.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the Byte data type.", temp))
      Else
         Return CByte(temp)
      End If    
   End Function

   Public Function ToChar(provider As IFormatProvider) As Char Implements IConvertible.ToChar
      Throw New InvalidCastException("Temperature-to-Char conversion is not supported.")
   End Function

   Public Function ToDateTime(provider As IFormatProvider) As DateTime Implements IConvertible.ToDateTime
      Throw New InvalidCastException("Temperature-to-DateTime conversion is not supported.")
   End Function

   Public Function ToDecimal(provider As IFormatProvider) As Decimal Implements IConvertible.ToDecimal
      Return temp
   End Function

   Public Function ToDouble(provider As IFormatProvider) As Double Implements IConvertible.ToDouble
      Return CDbl(temp)
   End Function

   Public Function ToInt16(provider As IFormatProvider) As Int16 Implements IConvertible.ToInt16
      If temp < Int16.MinValue Or temp > Int16.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the Int16 data type.", temp))
      End If
      Return CShort(Math.Round(temp))
   End Function

   Public Function ToInt32(provider As IFormatProvider) As Int32 Implements IConvertible.ToInt32
      If temp < Int32.MinValue Or temp > Int32.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the Int32 data type.", temp))
      End If
      Return CInt(Math.Round(temp))
   End Function

   Public Function ToInt64(provider As IFormatProvider) As Int64 Implements IConvertible.ToInt64
      If temp < Int64.MinValue Or temp > Int64.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the Int64 data type.", temp))
      End If
      Return CLng(Math.Round(temp))
   End Function

   Public Function ToSByte(provider As IFormatProvider) As SByte Implements IConvertible.ToSByte
      If temp < SByte.MinValue Or temp > SByte.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the SByte data type.", temp))
      Else
         Return CSByte(temp)
      End If    
   End Function

   Public Function ToSingle(provider As IFormatProvider) As Single Implements IConvertible.ToSingle
      Return CSng(temp)
   End Function

   Public Overridable Overloads Function ToString(provider As IFormatProvider) As String Implements IConvertible.ToString
      Return temp.ToString(provider) & " °C"
   End Function

   ' If conversionType is a implemented by another IConvertible method, call it.
   Public Overridable Function ToType(conversionType As Type, provider As IFormatProvider) As Object Implements IConvertible.ToType
      Select Case Type.GetTypeCode(conversionType)
         Case TypeCode.Boolean
            Return Me.ToBoolean(provider)
         Case TypeCode.Byte
            Return Me.ToByte(provider)
         Case TypeCode.Char
            Return Me.ToChar(provider)   
         Case TypeCode.DateTime
            Return Me.ToDateTime(provider)
         Case TypeCode.Decimal
            Return Me.ToDecimal(provider)
         Case TypeCode.Double
            Return Me.ToDouble(provider)
         Case TypeCode.Empty
            Throw New NullReferenceException("The target type is null.")
         Case TypeCode.Int16
            Return Me.ToInt16(provider)
         Case TypeCode.Int32
            Return Me.ToInt32(provider)
         Case TypeCode.Int64
            Return Me.ToInt64(provider)
         Case TypeCode.Object
            ' Leave conversion of non-base types to derived classes.
            Throw New InvalidCastException(String.Format("Cannot convert from Temperature to {0}.", _
                                           conversionType.Name))
         Case TypeCode.SByte
            Return Me.ToSByte(provider)
         Case TypeCode.Single
            Return Me.ToSingle(provider)
         Case TypeCode.String
            Return Me.ToString(provider)
         Case TypeCode.UInt16
            Return Me.ToUInt16(provider)
         Case TypeCode.UInt32
            Return Me.ToUInt32(provider)
         Case TypeCode.UInt64
            Return Me.ToUInt64(provider)
         Case Else
            Throw New InvalidCastException("Conversion not supported.")   
      End Select
   End Function

   Public Function ToUInt16(provider As IFormatProvider) As UInt16 Implements IConvertible.ToUInt16
      If temp < UInt16.MinValue Or temp > UInt16.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the UInt16 data type.", temp))
      End If
      Return CUShort(Math.Round(temp))
   End Function

   Public Function ToUInt32(provider As IFormatProvider) As UInt32 Implements IConvertible.ToUInt32
      If temp < UInt32.MinValue Or temp > UInt32.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the UInt32 data type.", temp))
      End If
      Return CUInt(Math.Round(temp))
   End Function

   Public Function ToUInt64(provider As IFormatProvider) As UInt64 Implements IConvertible.ToUInt64
      If temp < UInt64.MinValue Or temp > UInt64.MaxValue Then
         Throw New OverflowException(String.Format("{0} is out of range of the UInt64 data type.", temp))
      End If
      Return CULng(Math.Round(temp))
   End Function
End Class

Public Class TemperatureCelsius : Inherits Temperature : Implements IConvertible
   Public Sub New(value As Decimal)
      MyBase.New(value)
   End Sub

   ' Override ToString methods.
   Public Overrides Function ToString() As String
      Return Me.ToString(Nothing)
   End Function

   Public Overrides Function ToString(provider As IFormatProvider ) As String
      Return temp.ToString(provider) + "°C" 
   End Function

  ' If conversionType is a implemented by another IConvertible method, call it.
   Public Overrides Function ToType(conversionType As Type, provider As IFormatProvider) As Object
      ' For non-objects, call base method.
      If Type.GetTypeCode(conversionType) <> TypeCode.Object Then
         Return MyBase.ToType(conversionType, provider)
      Else   
         If conversionType.Equals(GetType(TemperatureCelsius)) Then
            Return Me
         ElseIf conversionType.Equals(GetType(TemperatureFahrenheit))
            Return New TemperatureFahrenheit(CDec(Me.temp * 9 / 5 + 32))
         ' Unspecified object type: throw an InvalidCastException.
         Else
            Throw New InvalidCastException(String.Format("Cannot convert from Temperature to {0}.", _ 
                                           conversionType.Name))
         End If
      End If                                  
   End Function
End Class

Public Class TemperatureFahrenheit : Inherits Temperature : Implements IConvertible
   Public Sub New(value As Decimal)
      MyBase.New(value)
   End Sub

   ' Override ToString methods.
   Public Overrides Function ToString() As String
      Return Me.ToString(Nothing)
   End Function

   Public Overrides Function ToString(provider As IFormatProvider ) As String
      Return temp.ToString(provider) + "°F" 
   End Function

   Public Overrides Function ToType(conversionType As Type, provider As IFormatProvider) As Object
      ' For non-objects, call base methood.
      If Type.GetTypeCode(conversionType) <> TypeCode.Object Then
         Return MyBase.ToType(conversionType, provider)
      Else   
         ' Handle conversion between derived classes.
         If conversionType.Equals(GetType(TemperatureFahrenheit)) Then 
            Return Me
         ElseIf conversionType.Equals(GetType(TemperatureCelsius))
            Return New TemperatureCelsius(CDec((MyBase.temp - 32) * 5 / 9))
         ' Unspecified object type: throw an InvalidCastException.
         Else
            Throw New InvalidCastException(String.Format("Cannot convert from Temperature to {0}.", _
                                           conversionType.Name))
         End If
      End If                                  
   End Function
End Class   
using System;

public abstract class Temperature : IConvertible
{
   protected decimal temp;

   public Temperature(decimal temperature)
   {
      this.temp = temperature;
   }

   public decimal Value
   { 
      get { return this.temp; } 
      set { this.temp = Value; }        
   }

   public override string ToString()
   {
      return temp.ToString(null as IFormatProvider) + "º";
   }

   // IConvertible implementations.
   public TypeCode GetTypeCode() { 
      return TypeCode.Object;
   }   

   public bool ToBoolean(IFormatProvider provider) {
      throw new InvalidCastException(String.Format("Temperature-to-Boolean conversion is not supported."));
   }

   public byte ToByte(IFormatProvider provider) {
      if (temp < Byte.MinValue || temp > Byte.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the Byte data type.", temp));
      else
         return (byte) temp;
   }

   public char ToChar(IFormatProvider provider) {
      throw new InvalidCastException("Temperature-to-Char conversion is not supported.");
   }

   public DateTime ToDateTime(IFormatProvider provider) {
      throw new InvalidCastException("Temperature-to-DateTime conversion is not supported.");
   }

   public decimal ToDecimal(IFormatProvider provider) {
      return temp;
   }

   public double ToDouble(IFormatProvider provider) {
      return (double) temp;
   }

   public short ToInt16(IFormatProvider provider) {
      if (temp < Int16.MinValue || temp > Int16.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the Int16 data type.", temp));
      else
         return (short) Math.Round(temp);
   }

   public int ToInt32(IFormatProvider provider) {
      if (temp < Int32.MinValue || temp > Int32.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the Int32 data type.", temp));
      else
         return (int) Math.Round(temp);
   }

   public long ToInt64(IFormatProvider provider) {
      if (temp < Int64.MinValue || temp > Int64.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the Int64 data type.", temp));
      else
         return (long) Math.Round(temp);
   }

   public sbyte ToSByte(IFormatProvider provider) {
      if (temp < SByte.MinValue || temp > SByte.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the SByte data type.", temp));
      else
         return (sbyte) temp;
   }

   public float ToSingle(IFormatProvider provider) {
      return (float) temp;
   }

   public virtual string ToString(IFormatProvider provider) {
      return temp.ToString(provider) + "°";
   }

   // If conversionType is implemented by another IConvertible method, call it.
   public virtual object ToType(Type conversionType, IFormatProvider provider) {
      switch (Type.GetTypeCode(conversionType))
      {
         case TypeCode.Boolean:
            return this.ToBoolean(provider);
         case TypeCode.Byte:
            return this.ToByte(provider);
         case TypeCode.Char:
            return this.ToChar(provider);
         case TypeCode.DateTime:
            return this.ToDateTime(provider);
         case TypeCode.Decimal:
            return this.ToDecimal(provider);
         case TypeCode.Double:
            return this.ToDouble(provider);
         case TypeCode.Empty:
            throw new NullReferenceException("The target type is null.");
         case TypeCode.Int16:
            return this.ToInt16(provider);
         case TypeCode.Int32:
            return this.ToInt32(provider);
         case TypeCode.Int64:
            return this.ToInt64(provider);
         case TypeCode.Object:
            // Leave conversion of non-base types to derived classes.
            throw new InvalidCastException(String.Format("Cannot convert from Temperature to {0}.", 
                                           conversionType.Name));
         case TypeCode.SByte:
            return this.ToSByte(provider);
         case TypeCode.Single:
            return this.ToSingle(provider);
         case TypeCode.String:
            IConvertible iconv = this;
            return iconv.ToString(provider);
         case TypeCode.UInt16:
            return this.ToUInt16(provider);
         case TypeCode.UInt32:
            return this.ToUInt32(provider);
         case TypeCode.UInt64:
            return this.ToUInt64(provider);
         default:
            throw new InvalidCastException("Conversion not supported.");
      }
   }

   public ushort ToUInt16(IFormatProvider provider) {
      if (temp < UInt16.MinValue || temp > UInt16.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the UInt16 data type.", temp));
      else
         return (ushort) Math.Round(temp);
   }

   public uint ToUInt32(IFormatProvider provider) {
      if (temp < UInt32.MinValue || temp > UInt32.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the UInt32 data type.", temp));
      else
         return (uint) Math.Round(temp);
   }

   public ulong ToUInt64(IFormatProvider provider) {
      if (temp < UInt64.MinValue || temp > UInt64.MaxValue)
         throw new OverflowException(String.Format("{0} is out of range of the UInt64 data type.", temp));
      else
         return (ulong) Math.Round(temp);
   }
}

public class TemperatureCelsius : Temperature, IConvertible
{
   public TemperatureCelsius(decimal value) : base(value)
   {
   }

   // Override ToString methods.
   public override string ToString()
   {
      return this.ToString(null);
   }

   public override string ToString(IFormatProvider provider)
   {
      return temp.ToString(provider) + "°C"; 
   }

   // If conversionType is a implemented by another IConvertible method, call it.
   public override object ToType(Type conversionType, IFormatProvider provider) {
      // For non-objects, call base method.
      if (Type.GetTypeCode(conversionType) != TypeCode.Object) {
         return base.ToType(conversionType, provider);
      }   
      else
      {   
         if (conversionType.Equals(typeof(TemperatureCelsius)))
            return this;
         else if (conversionType.Equals(typeof(TemperatureFahrenheit)))
            return new TemperatureFahrenheit((decimal) this.temp * 9 / 5 + 32);
         else
            throw new InvalidCastException(String.Format("Cannot convert from Temperature to {0}.", 
                                           conversionType.Name));
      }
   }
}

public class TemperatureFahrenheit : Temperature, IConvertible 
{
   public TemperatureFahrenheit(decimal value) : base(value)
   {
   }

   // Override ToString methods.
   public override string ToString()
   {
      return this.ToString(null);
   }

   public override string ToString(IFormatProvider provider)
   {
      return temp.ToString(provider) + "°F"; 
   }

   public override object ToType(Type conversionType, IFormatProvider provider)
   { 
      // For non-objects, call base methood.
      if (Type.GetTypeCode(conversionType) != TypeCode.Object) {
         return base.ToType(conversionType, provider);
      }   
      else
      {   
         // Handle conversion between derived classes.
         if (conversionType.Equals(typeof(TemperatureFahrenheit))) 
            return this;
         else if (conversionType.Equals(typeof(TemperatureCelsius)))
            return new TemperatureCelsius((decimal) (this.temp - 32) * 5 / 9);
         // Unspecified object type: throw an InvalidCastException.
         else
            throw new InvalidCastException(String.Format("Cannot convert from Temperature to {0}.", 
                                           conversionType.Name));
      }                                 
   }
}   

The following example illustrates several calls to these IConvertible implementations to convert TemperatureCelsius objects to TemperatureFahrenheit objects and vice versa.

Dim tempC1 As New TemperatureCelsius(0)
Dim tempF1 As TemperatureFahrenheit = CType(Convert.ChangeType(tempC1, GetType(TemperatureFahrenheit), Nothing), TemperatureFahrenheit)
outputBlock.Text += String.Format("{0} equals {1}.", tempC1, tempF1) + vbCrLf
Dim tempC2 As TemperatureCelsius = CType(Convert.ChangeType(tempC1, GetType(TemperatureCelsius), Nothing), TemperatureCelsius)
outputBlock.Text += String.Format("{0} equals {1}.", tempC1, tempC2) + vbCrLf
Dim tempF2 As New TemperatureFahrenheit(212)
Dim tempC3 As TEmperatureCelsius = CType(Convert.ChangeType(tempF2, GEtType(TemperatureCelsius), Nothing), TemperatureCelsius)
outputBlock.Text += String.Format("{0} equals {1}.", tempF2, tempC3) + vbCrLf
Dim tempF3 As TemperatureFahrenheit = CType(Convert.ChangeType(tempF2, GetType(TemperatureFahrenheit), Nothing), TemperatureFahrenheit)
outputBlock.Text += String.Format("{0} equals {1}.", tempF2, tempF3) + vbCrLf
' The example displays the following output:
'       0°C equals 32°F.
'       0°C equals 0°C.
'       212°F equals 100°C.
'       212°F equals 212°F.      
TemperatureCelsius tempC1 = new TemperatureCelsius(0);
TemperatureFahrenheit tempF1 = (TemperatureFahrenheit) Convert.ChangeType(tempC1, typeof(TemperatureFahrenheit), null);
outputBlock.Text += String.Format("{0} equals {1}.\n", tempC1, tempF1);
TemperatureCelsius tempC2 = (TemperatureCelsius) Convert.ChangeType(tempC1, typeof(TemperatureCelsius), null);
outputBlock.Text += String.Format("{0} equals {1}.\n", tempC1, tempC2);
TemperatureFahrenheit tempF2 = new TemperatureFahrenheit(212);
TemperatureCelsius tempC3 = (TemperatureCelsius) Convert.ChangeType(tempF2, typeof(TemperatureCelsius), null);
outputBlock.Text += String.Format("{0} equals {1}.\n", tempF2, tempC3);
TemperatureFahrenheit tempF3 = (TemperatureFahrenheit) Convert.ChangeType(tempF2, typeof(TemperatureFahrenheit), null);
outputBlock.Text += String.Format("{0} equals {1}.\n", tempF2, tempF3);
// The example displays the following output:
//       0°C equals 32°F.
//       0°C equals 0°C.
//       212°F equals 100°C.
//       212°F equals 212°F.

The TypeConverter Class

The .NET Framework also allows you to define a type converter for a custom type by extending the System.ComponentModel.TypeConverter class and associating the type converter with the type through a System.ComponentModel.TypeConverterAttribute attribute. The following table highlights the differences between this approach and implementing the IConvertible interface for a custom type.

NoteNote:

Design-time support can be provided for a custom type only if it has a type converter defined for it.

Conversion using TypeConverter

Conversion using IConvertible

Can be used both at design time and at run time.

Can be used only at run time.

Uses reflection; therefore, is slower than conversion enabled by IConvertible.

Does not use reflection.

Allows two-way type conversions from the custom type to other data types and from other data types to the custom type. For example, a TypeConverter defined for MyType allows conversions from MyType to String and from String to MyType.

Allows conversion from a custom type to other data types but not from other data types to the custom type.

NoteNote:
A TypeConverter for a type is implemented outside the type and associated with the type by applying a TypeConverterAttribute attribute.
NoteNote:
IConvertible is implemented by a custom type. To convert a type. A user of the type invokes an IConvertible conversion method on the type.

For details about using type converters to perform conversions, see System.ComponentModel.TypeConverter.

See Also

Reference

Concepts