单位转换实践：深入解析 Units.NET

摘要

在现代软件开发中，准确处理不同单位的转换是一个常见而复杂的需求。无论是处理温度、长度、重量还是其他物理量，都需要可靠的单位转换机制。本文将深入介绍 Units.NET 库，展示如何在 .NET 应用中优雅地处理单位转换。

基础配置

首先，通过 NuGet 安装 Units.NET：

<PackageReference Include="UnitsNet" Version="5.x.x" />

实战示例：天气 API

基础模型定义

public record WeatherForecast(
    Temperature Temperature,
    DateTime Date,
    string Summary
);

public record WeatherResponse(
    string DisplayValue,
    DateTime Date,
    string Summary
);

API 端点实现

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weather", (string? unit) =>
{
    var forecasts = Enumerable.Range(1, 5).Select(index =>
    {
        // 创建基础温度（摄氏度）
        var tempC = Temperature.FromDegreesCelsius(Random.Shared.Next(-20, 55));
        // 根据请求的单位进行转换
        var temp = unit?.ToLowerInvariant() switch
        {
            "f" or "fahrenheit" => tempC.ToUnit(TemperatureUnit.DegreeFahrenheit),
            "k" or "kelvin" => tempC.ToUnit(TemperatureUnit.Kelvin),
            _ => tempC
        };

        return new WeatherForecast(
            Temperature: temp,
            Date: DateTime.Now.AddDays(index),
            Summary: summaries[Random.Shared.Next(summaries.Length)]
        );
    })
    .ToArray();

    return forecasts.Select(f => new WeatherResponse(
        Date: f.Date,
        Summary: f.Summary,
        DisplayValue: f.Temperature.ToString("F2") //控制输出的数字为两位小数
    ));
})
.WithName("GetWeatherForecast");

当请求的units单位不同时，将输出相同温度的不同单位表示：

单位相互转换

public static class UnitConverter
{
    public static Temperature ConvertTemperature(
        double value, 
        string fromUnit, 
        string toUnit)
    {
        var temperature = fromUnit.ToLowerInvariant() switch
        {
            "c" => Temperature.FromDegreesCelsius(value),
            "f" => Temperature.FromDegreesFahrenheit(value),
            "k" => Temperature.FromKelvins(value),
            _ => throw new ArgumentException($"Unsupported unit: {fromUnit}")
        };

        return toUnit.ToLowerInvariant() switch
        {
            "c" => temperature.ToUnit(TemperatureUnit.DegreeCelsius),
            "f" => temperature.ToUnit(TemperatureUnit.DegreeFahrenheit),
            "k" => temperature.ToUnit(TemperatureUnit.Kelvin),
            _ => throw new ArgumentException($"Unsupported unit: {toUnit}")
        };
    }
}

数学运算支持

Units.NET 支持各种数学运算，使得单位计算变得简单：

public class UnitCalculations
{
        public static Speed CalculateSpeed(Length distance, Duration time)
        {
            return distance / time;
        }

        public static Acceleration CalculateAcceleration(Speed initialSpeed, Speed finalSpeed, Duration time)
        {
            return (finalSpeed - initialSpeed) / time;
        }

        public static Energy CalculateKineticEnergy(Mass mass, Speed velocity)
        {
            double massValue = mass.Kilograms;
            double velocityValue = velocity.MetersPerSecond;
            double energyValue = 0.5 * massValue * velocityValue * velocityValue;
            return Energy.FromJoules(energyValue);
        }
}

// 使用示例
var distance = Length.FromKilometers(100);
var time = Duration.FromHours(2);
var speed = UnitCalculations.CalculateSpeed(distance, time);
Console.WriteLine($"Speed: {speed.ToUnit(SpeedUnit.KilometerPerHour)}");

代码执行后，控制台将输出：Speed: 50 km/h

文化本地化支持

var usEnglish = new CultureInfo("en-US");
var russian = new CultureInfo("ru-RU");
var oneKg = Mass.FromKilograms(1);
// ToString() 使用 CurrentCulture 进行缩写语言和数字格式化。这与 .NET Framework 的行为一致，
// 因为 DateTime.ToString() 使用 CurrentCulture 处理整个字符串，可能是因为将英文日期格式与俄文月份名称混合在一起可能会令人困惑。
CultureInfo.CurrentCulture = russian;
string kgRu = oneKg.ToString(); // "1 кг"

// 使用特定文化和自定义字符串格式模式的 ToString()
string mgUs = oneKg.ToUnit(MassUnit.Milligram).ToString(usEnglish); // "unit: mg, value: 1.00"
string mgRu = oneKg.ToUnit(MassUnit.Milligram).ToString(russian); // "unit: мг, value: 1,00"

Console.WriteLine(mgUs);
Console.WriteLine(mgRu);
// 从字符串解析测量值
Mass kg = Mass.Parse("1.0 kg", usEnglish);

// 从字符串解析单位，一个单位可以有多个缩写
RotationalSpeedUnit rpm1 = RotationalSpeed.ParseUnit("rpm"); // RotationalSpeedUnit.RevolutionPerMinute
RotationalSpeedUnit rpm2 = RotationalSpeed.ParseUnit("r/min");  // RotationalSpeedUnit.RevolutionPerMinute

// 获取单位的默认缩写，如果在 Length.json 中为 Kilogram 单位定义了多个缩写，则获取第一个
string kgAbbreviation = Mass.GetAbbreviation(MassUnit.Kilogram); // "kg"

控制台将输出不同文化设置下的标准单位

1000000 mg
1000000 мг

结论

Units.NET 是一个强大而灵活的单位转换库，它不仅简化了单位转换的实现，还提供了丰富的功能支持。通过使用 Units.NET，开发者可以专注于业务逻辑，而不必担心单位转换的复杂性。无论是构建天气 API、物流系统还是科学计算应用，Units.NET 都是处理单位转换的理想选择。