devexpress/agent-skills/devexpress-office-file-api-unit-conversion

DevExpress Unit Conversion API

A lightweight .NET library for converting between metric and US customary units of measurement using a type-safe fluent API. Supports distance, mass, temperature, area, volume, speed, and metric prefix conversions. The API requires no external dependencies beyond the DevExpress.Document.Processor NuGet package and works identically on .NET 8+ and .NET Framework 4.6.2+.

When to Use This Skill

Use this skill when you need to:

• Convert distances or lengths (meters, feet, miles, kilometers, inches, yards, nautical miles)
• Convert mass/weight values (grams, kilograms, pounds, ounces, metric tons)
• Convert temperatures (Celsius, Fahrenheit, Kelvin)
• Convert area measurements (square meters, square feet, acres, hectares, square miles)
• Convert volumes (liters, gallons, cubic meters, cubic feet, fluid ounces, pints, quarts)
• Convert speeds (km/h, m/s, mph, knots, feet per second)
• Convert between metric prefixes (kilo, mega, milli, micro, etc.)
• Combine unit values with arithmetic (e.g., 5 feet + 4 inches, then convert to meters)
• Build type-safe unit-aware calculations without manual conversion factors

Prerequisites & Installation

NuGet Packages

.NET (8/9/10+)

dotnet add package DevExpress.Document.Processor

.NET Framework (4.6.2+)

Install-Package DevExpress.Document.Processor

Or add a direct reference to DevExpress.Docs.v26.1.dll.

Important: All DevExpress packages in a project must share the same version number. A valid DevExpress license is required.

Package Versions

Unless the user explicitly requests a specific version, always target the latest DevExpress release (v26.1 at the time of writing). dotnet add package <PackageName> without --version installs the latest stable version — prefer this form. Never pin an older version in project files, Dockerfiles, or CI/CD pipelines unless the user asks for it. This is especially important in integration scenarios (Docker, cloud deployments). All DevExpress.* packages in a project must share the same version.

Before You Start — Ask the Developer

If the host agent has a structured question-asking tool available, use it to ask these questions one at a time with clear options — for example, Claude Code's AskUserQuestion tool or GitHub Copilot's askQuestions tool. If no such tool is available, ask the questions directly in the chat response before generating code.

Before generating code, ask these questions to avoid rework:

General Questions

1. Target framework: Are you using .NET 8+ or .NET Framework 4.x?
2. New or existing project?: Creating new or adding to existing?
3. Hosting model: Console app, ASP.NET Core, Blazor, MAUI, WinForms, or something else?

Unit Conversion-Specific Questions

1. Measurement category: Which category? (length / weight / temperature / area / volume / speed / metric prefix)
2. Conversion direction: Metric to US, US to metric, between metric prefixes, or both directions?

Rule: If the developer's answer is ambiguous or missing, ask before generating code. Do not guess.

Component Overview

The Unit Conversion API provides two usage patterns:

• Fluent extension methods on numeric types (double, int, float) — create a QuantityValue<T>, then call To{Unit}() to convert. QuantityValue<T> implicitly converts to double, so you can use it directly in arithmetic or string formatting.
• Static converter classes accessed via Units.* — call .Convert(value, fromUnit, toUnit) for direct scalar conversion without creating QuantityValue<T> objects.

Key classes:

• `QuantityValue<T>` (struct) — holds a value in a specific unit. Supports +, -, *, / operators. Implicitly converts to double.
• `Units` (static class) — entry point for converter instances: Units.Distance, Units.Mass, Units.Temperature, Units.Area, Units.Volume, Units.Speed, Units.Metric.
• `Distance`, `Mass`, `Temperature`, `Area`, `Volume`, `Speed`, `MetricPrefix` — enums listing available unit values for each category.
• `DistanceUnitsConverter`, `MassUnitsConverter`, etc. — converter classes returned by Units.* properties.

Core Entry Point — Fluent API

using DevExpress.UnitConversion;
 
// Combine feet and inches, then convert to meters
QuantityValue<Distance> height = (5.0).Feet() + (4.0).Inches();
double meters = height.ToMeters().Value;   // explicit: use .Value
double meters2 = height.ToMeters();        // implicit: QuantityValue<T> → double
Console.WriteLine($"Height: {meters:F3} m");

Core Entry Point — Units.Convert() API

using DevExpress.UnitConversion;
 
// Convert 100 feet to meters directly
double result = Units.Distance.Convert(100.0, Distance.Foot, Distance.Meter);
 
// Convert 100°C to Fahrenheit
double fahrenheit = Units.Temperature.Convert(100.0, Temperature.Celsius, Temperature.Fahrenheit);
 
// Convert metric prefix: 5 km → m  (Kilo → None)
double meters = Units.Metric.Convert(5.0, MetricPrefix.Kilo, MetricPrefix.None);

Documentation & Navigation Guide

Getting Started

Refer to references/getting-started.md

When you need to:

• Install the NuGet package and set up the namespace
• Perform your first conversion (distance, weight, temperature)
• Understand both fluent and Units.Convert() patterns
• See all measurement categories with one example each
• Combine values with arithmetic operators

Quick Start Example

using DevExpress.UnitConversion;
 
// Distance: 5 feet 11 inches to meters
QuantityValue<Distance> height = (5.0).Feet() + (11.0).Inches();
Console.WriteLine($"Height: {height.ToMeters().Value:F3} m ({height.ToCentimeters().Value:F1} cm)");
 
// Mass: pounds to kilograms
QuantityValue<Mass> weight = (180.0).Pounds();
Console.WriteLine($"Weight: {weight.ToKilograms().Value:F2} kg");
 
// Temperature: Fahrenheit to Celsius and Kelvin
QuantityValue<Temperature> bodyTemp = (98.6).Fahrenheit();
Console.WriteLine($"Body temp: {bodyTemp.ToCelsius().Value:F1}°C / {bodyTemp.ToKelvin().Value:F2} K");
 
// Area: 25 m² to square feet
QuantityValue<Area> room = (25.0).SquareMeters();
Console.WriteLine($"25 m² = {room.ToSquareFeet().Value:F2} ft²");
 
// Speed: m/s to mph
double mph = Units.Speed.Convert(30.0, Speed.MetersPerSecond, Speed.MilesPerHour);
Console.WriteLine($"30 m/s = {mph:F2} mph");
 
// Metric prefix: 5 kilo → mega
double mega = Units.Metric.Convert(5.0, MetricPrefix.Kilo, MetricPrefix.Mega);
Console.WriteLine($"5 kilo = {mega} mega");

What This Does

Demonstrates the two API patterns: fluent extension methods returning QuantityValue<T> (distance, mass, temperature) and direct scalar conversion via Units.*.Convert() (speed, metric prefix). Both patterns work identically on .NET and .NET Framework.

Key Properties & API Surface

QuantityValue\<T\>

Units (static class)

BaseUnitsConverter\<T\>.Convert()

double Convert(double value, T from, T to)      // single value
void   Convert(double[] values, T from, T to)   // in-place array conversion

Distance Enum Values (most common)

Distance.Meter, Distance.Foot, Distance.Inch, Distance.Yard, Distance.MileStatute, Distance.MileNautical, Distance.Kilometer (via MetricPrefix), Distance.Angstrom

Note: Kilometer is not a direct Distance enum value. Use the MetricPrefix converter or the .Kilometers() extension method which internally handles the prefix.

Area Enum Values

Area.SquareMeter, Area.SquareMile, Area.SquareMileNautical, Area.Hectare, Area.SquareFoot, Area.SquareInch, Area.SquareYard, Area.AcreInternational, Area.AcreStatute, Area.Are, Area.Morgen

IMPORTANT — `Area.SquareKilometer` does not exist in this enum.

To convert to or from square kilometers, convert via Area.SquareMeter first, then divide or multiply by 1,000,000:

```csharp

// 2.5 square miles → square kilometers

double squareMeters = Units.Area.Convert(2.5, Area.SquareMile, Area.SquareMeter);

double squareKm = squareMeters / 1_000_000.0;

Console.WriteLine($"2.5 sq mi = {squareKm:F4} km²");

// 10 km² → square miles

double sqMiles = Units.Area.Convert(10.0 * 1_000_000.0, Area.SquareMeter, Area.SquareMile);

Console.WriteLine($"10 km² = {sqMiles:F4} sq mi");

```

Mass Enum Values

Mass.Gram, Mass.Pound, Mass.Ounce, Mass.Ton, Mass.TonImperial, Mass.Stone, Mass.Slug

Note: Kilogram is not a direct Mass enum value in Units.Mass.Convert(). Use the fluent .Kilograms() extension method, or Units.Metric.Convert(value, MetricPrefix.None, MetricPrefix.Kilo) after getting grams.

Temperature Enum Values

Temperature.Celsius, Temperature.Fahrenheit, Temperature.Kelvin, Temperature.Rankine, Temperature.Reaumur

Speed Enum Values

Speed.MetersPerHour, Speed.MetersPerSecond, Speed.MilesPerHour, Speed.Knot, Speed.KnotAdmiralty

MetricPrefix Enum Values

MetricPrefix.Tera, MetricPrefix.Giga, MetricPrefix.Mega, MetricPrefix.Kilo, MetricPrefix.Hecto, MetricPrefix.Deca, MetricPrefix.None, MetricPrefix.Deci, MetricPrefix.Centi, MetricPrefix.Milli, MetricPrefix.Micro, MetricPrefix.Nano, MetricPrefix.Pico, MetricPrefix.Femto, MetricPrefix.Atto

Common Patterns

Fluent Conversion (simple)

// 100 meters to feet
double feet = (100.0).Meters().ToFeet().Value;
Console.WriteLine($"100 m = {feet:F2} ft");   // 328.08 ft

Fluent Conversion (compound)

// 6 feet 2 inches to centimeters
QuantityValue<Distance> height = (6.0).Feet() + (2.0).Inches();
Console.WriteLine($"6'2\" = {height.ToCentimeters().Value:F1} cm");   // 187.9 cm

Direct Scalar Conversion

// 100°C to Fahrenheit — no QuantityValue needed
double f = Units.Temperature.Convert(100.0, Temperature.Celsius, Temperature.Fahrenheit);
Console.WriteLine($"100°C = {f:F1}°F");   // 212.0°F

Batch Array Conversion

// Convert an array of values in-place
double[] distances = { 1.0, 5.0, 10.0, 42.195 };
Units.Distance.Convert(distances, Distance.Meter, Distance.Foot);
// distances[] now contains feet

Metric Prefix Conversion

// Convert 760 mmHg to hectopascals using MetricUnitsConverter
QuantityValue<Pressure> pressure = (760.0).MmHg();
double pascals = pressure.ToPascals();
var prefixConverter = new MetricUnitsConverter();
double hPa = prefixConverter.Convert(pascals, MetricPrefix.None, MetricPrefix.Hecto);
Console.WriteLine($"760 mmHg = {hPa:F1} hPa");

Volume Conversion

double gallons = Units.Volume.Convert(10.0, Volume.Liter, Volume.Gallon);
Console.WriteLine($"10 L = {gallons:F3} US gallons");

Troubleshooting