Numeric conversions are common in .NET applications. Developers use them when processing financial values, reading data from databases, communicating with external services, and performing calculations across different numeric types.
Most of the time, these conversions work without attracting much attention. However, a small change in how a numeric value is converted can affect application results, especially when an application moves to a newer .NET runtime.
.NET 11 introduces an important behavioral change to conversions between decimal and binary floating-point types. Conversions now use correctly rounded results based on the exact source value rather than losing information through earlier conversion algorithms.
This improves numerical accuracy, but it can also change results in existing applications.
For example, converting a double value of 1.23 to decimal previously produced 1.23. With the new behavior, the conversion preserves the actual binary floating-point value, which is approximately 1.229999999999999982236431605997.
That difference may seem insignificant, but it can affect financial calculations, database comparisons, serialized values, and tests that depend on previous conversion results.
This article explains what changed in .NET 11, why existing applications may produce different results, and how developers can review and update their numeric conversion logic safely.
Understanding the Difference Between Decimal and Double
Before examining the .NET 11 change, it is important to understand how decimal and double represent numbers.
The decimal type is designed for decimal-based arithmetic. It is commonly used for financial values, prices, taxes, and calculations where decimal precision is important.
The double type uses binary floating-point representation. It can represent a much wider range of values, but many decimal fractions cannot be represented exactly in binary.
Consider this example:
double price = 1.23;
Console.WriteLine(price);
Although the output looks like 1.23, the actual binary representation is an approximation.
The same issue appears with values such as 0.1, 0.2, and 0.3.
For example:
double first = 0.1;
double second = 0.2;
Console.WriteLine(first + second);
The result is not necessarily exactly 0.3 because the individual values cannot be represented exactly using binary floating-point.
This is not a bug in C#. It is a consequence of how binary floating-point numbers are represented.
The decimal type uses a different representation that can represent many commonly used decimal fractions exactly, within its supported precision and range.
For example:
decimal first = 0.1m;
decimal second = 0.2m;
Console.WriteLine(first + second);
The result is:
0.3
The important point is that choosing a numeric type should depend on the meaning of the data, not simply on which type is convenient to use.
What Changed in .NET 11
Starting with .NET 11 Preview 7, conversions between decimal and binary floating-point types use correctly rounded results.
The change also affects conversions from BigInteger to binary floating-point types.
Previously, some conversions discarded significant digits or used intermediate conversions that introduced additional rounding errors.
The new implementation calculates the conversion as if the source value were available with exact intermediate precision, followed by a single rounding to the nearest representable destination value.
This means that a conversion can produce a different result even when the original source code has not changed.
Consider the following example:
using System.Globalization;
double value = 1.23;
decimal converted = (decimal)value;
Console.WriteLine(
converted.ToString("G29", CultureInfo.InvariantCulture));
Before .NET 11, the output was:
1.23
With the new conversion behavior, the output becomes:
1.229999999999999982236431606
Why does this happen?
The double variable does not contain the exact decimal number 1.23. It contains the nearest binary floating-point representation of that number.
The previous conversion algorithm retained a limited number of significant decimal digits, hiding the difference.
The .NET 11 implementation preserves the exact source value to the extent that the destination decimal type can represent it.
This is a behavioral breaking change rather than a source-code breaking change. Existing code can still compile, but its results may be different.
Why This Change Matters for Existing Applications
The conversion behavior can affect applications that move values between decimal and binary floating-point types.
A common example is a financial application that receives values from an external service as double and converts them into decimal for calculations.
Consider the following implementation:
double productPrice = 19.99;
decimal amount = (decimal)productPrice;
Console.WriteLine(amount);
With the previous conversion behavior, developers might have expected the result to be 19.99.
With .NET 11, the result preserves the underlying binary approximation.
If the application subsequently calculates tax, discounts, or invoice totals, the additional precision can affect intermediate and final results.
Other areas that deserve attention include:
Financial calculations that convert double values into decimal.
Database applications that read floating-point columns and convert them into decimal.
APIs that exchange numeric values between different programming languages.
Serialization systems that depend on previously generated numeric values.
Tests that compare exact numeric output.
Applications that convert BigInteger values into floating-point types.
The change does not mean that decimal calculations are now inaccurate. It means that conversions expose the actual value represented by the source type instead of hiding its approximation.
Use Decimal Literals When Working With Decimal Values
One of the simplest ways to avoid unexpected conversion results is to use the correct numeric literal from the beginning.
Consider this implementation:
double price = 123.45;
decimal amount = (decimal)price;
If the original value represents a monetary amount, using double introduces an unnecessary binary floating-point conversion.
A better approach is:
decimal amount = 123.45m;
The m suffix tells the C# compiler that the literal should be treated as decimal.
This avoids converting a binary floating-point value into decimal when the application already knows that the original value represents a decimal quantity.
The same principle applies when initializing values:
decimal taxRate = 0.18m;
decimal discount = 0.10m;
decimal unitPrice = 1250.50m;
Using decimal literals consistently helps prevent unnecessary conversions in financial and business applications.
However, developers cannot always control the source type. External APIs, legacy databases, and third-party libraries may still provide float or double values.
In those situations, the conversion policy should be explicit.
Apply Business Rounding Rules Instead of Relying on Conversion Behavior
Correctly converting a number and applying business rounding are two different operations.
A conversion determines the nearest representable value in the destination numeric type.
Business rounding determines how an application should present or use a value at a particular decimal precision.
For example, an invoice application may need to display an amount with two decimal places.
You should not rely on an implicit numeric conversion to implement this rule.
Instead, use decimal arithmetic and explicitly apply the required rounding policy.
decimal amount = 125.6789m;
decimal rounded = Math.Round(
amount,
2,
MidpointRounding.AwayFromZero);
Console.WriteLine(rounded);
Output:
125.68
The MidpointRounding.AwayFromZero option is appropriate when the business requirement specifies rounding midpoint values away from zero.
Another common option is MidpointRounding.ToEven, which rounds midpoint values toward the nearest even number.
For example:
decimal first = Math.Round(
2.5m,
0,
MidpointRounding.ToEven);
decimal second = Math.Round(
3.5m,
0,
MidpointRounding.ToEven);
Console.WriteLine(first);
Console.WriteLine(second);
Output:
2
4
The correct rounding strategy depends on the application's requirements. Financial applications should define these rules explicitly rather than allowing different parts of the application to use different rounding behavior.
Also, do not round every intermediate calculation automatically. Some applications need to preserve additional precision during calculations and round only when storing or presenting the final amount.
Review Conversions From Double and Float to Decimal
The most visible part of the .NET 11 change involves converting binary floating-point values into decimal.
Applications should review explicit casts, constructors, and conversion methods.
For example:
double temperature = 36.6;
decimal converted = Convert.ToDecimal(temperature);
The conversion can now preserve more of the actual binary source value than previous .NET versions did.
If the application needs the previous behavior for compatibility, Microsoft documents a way to reproduce the earlier significant-digit rounding.
The previous conversion retained seven significant decimal digits for float and fifteen significant decimal digits for double.
The following implementation demonstrates how to reproduce that behavior:
using System.Globalization;
static decimal ConvertToDecimalLikePrevious(float value)
{
Span<char> text = stackalloc char[32];
value.TryFormat(
text,
out int length,
"G7",
CultureInfo.InvariantCulture);
return decimal.Parse(
text[..length],
NumberStyles.Float,
CultureInfo.InvariantCulture);
}
static decimal ConvertToDecimalLikePrevious(double value)
{
Span<char> text = stackalloc char[32];
value.TryFormat(
text,
out int length,
"G15",
CultureInfo.InvariantCulture);
return decimal.Parse(
text[..length],
NumberStyles.Float,
CultureInfo.InvariantCulture);
}
You can use these methods when an application has a genuine compatibility requirement to preserve previous conversion results.
For example:
double measurement = 123.456789123;
decimal previousBehavior =
ConvertToDecimalLikePrevious(measurement);
Console.WriteLine(previousBehavior);
This approach is not a general replacement for the new conversion behavior.
Use it only when an existing application depends on the previous significant-digit rounding and changing that behavior would break an established contract.
For new financial calculations, prefer receiving or storing the original value as decimal whenever possible.
Review Decimal to Double Conversions
The change also affects conversions in the opposite direction.
Previously, some conversions from decimal to double or float could involve multiple rounding steps.
.NET 11 now rounds the exact decimal source value once to the nearest representable destination value.
Consider this example:
using System.Globalization;
decimal value = 10000000000000.099609375m;
double converted = (double)value;
Console.WriteLine(
converted.ToString("G99", CultureInfo.InvariantCulture));
The previous behavior produced:
10000000000000.09765625
The new behavior produces:
10000000000000.099609375
This matters when applications exchange numeric values with systems that use double or float.
For example, a .NET application might store financial values as decimal but send them to another service that expects double.
The receiving system cannot necessarily represent the original decimal value exactly.
Developers should therefore define the precision expected at the integration boundary and test both the serialized value and the value received by the external system.
Correct rounding improves the conversion, but it does not make double capable of representing every decimal value exactly.
Do Not Overlook BigInteger Conversions
Although the decimal conversion change attracts the most attention, .NET 11 also improves conversions from BigInteger to binary floating-point types.
BigInteger supports integers that are larger than the range of standard integral types such as long and ulong.
When converting a BigInteger into double, float, Half, or BFloat16, the destination type may not have enough precision to represent the entire source value.
Previously, some conversions discarded bits or passed through an intermediate type, which could produce a result that was not the nearest representable value.
.NET 11 performs correctly rounded conversions instead.
For example:
using System.Globalization;
using System.Numerics;
BigInteger value = long.MaxValue / 2;
double converted = (double)value;
Console.WriteLine(
converted.ToString("G17", CultureInfo.InvariantCulture));
The previous result was:
4.6116860184273874E+18
The new result is:
4.6116860184273879E+18
Applications that use BigInteger for large identifiers, calculations, financial models, or mathematical operations should review these conversions.
If an application depends on an exact integer value, do not convert it into double simply for convenience. Keep it as BigInteger or use another representation that preserves the required precision.
Audit Existing Applications Before Moving to .NET 11
The conversion change is especially important for applications that have been running for several years.
Developers should review the codebase before upgrading rather than waiting for unexpected test failures after deployment.
Start by searching for explicit conversions between float, double, and decimal.
Look for patterns such as:
decimal amount = (decimal)doubleValue;
decimal converted = Convert.ToDecimal(floatValue);
double result = (double)decimalValue;
Also inspect constructors, generic numeric conversion methods, and code that uses IConvertible.
Pay attention to database models. A column defined as float or real may be mapped to double or float in the application, even when the business requirement expects decimal arithmetic.
If the source system represents money or another decimal quantity, review whether the database schema and application model should use decimal-compatible types instead.
Next, inspect integration boundaries. JSON APIs, message queues, external libraries, and native applications may use different numeric representations.
Finally, review tests that compare exact numeric values or use hardcoded expected results generated by earlier .NET versions.
A test that previously expected 1.23 after converting a double may now need to reflect the actual conversion behavior or use a decimal source value if that is what the application intended.
Update Unit Tests and Expected Results
Existing tests may fail after migrating to .NET 11, even when the application still compiles successfully.
This happens because tests may encode the previous conversion result rather than the actual business requirement.
Consider a test like this:
double input = 1.23;
decimal actual = (decimal)input;
Assert.Equal(1.23m, actual);
The assertion can fail because the converted value now preserves the binary approximation.
There are two possible approaches, depending on the requirement.
If the application genuinely needs the exact decimal value 1.23, change the input type or source representation:
decimal input = 1.23m;
decimal actual = input;
Assert.Equal(1.23m, actual);
If the application intentionally converts a double value, update the test to verify the new conversion behavior.
Avoid changing every failing assertion to use a broad tolerance without understanding the reason for the difference. Tolerance-based comparisons are useful for certain numerical algorithms, but they should not hide incorrect financial calculations or unexpected changes in application behavior.
Also review serialized test data, snapshots, and expected output files. These may contain numeric values produced by the previous conversion algorithms.
Is There a Compatibility Switch?
One important detail for migration planning is that .NET 11 does not provide a compatibility switch to restore the previous decimal and BigInteger conversion algorithms.
Applications that depend on the previous results must implement the required compatibility behavior explicitly.
This means developers should not expect a runtime configuration option to reverse the conversion change.
If an application requires the old float-to-decimal or double-to-decimal behavior, use an explicit compatibility conversion method such as the G7 and G15 examples discussed earlier.
For conversions involving other numeric types, review the original algorithm and implement the required behavior deliberately rather than assuming that one compatibility helper can cover every conversion direction.
It is also worth remembering that compile-time constant conversions can be affected by the compiler version. When a conversion is evaluated as a constant, rebuilding with a .NET 11 SDK can embed the new result in the compiled assembly even if the project targets an earlier framework.
This is another reason to include SDK version changes in migration testing.
Best Practices for Safe Numeric Conversions
The .NET 11 change is a good opportunity to review how an application handles numeric data.
Use decimal for monetary values and other quantities that require decimal arithmetic. Avoid introducing double into financial calculations unless there is a specific technical requirement.
Keep numeric types consistent across application layers. If a database column represents a monetary amount, map it to decimal rather than converting it through double unnecessarily.
Apply business rounding explicitly with Math.Round and an appropriate MidpointRounding strategy.
Treat conversion boundaries carefully when exchanging data with external systems. Document the precision expected by each interface and test representative values.
Finally, maintain regression tests for important calculations. Include ordinary values, very small values, large values, negative values, midpoint values, and values near the precision limits of the involved types.
These practices help prevent subtle numeric changes from becoming production issues.
Summary
.NET 11 improves conversions between decimal and binary floating-point types by rounding the exact source value once to the nearest representable destination value. It also improves conversions from BigInteger to binary floating-point types.
Although this change improves numerical correctness, existing applications may produce different results when they convert between these types.
Developers should review explicit conversions, database mappings, API boundaries, serialized values, and tests that depend on previous results.
For financial and business applications, the safest approach is to use decimal from the point where the original data is received, apply business rounding rules explicitly, and avoid unnecessary conversions through double or float.
The goal is not to preserve every old result. It is to ensure that every numeric conversion reflects the application's actual requirements and produces predictable results after upgrading to .NET 11.
Join the conversation! Your thoughts help the community grow.