Move IQuantity conversion members to extensions (#1696)

## Why

This extracts the independently useful `IQuantity.As()` / `ToUnit()`
interface cleanup from #1544 so that the larger fractional quantity
value PR carries less unrelated API and generated-code churn.

Conversion is behavior rather than quantity state, and requiring every
custom `IQuantity` implementation to implement these members adds
unnecessary burden. Keeping the calls as extensions preserves normal
source usage while removing those members from the interface contract.

The generated concrete `As()` / `ToUnit()` methods and their conversion
formulas deliberately remain in place. Removing those depends on the
`UnitConverter` redesign in #1544 and is not a safe standalone change on
current `master`.

A conservative tree-to-tree comparison now reduces #1544 by about 3,098
changed lines. Of those, 3,096 lines are exact generated overlap (24
lines in each of 129 quantities); the generator, interface, and
custom-fixture deletions overlap further. The final total depends on
resolving the temporary current-master `UnitConverter` compatibility
bridge when #1544 is synchronized.

## Changes

- Remove `As()` and `ToUnit()` members from `IQuantity`,
`IQuantity<TUnit>`, and the self-typed interface default implementation.
- Add equivalent `QuantityExtensions` overloads for untyped, typed, and
self-typed quantity references.
- Support an explicitly supplied `UnitConverter` for self-typed generic
conversions.
- Route extension conversions through the current `UnitConverter`,
including conversion through a quantity's base unit when no direct
conversion is registered.
- Remove the generated explicit interface shims while retaining all
concrete generated conversion methods.
- Regenerate all quantity sources.
- Simplify the custom `HowMuch` test quantity now that interface
implementations no longer need conversion members.
- Align wrong-unit interface-call behavior with `UnitConverter` by
throwing `UnitNotFoundException`.

This intentionally changes the binary interface contract; ordinary
source calls continue to resolve through extensions in the `UnitsNet`
namespace.

## Tests

Added or changed tests cover:

- `As()` through both `IQuantity` and `IQuantity<TUnit>` references.
- `ToUnit()` through an `IQuantity` reference starting from a non-base
unit.
- Self-typed generic `ToUnit()` with a custom `UnitConverter`.
- Wrong-unit `As()` and `ToUnit()` calls reporting
`UnitNotFoundException`.

Validation performed:

- `dotnet run --project CodeGen`
- `dotnet build UnitsNet.slnx --configuration Release --no-restore`
- Focused conversion/API tests on .NET 10: 1,854 passed
- Focused conversion/API tests on .NET Framework 4.8: 1,851 passed
- `IQuantityTests` on .NET 10: 20 passed
- `IQuantityTests` on .NET Framework 4.8: 17 passed
- Full core test suite on .NET 10: 42,876 passed, 20 skipped, 0 failed

Author: angularsen

CodeGen/Generators/UnitsNetGen/QuantityGenerator.cs

@@ -1024,7 +1024,7 @@ public double As({_unitEnumName} unit)
 
             Writer.WL( $@"
 
-        /// <inheritdoc cref=""IQuantity.As(UnitKey)""/>
+        /// <inheritdoc cref=""QuantityExtensions.As(IQuantity, UnitKey)""/>
         public double As(UnitKey unitKey)
         {{
             return As(unitKey.ToUnit<{_unitEnumName}>());
@@ -1129,30 +1129,6 @@ private bool TryToUnit({_unitEnumName} unit, [NotNullWhen(true)] out {_quantity.
         }}
 ");
             Writer.WL($@"
-        #region Explicit implementations
-
-        double IQuantity.As(Enum unit)
-        {{
-            if (unit is not {_unitEnumName} typedUnit)
-                throw new ArgumentException($""The given unit is of type {{unit.GetType()}}. Only {{typeof({_unitEnumName})}} is supported."", nameof(unit));
-
-            return As(typedUnit);
-        }}
-
-        /// <inheritdoc />
-        IQuantity IQuantity.ToUnit(Enum unit)
-        {{
-            if (!(unit is {_unitEnumName} typedUnit))
-                throw new ArgumentException($""The given unit is of type {{unit.GetType()}}. Only {{typeof({_unitEnumName})}} is supported."", nameof(unit));
-
-            return ToUnit(typedUnit, DefaultConversionFunctions);
-        }}
-
-        /// <inheritdoc />
-        IQuantity<{_unitEnumName}> IQuantity<{_unitEnumName}>.ToUnit({_unitEnumName} unit) => ToUnit(unit);
-
-        #endregion
-
         #endregion
 ");
         }

Docs/upgrading-from-5.x-to-6.x.md

@@ -29,6 +29,7 @@ If there is sufficient demand for supporting any number type like `float`, `deci
     - Remove `IValueQuantity<out TValueType>`
     - Change `IQuantity<TSelf, TUnitType, out TValueType>` to `IQuantity<TSelf, TUnitType>`
     - Change `IArithmeticQuantity<TSelf, TUnitType, TValueType>` to `IArithmeticQuantity<TSelf, TUnitType>`
+- Move `IQuantity.As()` and `IQuantity.ToUnit()` from the quantity interfaces to `QuantityExtensions` #1696
 - Remove obsolete units #1372
     - `CoefficientOfThermalExpansion.InverseKelvin`, `InverseDegreeCelsius`, `InverseDegreeFahrenheit`
     - `HeatTransferCoefficient.BtuPerSquareFootDegreeFahrenheit`
@@ -43,10 +44,12 @@ If there is sufficient demand for supporting any number type like `float`, `deci
 ### Source incompatible
 
 - `IQuantity.UnitInfo` is now a interface default member on .NET5+, and may compete with any custom property implemented in third party quantities #1649
+- Custom quantities that explicitly implement `IQuantity.As()`, `IQuantity.ToUnit()`, `IQuantity<TUnitType>.As()` or `IQuantity<TUnitType>.ToUnit()` must remove those explicit interface implementations. The methods may remain as ordinary members if they are also part of the custom quantity's public API. #1696
 
 ### Behavioral change
 
-None.
+- Calls to `.As()` and `.ToUnit()` through an `IQuantity` or `IQuantity<TUnitType>` reference now use the `QuantityExtensions` methods and `UnitConverter.Default`. They no longer dispatch to type-specific methods defined by a custom quantity. Custom quantities that need these calls to support conversion must register their conversion functions with `UnitConverter.Default`. #1696
+- Calling these extension methods with an incompatible unit type now throws `UnitNotFoundException` instead of `ArgumentException`. Code that catches `ArgumentException` around interface-based conversions may need to be updated. #1696
 
 ### Description of different kinds of incompatible changes
 

UnitsNet.Tests/CustomCode/IQuantityTests.cs

@@ -7,15 +7,60 @@ namespace UnitsNet.Tests;
 public partial class IQuantityTests
 {
     [Fact]
-    public void As_GivenWrongUnitType_ThrowsArgumentException()
+    public void As_GivenWrongUnitType_ThrowsUnitNotFoundException()
     {
-        Assert.All(Quantity.Infos.Select(x => x.Zero), quantity => { Assert.Throws<ArgumentException>(() => quantity.As(ComparisonType.Absolute)); });
+        Assert.All(Quantity.Infos.Select(x => x.Zero), quantity => { Assert.Throws<UnitNotFoundException>(() => quantity.As(ComparisonType.Absolute)); });
     }
 
     [Fact]
-    public void ToUnit_GivenWrongUnitType_ThrowsArgumentException()
+    public void ToUnit_GivenWrongUnitType_ThrowsUnitNotFoundException()
     {
-        Assert.All(Quantity.Infos.Select(x => x.Zero), quantity => { Assert.Throws<ArgumentException>(() => quantity.ToUnit(ComparisonType.Absolute)); });
+        Assert.All(Quantity.Infos.Select(x => x.Zero),
+            quantity => { Assert.Throws<UnitNotFoundException>(() => quantity.ToUnit(ComparisonType.Absolute)); });
+    }
+
+    [Fact]
+    public void As_InterfaceReferences_ReturnConvertedValue()
+    {
+        var mass = Mass.FromKilograms(1);
+        IQuantity quantity = mass;
+        IQuantity<MassUnit> typedQuantity = mass;
+
+        Assert.Equal(1000, quantity.As(MassUnit.Gram));
+        Assert.Equal(1000, typedQuantity.As(MassUnit.Gram));
+    }
+
+    [Fact]
+    public void ToUnit_IQuantityFromNonBaseUnit_ReturnsConvertedQuantity()
+    {
+        IQuantity quantity = Length.FromKilometers(1);
+
+        IQuantity convertedQuantity = quantity.ToUnit(LengthUnit.Centimeter);
+
+        Assert.Equal(100_000, convertedQuantity.Value);
+        Assert.Equal(LengthUnit.Centimeter, convertedQuantity.Unit);
+    }
+
+    [Fact]
+    public void ToUnit_GenericConstraintWithCustomConverter_UsesProvidedConverter()
+    {
+        var converter = new UnitConverter();
+        converter.SetConversionFunction<Length>(
+            LengthUnit.Meter,
+            LengthUnit.Centimeter,
+            _ => Length.FromCentimeters(123));
+
+        Length convertedQuantity = ConvertToUnit(Length.FromMeters(1), LengthUnit.Centimeter, converter);
+
+        Assert.Equal(123, convertedQuantity.Value);
+        Assert.Equal(LengthUnit.Centimeter, convertedQuantity.Unit);
+
+        static TQuantity ConvertToUnit<TQuantity, TUnit>(TQuantity quantity, TUnit unit, UnitConverter unitConverter)
+            where TQuantity : IQuantity<TQuantity, TUnit>
+            where TUnit : struct, Enum
+        {
+            return quantity.ToUnit(unit, unitConverter);
+        }
     }
 
     [Fact]

UnitsNet.Tests/CustomQuantities/HowMuch.cs

@@ -20,11 +20,6 @@ public static HowMuch From(double value, HowMuchUnit unit)
             return new HowMuch(value, unit);
         }
 
-        public double As(HowMuchUnit unit)
-        {
-            throw new NotImplementedException();
-        }
-
         public HowMuchUnit Unit { get; }
 
         public double Value { get; }
@@ -64,23 +59,6 @@ UnitKey IQuantity.UnitKey
             get => UnitKey.ForUnit(Unit);
         }
 
-        public double As(Enum unit) => Convert.ToDouble(unit);
-        public double As(UnitKey unitKey)
-        {
-            return As(unitKey.ToUnit<HowMuchUnit>());
-        }
-
-        public IQuantity ToUnit(Enum unit)
-        {
-            if (unit is HowMuchUnit howMuchUnit) return new HowMuch(As(unit), howMuchUnit);
-            throw new ArgumentException("Must be of type HowMuchUnit.", nameof(unit));
-        }
-
-        public IQuantity<HowMuchUnit> ToUnit(HowMuchUnit unit)
-        {
-            throw new NotImplementedException();
-        }
-
         public override string ToString()
         {
             return $"{Value} {Unit}";

UnitsNet/Extensions/QuantityExtensions.cs

@@ -78,12 +78,80 @@ public static UnitInfo<TQuantity, TUnit> GetUnitInfo<TQuantity, TUnit>(this IQua
 #endif
     }
 
-    /// <inheritdoc cref="IQuantity.As(UnitKey)" />
-    /// <remarks>This should be using UnitConverter.Default.ConvertValue(quantity, toUnit) </remarks>
+    /// <summary>
+    ///     Gets the value of a quantity in the specified unit.
+    /// </summary>
     internal static double GetValue<TQuantity>(this TQuantity quantity, UnitKey toUnit)
         where TQuantity : IQuantity
     {
-        return quantity.As(toUnit);
+        return UnitConverter.Default.ConvertValue(quantity, toUnit);
+    }
+
+    private static IQuantity ConvertTo(this UnitConverter converter, IQuantity quantity, UnitKey toUnit)
+    {
+        if (quantity.UnitKey == toUnit)
+        {
+            return quantity;
+        }
+
+        var targetUnit = (Enum)toUnit;
+        Type quantityType = quantity.GetType();
+        if (converter.TryGetConversionFunction(quantityType, quantity.Unit, quantityType, targetUnit, out ConversionFunction? conversionFunction))
+        {
+            return conversionFunction(quantity);
+        }
+
+#pragma warning disable CS0618 // Type or member is obsolete
+        UnitKey baseUnit = quantity.QuantityInfo.BaseUnitInfo.UnitKey;
+#pragma warning restore CS0618 // Type or member is obsolete
+        if (quantity.UnitKey != baseUnit)
+        {
+            IQuantity quantityInBaseUnit = converter.ConvertTo(quantity, baseUnit);
+            return converter.ConvertTo(quantityInBaseUnit, toUnit);
+        }
+
+        throw new UnitNotFoundException($"Can't convert {quantity.Unit} to {targetUnit}.");
+    }
+
+    /// <summary>
+    ///     Converts a quantity value to the specified unit.
+    /// </summary>
+    /// <param name="converter">The converter to use.</param>
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="toUnit">The target unit.</param>
+    /// <returns>The converted value.</returns>
+    internal static double ConvertValue<TQuantity>(this UnitConverter converter, TQuantity quantity, UnitKey toUnit)
+        where TQuantity : IQuantity
+    {
+        return converter.ConvertTo(quantity, toUnit).Value;
+    }
+
+    /// <summary>
+    ///     Converts a quantity to the specified unit while preserving its concrete type.
+    /// </summary>
+    /// <param name="converter">The converter to use.</param>
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="toUnit">The target unit.</param>
+    /// <returns>The converted quantity.</returns>
+    internal static TQuantity ConvertToUnit<TQuantity>(this UnitConverter converter, TQuantity quantity, UnitKey toUnit)
+        where TQuantity : IQuantityOfType<TQuantity>
+    {
+        return (TQuantity)converter.ConvertTo(quantity, toUnit);
+    }
+
+    /// <summary>
+    ///     Gets the value of a quantity in the specified unit.
+    /// </summary>
+    /// <typeparam name="TQuantity">The quantity type.</typeparam>
+    /// <typeparam name="TUnit">The unit enum type.</typeparam>
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="unit">The target unit.</param>
+    /// <returns>The converted value.</returns>
+    public static double As<TQuantity, TUnit>(this TQuantity quantity, TUnit unit)
+        where TQuantity : IQuantity<TQuantity, TUnit>
+        where TUnit : struct, Enum
+    {
+        return UnitConverter.Default.ConvertValue(quantity, UnitKey.ForUnit(unit));
     }
 
     /// <summary>
@@ -110,6 +178,32 @@ public static double As<TQuantity>(this TQuantity quantity, UnitSystem unitSyste
 #endif
     }
 
+    /// <summary>
+    ///     Converts a quantity to the specified unit while preserving its concrete type.
+    /// </summary>
+    /// <typeparam name="TQuantity">The quantity type.</typeparam>
+    /// <typeparam name="TUnit">The unit enum type.</typeparam>
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="unit">The target unit.</param>
+    /// <returns>The converted quantity.</returns>
+    public static TQuantity ToUnit<TQuantity, TUnit>(this TQuantity quantity, TUnit unit)
+        where TQuantity : IQuantity<TQuantity, TUnit>
+        where TUnit : struct, Enum
+    {
+        return quantity.ToUnit(unit, UnitConverter.Default);
+    }
+
+    /// <inheritdoc cref="ToUnit{TQuantity,TUnit}(TQuantity,TUnit)" />
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="unit">The target unit.</param>
+    /// <param name="unitConverter">The converter to use.</param>
+    public static TQuantity ToUnit<TQuantity, TUnit>(this TQuantity quantity, TUnit unit, UnitConverter unitConverter)
+        where TQuantity : IQuantity<TQuantity, TUnit>
+        where TUnit : struct, Enum
+    {
+        return unitConverter.ConvertToUnit(quantity, UnitKey.ForUnit(unit));
+    }
+
     /// <summary>
     ///     Converts the specified quantity to a new quantity with a unit determined by the given <see cref="UnitSystem" />.
     /// </summary>
@@ -145,6 +239,28 @@ public static TQuantity ToUnit<TQuantity>(this TQuantity quantity, UnitSystem un
 #endif
     }
 
+    /// <summary>
+    ///     Gets the value of a quantity in the specified unit.
+    /// </summary>
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="unit">The target unit.</param>
+    /// <returns>The converted value.</returns>
+    public static double As(this IQuantity quantity, UnitKey unit)
+    {
+        return UnitConverter.Default.ConvertValue(quantity, unit);
+    }
+
+    /// <summary>
+    ///     Converts a quantity to the specified unit.
+    /// </summary>
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="unit">The target unit.</param>
+    /// <returns>The converted quantity.</returns>
+    public static IQuantity ToUnit(this IQuantity quantity, UnitKey unit)
+    {
+        return UnitConverter.Default.ConvertTo(quantity, unit);
+    }
+
     /// <summary>
     ///     Converts the specified quantity to a new quantity with a unit determined by the given <see cref="UnitSystem" />.
     /// </summary>
@@ -170,6 +286,19 @@ public static IQuantity ToUnit(this IQuantity quantity, UnitSystem unitSystem)
          return quantityInfo.From(quantity.As(unitKey), unitKey);
     }
 
+    /// <summary>
+    ///     Converts a quantity to the specified unit.
+    /// </summary>
+    /// <typeparam name="TUnit">The unit enum type.</typeparam>
+    /// <param name="quantity">The quantity to convert.</param>
+    /// <param name="unit">The target unit.</param>
+    /// <returns>The converted quantity.</returns>
+    public static IQuantity<TUnit> ToUnit<TUnit>(this IQuantity<TUnit> quantity, TUnit unit)
+        where TUnit : struct, Enum
+    {
+        return (IQuantity<TUnit>)UnitConverter.Default.ConvertTo(quantity, UnitKey.ForUnit(unit));
+    }
+
     /// <summary>
     ///     Converts the specified quantity to a new quantity with a unit determined by the given <see cref="UnitSystem" />.
     /// </summary>