C# Reference ยท Operators and Expressions
User-defined conversions
Reference for C# user-defined conversion operators: when to choose implicit or explicit, the rules the compiler enforces, and how they interact with casts.
A user-defined conversion lets you say how your type turns into another type, or how another type turns into yours. You declare it as a public static operator with the keyword implicit or explicit. An implicit conversion happens automatically wherever a value of the target type is expected. An explicit one requires a cast, (Target)value.
The guideline is simple: make a conversion implicit only if it can never lose information and never throw. Otherwise make it explicit.
public static implicit operator Celsius(double degrees) => new(degrees); public static explicit operator double(Celsius c) => c.Degrees;
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public static implicit operator TargetType(SourceType value) { ... } public static explicit operator TargetType(SourceType value) { ... } public static explicit operator checked TargetType(SourceType value) { ... } // C# 11
| Name | Description |
|---|---|
SourceType |
The type being converted from. |
TargetType |
The type being converted to. Either the source or the target must be the declaring type. |
Returns: a value of TargetType.
Errors: the compiler rejects conversions to or from object, interfaces, base or derived classes of the declaring type (they already convert), and duplicate conversions. A missing cast gives error CS0266.
Usage notes
- Implicit conversions must not throw and must not lose information. If either can happen, make it
explicit. - You cannot define a conversion between two types if a built-in or inheritance conversion already exists, for example to a base class.
- An
implicitconversion is also reachable through a cast, but anexplicitone is not applied silently. - At most one user-defined conversion is applied per step. The compiler may combine it with a built-in numeric conversion before or after it, as in
Meters m = 5. - Pattern matching (
is,as,switchtype patterns) ignores user-defined conversions.o is UserIdisfalsewhenois a string. - Overload resolution takes implicit conversions into account, which can make overloads ambiguous. Too many implicit conversions make code harder to read.
- A conversion to
stringis usually better written asToString(); an implicit conversion hides cost and surprises. - Nullable lifting: for struct types the compiler also lifts conversions to
T?, soCelsius? x = 4.0;works. - Generic math interfaces (
INumber<T>,IParsable<T>) are often a cleaner design than many conversions.