Make an ASP.NET Core Controller API Culture-Sensitive with IValueProviderFactory

In the last article, "Are Your ASP.NET Core Routes and Query Strings Culture-Invariant?", we looked at a globalization issue that came up because ASP.NET Core model binding for route and query string data is culture-invariant. In that article, we solved the issue by making the route data culture-invariant, but we have another option: make the ASP.NET Core controller API culture sensitive.

IValueProviderFactory lets us use culture-sensitive route and query string data.

Note: This methodology applies to controller APIs only. I have not found an equivalent method that works with minimal APIs (but be sure to tell me if you know of one). For minimal APIs, use a culture-invariant URL.

The code for this article is available on GitHub: https://github.com/jeremybytes/aspnetcore-api-globalization.

Globalization Issue

Check out the previous article for a full description of the issue. For this article, we will go back to square one and show the basics of the globalization issue.

With the regional format settings on my machine set to United States English, the application runs fine.

  (From Controller Service) Sunset Tomorrow: 12/8/2024 4:26:50 PM
  (From Minimal API Service) Sunset Tomorrow: 12/8/2024 4:26:50 PM

But when I change the regional format to Icelandic, we get a runtime error.

If we debug to get the URL and run that manually, we see that the service returns an error:

Here is the URL and the results:

  http://localhost:8973/SolarCalculator/45,6382/-122,7013/2024-12-08

  {"results":null,"status":"ERROR"}

As a reminder, the 2 numeric route parameters represent latitude and longitude. Since we are using the Icelandic regional format, the comma (",") is used as a decimal separator. This is incorrectly parsed (and ignored) by the API. The result is that the latitude and longitude values are out of range.

If you want the full details, see the previous article.

IValueProviderFactory

A Microsoft Learn article (Globalization behavior of model binding route data and query strings) tells us what the problem is. But in addition to telling us that the model binding in this scenario is culture-invariant, it also tells how to make the model binding culture-sensitive -- by using IValueProviderFactory.

In short, we create custom value provider factories for route and query string data, then replace the default factories in the API startup.

Custom IValueProviderFactory

Here is the code for 2 custom value provider factories (in the GitHub repo CultureFactories.cs file):

  public class CultureQueryStringValueProviderFactory : IValueProviderFactory
  {
      public Task CreateValueProviderAsync(ValueProviderFactoryContext context)
      {
          ArgumentNullException.ThrowIfNull(context);

          var query = context.ActionContext.HttpContext.Request.Query;
          if (query?.Count > 0)
          {
              context.ValueProviders.Add(
                  new QueryStringValueProvider(
                      BindingSource.Query,
                      query,
                      CultureInfo.CurrentCulture));
          }

          return Task.CompletedTask;
      }
  }

  public class CultureRouteValueProviderFactory : IValueProviderFactory
  {
      public Task CreateValueProviderAsync(ValueProviderFactoryContext context)
      {
          ArgumentNullException.ThrowIfNull(context);

          context.ValueProviders.Add(
              new RouteValueProvider(
                  BindingSource.Path,
                  context.ActionContext.RouteData.Values,
                  CultureInfo.CurrentCulture));

          return Task.CompletedTask;
      }
  }

These classes create value providers that include culture information (set to CultureInfo.CurrentCulture) for the query string value provider and route value provider, respectively.

Replacing the Default Value Provider Factories

The last step is to replace the default value provider factories with the custom factories. This happens in the Program.cs file of the controller API.

We replace the existing AddControllers:

    builder.Services.AddControllers();

With one that takes an options delegate parameter:

  builder.Services.AddControllers(options =>
  {
      var index = options.ValueProviderFactories.IndexOf(
          options.ValueProviderFactories
              .OfType<QueryStringValueProviderFactory>()
              .Single());

      options.ValueProviderFactories[index] =
          new CultureQueryStringValueProviderFactory();

      index = options.ValueProviderFactories.IndexOf(
          options.ValueProviderFactories
              .OfType<RouteValueProviderFactory>()
              .Single());

      options.ValueProviderFactories[index] =
          new CultureRouteValueProviderFactory();
  });

This code finds the index of the existing value provider factory in the options and replaces it with the custom value provider factory (once for the query string and once for the route).

Working API

With the value provider factories in place, we can re-run the API using the same URL and get working results:

Here is the URL and results:

  http://localhost:8973/SolarCalculator/45,6382/-122,7013/2024-12-08

  {"results":{"sunrise":"07:38:51","sunset":"16:26:50","solar_noon":"12:02:50",
  "day_length":"08:47:58.5373487"},"status":"OK"}

The route parameters are still using the Icelandic regional format (45,6382 and -122,7013), but now we have valid results.

The application is using the current culture for the values when creating the route, and the API is using the current culture to read the route data.

And the application is back in a working state as well:

  (From Controller Service) Sunset Tomorrow: 8.12.2024 16:26:50
  (From Minimal API Service) Sunset Tomorrow: 8.12.2024 16:26:50

Two Approaches

Now that we have 2 approaches to solving the same globalization issue, which should we use? Here are my thoughts. I'd love to hear your thoughts as well.

In General: Culture-Invariant

I understand why route and query string data is culture-invariant by default. As stated in the documentation, this is to try to make URLs as "neutral" as possible to support the largest number of clients.

The implication of this is that now I feel like I need to specifically mark all of my API calls as culture-invariant since its possible that my application code could be running on a machine with different regional format settings.

I have not been doing this -- instead relying on the US-centric default. Going forward, I need to make sure that my API calls are appropriately culture-invariant.

For Specific Cases: Culture-Sensitive

For the specific scenario that brought this issue up, I'm leaning toward making the APIs culture-sensitive.

The scenario is that I have workshop lab files that run on a user's machine. Both the API calling code and the API itself are on the same machine. My inclination is to make sure that both ends use the current culture of the machine. This is what I assumed (very incorrectly) was happening and why the issue caught me off guard.

But I'm not completely set on this yet; it's just my initial inclination.

Wrap Up

For those of us in the US, we often forget about globalization issues. This is because we are the default culture -- even when we specify "neutral" culture (i.e., culture-invariant), it is still our culture.

Now that we are aware that route and query string data for APIs is culture-invariant, we need to take some action: either ensuring that our routes and query strings are culture-invariant or by adjusting the API itself.

Ultimately, it comes down to whether to put the onus on the client (API calling code) or the service (the API). Let me know your thoughts.

Happy Coding!

Are Your ASP.NET Core Routes and Query Strings Culture-Invariant?

In a recent workshop, I ran into an interesting issue with ASP.NET Core and globalization. One of the attendees was from Iceland, and she was getting errors when running an application hitting a local API. Later, I was able to hunt down the globalization issue, and it has to do with the way model binding works.

Model binding in ASP.NET Core for route and query string data is culture-invariant.

This caught me a bit off guard. I expected that the globalization settings on the computer would be used throughout the code. But because of the culture-invariant behavior of route and query string data in ASP.NET Core, things do not work that way.

Note: This specifically refers to model binding for route and query string data (i.e., data that is part of a URL). Model binding for form data is culture sensitive.

If you are biased toward United States English (as too many of us are), this issue does not come up locally. But if your API calls are made from non-US culture machines, you may run into issues if the routes or query strings are not specifically created as culture-invariant.

In this article, we'll take a look at making sure that our API calls are culture-invariant. In a future article, we'll look at how we can add a custom value provider that respects CultureInfo settings. (Update: Article is now available: Make an ASP.NET Core Controller API Culture-Sensitive with IValueProviderFactory.)

Source code for this article is available on GitHub: https://github.com/jeremybytes/aspnetcore-api-globalization.

The workshop code that brought this issue to light is available here: https://github.com/jeremybytes/vslive2024-orlando-workshop-labs.

Happy Path for US English

We'll start with the happy path. The scenario is that I need to get sunset information for my home automation software. The application calls a (local) service that provides sunset time based on latitude, longitude, and date. (For purposes of the sample code in the workshop, the service is run on the local machine. In the original implementation, this was a third-party service.)

Application Output

Running the application produces the following output.

  (From Controller Service) Sunset Tomorrow: 12/7/2024 4:26:56 PM
  (From Minimal API Service) Sunset Tomorrow: 12/7/2024 4:26:56 PM

This shows "tomorrow" sunset time as 4:26 p.m. (this is where I live in Vancouver, WA, USA). And since I am in the US, the date represents December 7, 2024.

API Call

Here is the API call that produces the sunset data:

Here is the URL:

    http://localhost:8973/SolarCalculator/45.6382/-122.7013/2024-12-07

And the JSON result:

  {"results":{"sunrise":"7:37:52 AM","sunset":"4:26:56
  PM","solar_noon":"12:02:24 PM","day_length":"08:49:03.8810000"},"status":"OK"}

The route in the URL has the latitude (45.6382), the longitude (-122.7013), and the date (2024-12-07).

The latitude and longitude values are culturally significant.

The URL / route is created in the code:

  string endpoint =
      $"SolarCalculator/{latitude:F4}/{longitude:F4}/{date:yyyy-MM-dd}";
  HttpResponseMessage response = 
      client.GetAsync(endpoint).Result;

The formatting on the latitude and longitude parameters specify that they should include 4 decimal places.

Changing Culture to Iceland

To duplicate the issue, I changed my computer's "Regional format" to Icelandic in the "Language & Region" settings (I'm using Windows 11).

This changes the number format to use a comma (",") for the decimal separator and a dot (".") for the thousands separator.

Re-running the application throws an error at this point. We can trace through the application to generate the URL and run it manually:

Here is the URL and the JSON result:

  http://localhost:8973/SolarCalculator/45,6382/-122,7013/2024-12-07

  {"results":null,"status":"ERROR"}

This shows the latitude value as "45,6382" and longitude as "-122,7013". These are the proper formats for the Icelandic regional format setting.

However, we see that the API now returns an error. For some reason, it does not work with these route parameters.

API Route Model Binding

It took a bit of debugging to find what was happening. Ultimately, I ended up in the HTTPGet code of the API controller.

Note: Minimal APIs exhibit this same behavior. This is not specific to Controller APIs.

Here is the endpoint:

    [HttpGet("{lat}/{lng}/{date}")]
    public SolarData GetWithRoute(double lat, double lng, DateTime date)
    {
        var result = SolarCalculatorProvider.GetSolarTimes(date, lat, lng);
        return result;
    }

When debugging into this method, I found that the "lat" and "lng" parameters did not have the values I expected:

  lat = 456382
  lng = -1227013
  date = (7.12.2024 00:00:00)

This is where I hit the unexpected. The decimal separator (",") from the route was not being used.

Route & Query Strings are Culture-Invariant

After much digging, I found a relevant section on the Microsoft Learn site (https://learn.microsoft.com/en-us/aspnet/core/mvc/models/model-binding?view=aspnetcore-9.0#globalization-behavior-of-model-binding-route-data-and-query-strings):

Globalization behavior of model binding route data and query strings
The ASP.NET Core route value provider and query string value provider:
o Treat values as invariant culture.
o Expect that URLs are culture-invariant.
In contrast, values coming from form data undergo a culture-sensitive conversion. This is by design so that URLs are shareable across locales.

Culture-invariant means US English (because the world revolves around the US </sarcasm>). So, the comma is not recognized as a decimal separator here and ends up being ignored.

The result in this code is that the values overflow latitude and longitude values (which range from -180 to +180). So the API returns an error result.

The sample code also has an HTTPGet that uses a query string rather than a route. When I was investigating the problem, I tried this endpoint and had the same issue as the endpoint that used route parameters. As noted in the documentation above, both route parameters and query string parameters are mapped the same way -- with invariant culture.

Creating a Culture-Invariant API Call

Based on what we know now, one solution is to make sure that the parameters of our API calls are culture-invariant.

Here is the revised calling code:

  string endpoint = string.Format(
                      CultureInfo.InvariantCulture, 
                      "SolarCalculator/{0:F4}/{1:F4}/{2:yyyy-MM-dd}",
                      latitude, longitude, date);

Note that we cannot use the default string interpolation like we had previously. There are ways to create a string that respects culture while using string interpolation, but I find it easier to fall back to String.Format. This is probably out of habit, but it's an approach that works. You can use whatever method you like to create a culture-invariant string.

Working Application with Icelandic Regional Format

Now that we have an invariant culture specified on the string, the URL will be formatted just like the original US English version that we started with (using a dot as the decimal separator).

Here is the resulting application output:

  (From Controller Service) Sunset Tomorrow: 7.12.2024 16:26:56
  (From Minimal API Service) Sunset Tomorrow: 7.12.2024 16:26:56

This output also shows the Icelandic general date format: day dot month dot year.

Another Alternative

Instead of using a culture-invariant route / query string, we can also update the service so that it is culture sensitive. How to do this is described in the same Microsoft Learn article mentioned above (https://learn.microsoft.com/en-us/aspnet/core/mvc/models/model-binding?view=aspnetcore-9.0#globalization-behavior-of-model-binding-route-data-and-query-strings).

I have done this as well. The general idea is that you create a custom IValueProviderFactory that parses the parameters based on the current culture (or other desired culture). You do this for both query string values and route values. Then in the "AddControllers" part of the API builder process, you replace the default route and query string value providers with the custom value providers. (Update: Article is now available: Make an ASP.NET Core Controller API Culture-Sensitive with IValueProviderFactory.)

This solution only works with Controller APIs. I have been unable to find a similar option for Minimal APIs.

The sample code has an implementation of this, and I'll go through it in a future article.

The Important Question

So the important question is "Are your ASP.NET Core route and query strings culture-invariant?" If not, you may need to take a look at them. You may not need to worry about it if you are using an unambiguous date format (like the year/month/day format used here). But if your parameters have decimals or thousands separators, then you will want to make sure that those parameters are represented in a culture-invariant way.

Wrap Up

Localization and globalization are important topics. I haven't touched on localization here (where we make sure that the text in our applications is available in other languages). In my particular situation (coding workshops), the workshops are conducted in English, and so the application text can also be in English.

But when it comes to globalization, folks use different number and date formats. I'm often conscious of date formats when I present outside of the US (since we have the worst of all "standard" date formats). But this is the first time I have run into an issue with globalization around a decimal separator.

I understand the desire to have URLs culture-invariant. But it also grates on me a bit. The idea of making the API culture sensitive seems like a better solution for my scenario. Stay tuned for the next article, and you can help me decide by telling me which option you prefer.

Happy Coding!

Trying and Failing with GitHub Copilot

Or, How Jeremy failed to create a Triangle Classifier with appropriate tests.

So, I spent about 2 hours trying to get GitHub Copilot (specifically GitHub Copilot chat within Visual Studio 2022) to create a function and test suite as described in The Art of Software Testing by Glenford J. Myers (1st edition, Wiley. & Sons, 1979).

I failed miserably.

In the end, I have a function that looks pretty close to what I was trying to get and a suite of unit tests that do not all pass.

If you would like to enjoy the output of my failure, feel free to check out the code on GitHub: https://github.com/jeremybytes/copilot-triangle-testing.

Goal

The beginning of The Art of Software Testing has a self-assessment test to see how good you are at testing a function. Here is the text (from p. 1):

Before beginning this book, it is strongly recommended that you take the following short test. The problem is the testing of the following program:

The program reads three integer values from a card. The three values are interpreted as representing the lengths of the sides of a triangle. The program prints a message that states whether the triangle is scalene, isosceles, or equilateral.

On a sheet of paper, write a set of test cases (i.e., specific sets of data) that you feel would adequately test this program. When you have completed this, turn the page to analyze your tests.

The next page has a set of 14 test cases including adequate test coverage for the success cases as well as correctly dealing with potentially invalid parameter sets (sets that could not make a valid triangle, parameters out of range, and others).

Since it is no longer 1979, I asked for a C# method with 3 parameters (not "integer values from a card") and requested the output be an enum (rather than "print[ing] a message").

Process

I got the initial function up pretty quickly (including checks for out-of-range parameters and invalid parameter sets). And I spent a lot longer on the test suite. GitHub Copilot created the initial tests, and then I kept asking for adjustments for edge cases, out of range parameters, and invalid parameter sets. In the end, the tests do not pass. Some of the parameter sets are invalid (when they are meant to be out-of-range examples). I tried getting GitHub Copilot to reorder things so that the proper exceptions are tested for based on the parameter sets, but it was beyond its (or my) abilities. Eventually, GitHub Copilot kept providing the same code over and over again.

Note: In the initial request to create the function, GitHub Copilot used double for the parameters (rather than int as noted in the book). I left this since part of the testing scenarios in the book included non-integer values.

End State

The tests do not pass, and with the amount of time I spent trying to get GitHub Copilot to build what I wanted, I could have done it multiple times manually.

I could fix the code and tests manually, but this was to see exactly how useful GitHub Copilot is in a fairly straight-forward scenario. The answer is that it was just frustrating for me.

Feel free to tell me "you're doing it wrong", I've heard that before. But I would rather work with an intern that was brand new to programming that try to coerce GitHub Copilot into generating what I want.

The Code

Anyway, the code is in this repository if you're interested in looking at the final product (or more correctly, the code in its incomplete state when I finally gave up and had to ask myself how much electricity and clean water were used for this experiment).

I'm putting this out as something to point to; I'm not looking for corrections or advice at this point. (If I personally know you and you want to chat about it, feel free to contact me through the normal channels.)

Update: Cursory Analysis

So, I couldn't leave the code alone, so I went back a few days later to take a look at some of the issues.

The problem with using double

Let's start with a failing test:

    [Theory]
    [InlineData(1.1, 2.2, 3.3)] // Non-integer values
    // other test cases removed
    public void ClassifyTriangle_InvalidTriangles_ThrowsArgumentException(double side1, double side2, double side3)
    {
        // Arrange
        var classifier = new TriangleClassifier();

        // Act & Assert
        var exception = Assert.Throws<ArgumentException>(() => classifier.ClassifyTriangle(side1, side2, side3));
        Assert.Equal("The given sides do not form a valid triangle.", exception.Message);
    }

This particular test makes sure that the side lengths form a valid triangle. Adding any 2 sides together needs to be greater than the 3rd side. So, for example, lengths of 1, 2, 3 would be invalid because 1 + 2 is not greater than 3.

At first glance, the test case above (1.1, 2.2, 3.3) seems okay: 1.1 + 2.2 is not greater than 3.3. But when we look at the actual test that runs (and fails), we see the problem:

TriangleTests.TriangleClassifierTests.ClassifyTriangle_InvalidTriangles_ThrowsArgumentException(side1: 1.1000000000000001, side2: 2.2000000000000002, side3: 3.2999999999999998)

Because of the imprecision of the double type, adding side1 and side2 is greater than side3, so it does not throw the expected exception.

One answer to this is to change the double types to decimal types. This would ensure that the values of 1.1, 2.2, and 3.3 are precise.

Incorrect Overflow Check

Another strange part of the code is checking for overflow values. Here's the generated code:

    // Check for potential overflow in addition
    if (side1 > double.MaxValue - side2 || side1 > double.MaxValue - side3 || side2 > double.MaxValue - side3)
    {
        throw new ArgumentOutOfRangeException("Sides are too large.");
    }

The generated comment says that it is checking for potential overflow in addition; however, the conditions do not reflect that. Instead, they use MaxValue with subtraction. This is just weird. This code would not detect an overflow.

Tests for Overflow Check

Even stranger than the code that checks for overflow are the test cases for that code:

    [Theory]
    [InlineData(double.MaxValue / 2, double.MaxValue / 2, double.MaxValue / 2)] // Edge case: large double values
    [InlineData(double.MaxValue / 2, double.MaxValue / 2, 1)] // Edge case: large double values with a small side
    [InlineData(double.MaxValue / 2, 1, 1)] // Edge case: large double value with two small sides
    [InlineData(double.MinValue, double.MinValue, double.MinValue)] // Edge case: minimum double values
    [InlineData(double.MinValue, double.MinValue, -1)] // Edge case: minimum double values with a small negative side
    [InlineData(double.MinValue, -1, -1)] // Edge case: minimum double value with two small negative sides
    public void ClassifyTriangle_OverflowValues_ThrowsArgumentOutOfRangeException(double side1, double side2, double side3)
    {
        // Arrange
        var classifier = new TriangleClassifier();

        // Act & Assert
        var exception = Assert.Throws<ArgumentOutOfRangeE>ception>(() => classifier.ClassifyTriangle(side1, side2, side3));
        Assert.Equal("Sides are too large.", exception.ParamName);
    }

Every one of these test cases fails. This was after I asked GitHub Copilot chat to fix the failing tests. It said OK and then updated the test cases to the ones shows above.

Looking at the first case ("MaxValue / 2" for all 3 sides), This would not be expected to overflow double. In the valid triange check (noted previously), any 2 sides are added together. In theory, that means that adding any 2 of these sides would result in the MaxValue (i.e., not an overflow value). For this test case, no exception is thrown, so the test fails.

The test cases that use MinValue are completely invalid for this code. The code is checking for overflow (theoretically) but not for underflow. The test cases with MinValue all fail because the sides are less than or equal to zero (which is a separate check in the method). So these test cases will always fail because the wrong exception is thrown.

Updated Summary

What really worries me about the code is that my cursory analysis only looks at the failing tests in the test suite. This has led me to find invalid test cases and also code that doesn't do what it thinks it is doing.

So what if I were to dig through all of the passing tests? (There are 36 of them.) I expect that I will find the same issues: invalid test cases that lead to code that doesn't do what it thinks it does.

And that's the problem. Without any trust at all in the code, this is pretty useless. The last thing I need as part of my development process is a random excrement generator.

Happy Coding!