.NET Exceptions – System.FormatException

Moving along through our in-depth .NET Exception Handling series, today we come across the System.FormatException. As the name implies, the System.FormatException is thrown in a wide variety of scenarios, yet they all revolve around providing an improperly formatted argument to a vast array of methods and API calls.

We’ll spend some time in this article exploring the System.FormatException in more detail, such as where it resides in the .NET exception hierarchy. We’ll also take a look at a few functional C# code samples that will illustrate how the System.FormatException might be thrown in some everyday code, so you can better plan for handling them yourself. Let’s get going!

The Technical Rundown

When Should You Use It?

Like many of the Exception classes within .NET that inherit directly from System.SystemException, the System.FormatException is quite broad and encompasses a great deal of potential format-related issues. In fact, there are far too many edge cases to go through them all here, let alone provide code examples, so we’ll just briefly list a few common scenarios that could lead to a System.FormatException:

  • Conversion attempts using Convert class methods in an attempt to change a string into another data type by passing an invalid string value.
  • DateTime class parse attempts that don’t conform to the expected culture-specific formatting patterns.
  • GUIDs that aren’t 32-hexadecimal digits.
  • Attempting to pass a format string to an object that implements the IFormattable interface, but where the format string isn’t one of the standard format strings.
  • Calling String.Format(), whereby the provided format string contains a greater number of indices than the number of insertion object arguments that were given (e.g. String.Format("{0:t} on {1:D}", DateTime.Now)).

There are many other possible scenarios to consider, so you are encouraged to check out the official documentation for all the details on the System.FormatException and see in which scenarios it might pop up.

For our code examples today we’ll be looking at two scenarios outlined above: Using methods of the Convert class with improper string values passed, and using an invalid format string for an IFormattable implementor object. As usual, we’ll start with the full code sample below, then walk through it in more detail afterward:

We begin with the ConvertStringToChar(string value) method, which does just as the name implies. As with all our example methods, we’re logging any caught System.FormatExceptions that may be thrown:

We start by declaring a name variable and then passing it to ConvertStringToChar(string value):

As you may be aware, the Convert.ToChar(string value) method requires that the passed string be only a single character long, so we end up throwing a System.FormatException:

Instead, we’ll try setting name equal to only the first character, then pass it a second time (this is a bit convoluted, since name.First() already converts itself to a char object):

Sure enough, this conversion works fine:

We also have a similar ConvertStringToBoolean(string value) method that, again, attempts just what the method name states:

To test this we’ll first start with a string value of "true", followed by a value of "truthy":

As it happens, Convert.ToBoolean(string value) only accepts values of "False", "false", "True", or "true", so while our first call succeeds, our second call throws another System.FormatException:

Our last example attempts to provide a format string to an object that implements IFormattable. In this case, the FormatDecimal(decimal value, string format) method tries to format the passed value using the passed format string, then returns the result:

To test this method we first declare the value variable, along with format using a valid standard numeric format string (c, in this case, which signifies a currency). For our second call we try using a numeric format string of Z, which is invalid:

As expected, our first call performs just as expected, while the second call throws yet another System.FormatException, informing us of the issue:

To get the most out of your own applications and to fully manage any and all .NET Exceptions, check out the Airbrake .NET Bug Handler, offering real-time alerts and instantaneous insight into what went wrong with your .NET code, along with built-in support for a variety of popular development integrations including: JIRA, GitHub, Bitbucket, and much more.