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 6+ 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

| Package | Purpose | |---------|---------| | DevExpress.Document.Processor | Unit Conversion API (included in the package) |

.NET (6/7/8+)

dotnet add package DevExpress.Document.Processor

.NET Framework (4.6.2+)

Install-Package DevExpress.Document.Processor

Or add a direct reference to DevExpress.Docs.v25.2.dll.

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

Before You Start — Ask the Developer

Before generating code, ask these questions to avoid rework:

General Questions

1. Target framework: Are you using .NET 8+, .NET 6/7, 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, then call To{Unit}() to convert. QuantityValue 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 objects.

Key classes:

• QuantityValue (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 height = (5.0).Feet() + (4.0).Inches();
double meters = height.ToMeters().Value;   // explicit: use .Value
double meters2 = height.ToMeters();        // implicit: QuantityValue → 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](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 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 weight = (180.0).Pounds();
Console.WriteLine($"Weight: {weight.ToKilograms().Value:F2} kg");

// Temperature: Fahrenheit to Celsius and Kelvin
QuantityValue 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 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 (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\

| Property/Operator | Type | Description | |-------------------|------|-------------| | Value | double | Numeric value in the current unit | | implicit double | double | Implicit conversion — use directly in math/strings | | + / - | QuantityValue | Add or subtract same-category quantities | | * / / | QuantityValue | Multiply or divide by a scalar |

Units (static class)

| Property | Type | Description | |----------|------|-------------| | Units.Distance | DistanceUnitsConverter | Distance/length conversions | | Units.Mass | MassUnitsConverter | Mass/weight conversions | | Units.Temperature | TemperatureUnitsConverter | Temperature conversions | | Units.Area | AreaUnitsConverter | Area conversions | | Units.Volume | VolumeUnitsConverter | Volume conversions | | Units.Speed | SpeedUnitsConverter | Speed conversions | | Units.Metric | MetricUnitsConverter | Metric prefix conversions |

BaseUnitsConverter\.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 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 = (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

| Symptom | Cause | Solution | |---------|-------|----------| | Compile error: type Weight not found | Wrong type name | The enum is Mass, not Weight. Use QuantityValue and .Pounds(), .Grams() etc. | | Compile error: Distance.Kilometer not found | Enum member absent | Kilometer is not in the Distance enum. Use .Kilometers() extension method on a double instead. | | Compile error: Area.SquareKilometer not found | Enum member absent | SquareKilometer is not in the Area enum. Convert via Area.SquareMeter then divide/multiply by 1,000,000. | | Ambiguous extension method invocation | Conflicting namespace | Ensure only using DevExpress.UnitConversion; is present; remove conflicting using directives | | Incorrect conversion result | Wrong extension method | .Feet() creates US feet, .Meters() creates SI meters — double-check the method name | | Build error: type not found | Package not installed | Run dotnet add package DevExpress.Document.Processor | | License error at runtime | Missing DevExpress license | Register license per the DevExpress installation guide | | Version mismatch error | Mixed DX package versions | All DevExpress packages must use the same version | | Cannot add Distance + Mass | Type mismatch | Only add/subtract QuantityValue of the same T. Mix categories only after extracting .Value. |

Constraints & Rules

CRITICAL — follow these rules in every interaction:

1. Build verification: After making changes, verify the project builds with dotnet build. Check for errors before reporting success.
2. NuGet packages: Use only DevExpress.Document.Processor. Do not guess other package names.
3. Namespace imports: Always include using DevExpress.UnitConversion;. Never assume it exists.
4. Version consistency: All DevExpress packages must use the same version. Do not mix.
5. Correct enum name: The mass/weight category is Mass (not Weight). QuantityValue, not QuantityValue.
6. License: DevExpress requires a valid license. Remind the developer if they hit license-related build errors.
7. No destructive changes: Preserve existing code structure. Only add or modify what is necessary.
8. Framework detection: Check the project's .csproj for target framework. The API works on both .NET and .NET Framework with the same code.
9. Type safety: Only use +/- operators on QuantityValue instances with the same T. Never mix categories.

Using DevExpress Documentation MCP

If the DxDocs MCP server is available, use it to supplement this skill:

• Search: Use devexpress_docs_search with technology "Unit Conversion API" and your question.
• Fetch: Use devexpress_docs_get_content with a documentation URL to get full article content.

When to use MCP vs. built-in references:

• Built-in references: Getting started, common patterns, supported categories, troubleshooting.
• MCP search: Full list of extension methods for less common units (pressure, energy, force, magnetism, information), version-specific changes, or uncommon features.
• Always MCP for: Exact extension method names for units not listed here (e.g., pressure units like .MmHg(), .Pascals()).

---

Next Steps

Start with [Getting Started](references/getting-started.md) to install the package and run your first conversion, then explore specific categories through the examples above.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DevExpress
• Source: DevExpress/agent-skills
• License: MIT
• Homepage: https://www.devexpress.com

Install and usage instructions live in the source repository linked above.