A Money value-object implementation in .NET
Tags: net, money, valueobject, nmoneys
Published: 2017-08-21 10:20:27

---
title: A Money value-object implementation in .NET
published: true
description: An introduction to NMoneys, a money value-object implementation that follows the ISO 4217 standard.
tags: .net, money, value-object, nmoneys
---

![money](https://thepracticaldev.s3.amazonaws.com/i/l2xgj1nktxkkb011u3x1.jpg)

Let's skin the proverbial cat by breaking out the title

# A money value-object

In this context "money" refers to a quantity that represents a mean of payment in an accepted currency. That is, a monetary quantity is made up of an "amount" that makes sense in the context of a given currency.
Remove the quantity of "five dollars" and saying you have "dollars" won't get you far when buying a car.
Likewise, remove the currency and the number alone makes little or no sense when declaring your wealth.

According to <a href="https://martinfowler.com/aboutMe.html" target="_blank">Martin Fowler</a> (author of the highly recommendable <a href="https://martinfowler.com/books/eaa.html" target="_blank">Patterns of Enterprise Application Architecture</a>, a <a href="https://martinfowler.com/eaaCatalog/valueObject.html" target="_blank">Value object</a> is:

> A small simple object whose equality isn't based on identity

Which is to say two value objects are equal is their values are equal.

A money value-object is, thus, a small (most likely immutable) type that represents a monetary quantity by specifying its amount and its currency and that allows meaningful and correct operations between instances.

## Why do we need a money value-object in .NET?

Short answer is _because there is none_.

Sufferers of <a href="http://wiki.c2.com/?PrimitiveObsession" target="_blank">primitive obsession</a> might use raw numbers for formatting. It is unfortunate that such capabilities are mixed up with interesting and complex stuff such as languages, cultures, regions, calendars,...
Using a raw numeric primitive and relying on cultural context might lead to dangerous misunderstandings: is this number in dollars, euros or is it the length of some random king's arm? And that is obviating the fact that a perfectly valid operation between two numbers, such as sum them up, might be totally incorrect as-is between two monetary quantities if they happen to be in different currencies.

We can discipline our way around with numbers, format providers and good naming but reality is, we are way better off encapsulating money rules and operations in a money type.

## The need of standardization

Money and countries are a sensitive topic and in order to agree what is what, that International Organization for Standardization _ISO_ helps by providing a list of current, accepted currencies and their alphabetic and numeric codes.

This list is active, with new currencies entering the list and old, deprecated currencies coming out and names changing.
Despite the efforts of Microsoft, there is a gap between what is currently accepted by the ISO and what is implemented in the .NET Framework, and framework releases and patches sometimes lag behind the current standard.

It is easier for a focused, smaller library to stay current than it is for a larger framework.

# NMoneys to the rescue

For the aforementioned reasons is that <a href="https://github.com/dgg/nmoneys" target="_blank">NMoneys</a> exists: to provide a money value-object Open Source implementation that follows the ISO 4217 standard.

The project is a veteran with a lot of dogfooding on its shoulders and I hope that it will get more exposure and help even more people that has helped so far.

![nmoneys](https://raw.githubusercontent.com/dgg/nmoneys/wiki/NMoneys_long.png)

Visit the <a href="https://github.com/dgg/nmoneys" target="_blank">project site</a>, read the <a href="https://github.com/dgg/nmoneys/wiki" target="_blank">documentation</a>, get its binaries via <a href="https://www.nuget.org/packages/NMoneys" target="_blank">NuGet</a> and <a href="https://github.com/dgg/nmoneys/wiki/Contribute" target="_blank">contribute</a> if you feel like it.

You can follow my personal <a href="https://dgondotnet.blogspot.dk/" target="_blank">blog</a> for <a href="https://dgondotnet.blogspot.dk/search/label/NMoneys" target="_blank">updates and new releases</a>.

Enjoy responsibly ;-)