Convertir appsettings.json a objeto y utilizarlo correctamente en .NET

En este tutorial trataremos dos puntos importantes sobre el fichero appsettings.json y los archivos de configuración de .NET:

Cómo convertir appsettings.json a un objeto de forma sencilla para poder utilizar la configuración en nuestra aplicación de .NET.
Guía completa sobre cómo utilizar correctamente los archivos de configuración en .NET para conseguir un desarrollo eficiente, cómodo, mantenible y evitar futuros problemas.

A lo largo de mi trayectoria profesional me he encontrado con determinadas prácticas que, aunque funcionan, a la larga son negativas para el desarrollo de aplicaciones. Esta guía paso a paso tiene como objetivo darte una serie de recomendaciones y consejos para que los utilices en tus proyectos de .NET y consigas los siguientes puntos:

Desarrollo eficiente de aplicaciones, es decir, que añadir, eliminar o modificar propiedades de la configuración sea un proceso sencillo, rápido y cómodo.
Evitar errores en tus aplicaciones, dependiendo de cómo se hagan las cosas tendremos más o menos riesgo de que al leer de la configuración se produzcan errores de ejecución. Intentaremos minimizar este punto al máximo.

Para conseguir todos los puntos anteriores, de forma resumida, mi recomendación es que utilices un único objeto que represente toda la configuración y que cumpla con los siguientes puntos:

Solo debe existir una clase C# y un objeto que represente la configuración completa, no varios. Esto significa que, si tenemos varias subclases dentro de la configuración, éstas estarán dentro de la clase C# unificada, no serán independientes.
Solo se convierte de appsettings.json al objeto C# una única vez, no varias. Lo anterior se traduce en que no podemos leer propiedades o secciones concretas del appsettings.json, se lee y se convierte el fichero solo una vez y después se reutiliza en el resto de la aplicación.
Para utilizar y leer la configuración en nuestra aplicación la pasaremos a través de inyección de dependencias a las clases y métodos de nuestro proyecto. Este punto es opcional pero altamente recomendable.

Proyecto de ejemplo con código base

Para ilustrar los pasos de esta guía sobre los ficheros de configuración en .NET utilizaremos un nuevo proyecto de consola .NET, aunque este tutorial se puede aplicar a cualquier tipo de proyecto .NET con C# como, por ejemplo, un API o una aplicación MVC.

El motivo por el que elijo este tipo de proyecto es porque es el único que, por defecto y a día de hoy, no trae nada preconfigurado para tratar el fichero appsettings.json. Esto nos permitirá empezar completamente desde cero y aprender todos los pasos necesarios.

Si no sabes cómo crear un proyecto de consola C# desde Visual Studio te dejo por aquí los pasos necesarios:

Abre Visual Studio y selecciona «Create new project».
Dale un nombre descriptivo y pulsa sobre «Next».
Selecciona el framework, en este caso utilizaremos «.NET 8»; pulsa sobre «Create».
Ejecuta el proyecto y verifica que funciona correctamente:

Proyecto ejemplo con codigo base para appsettings json

Crear archivo appsettings.json para almacenar configuración

Una vez que hemos creado el proyecto .NET es momento de crear nuestro archivo de configuración appsettings.json.

El primer paso consiste en añadir el fichero al proyecto, click derecho, «Add», «New Item». Selecciona cualquier tipo de fichero y, en el nombre, escribe appsettings.json. Es importante utilizar este nombre para seguir el estándar de .NET y crearlo en la raíz del proyecto, aunque podríamos llamarle de otra manera o crearlo en cualquier otro lugar.

En segundo lugar asegúrate de que, en las propiedades del fichero o bien en el .csproj, tienes establecida la propiedad CopyToOutputDirectory al valor Always, de lo contrario tendrás un error cuando publiques la aplicación de consola y ésta intente acceder al fichero porque no lo va a encontrar:

Finalmente, como último paso de este apartado, rellena tu fichero de configuración con las propiedades y valores que necesites. A continuación te adjunto un ejemplo completo de appsettings.json con propiedades simples y complejas:

{
  "ExampleString": "ExampleStringValue",
  "ExampleInt": 3,
  "ExampleObject": {
    "Property1": "Value1",
    "Property2": 42
  },
  "ExampleStringList": [
    "String1",
    "String2",
    "String3"
  ],
  "ExampleObjectList": [
    {
      "Header": {
        "Title": "Header1",
        "Description": "Description1"
      },
      "Body": {
        "Content": "Body1",
        "Details": 100.15
      }
    },
    {
      "Header": {
        "Title": "Header2",
        "Description": "Description2"
      },
      "Body": {
        "Content": "Body2",
        "Details": 200.25
      }
    }
  ]
}

Diseñar clase C# para representar appsettings.json

Si lo que queremos es convertir el fichero appsettings.json a un objeto es obvio que el siguiente paso consiste en diseñar y crear la clase C# que va a representar nuestro fichero de configuración en la raiz del proyecto, de hecho, este paso se podría hacer antes que el apartado anterior, es cuestión de gustos.

A continuación tienes el ejemplo completo de la clase C# correspondiente al json que hemos creado en la sección anterior:

namespace AppSettingsNetTutorial
{
    public class Config
    {
        public string ExampleString { get; set; }
        public int ExampleInt { get; set; }
        public ExampleObject ExampleObject { get; set; }
        public List<string> ExampleStringList { get; set; }
        public List<ExampleObjectListItem> ExampleObjectList { get; set; }
    }

    public class ExampleObject
    {
        public string Property1 { get; set; }
        public int Property2 { get; set; }
    }

    public class ExampleObjectListItem
    {
        public Header Header { get; set; }
        public Body Body { get; set; }
    }

    public class Header
    {
        public string Title { get; set; }
        public string Description { get; set; }
    }

    public class Body
    {
        public string Content { get; set; }
        public double Details { get; set; }
    }
}

Ten en cuenta que los nombres de las clases pueden tener cualquier valor (como por ejemplo ExampleObject y ExampleObjectListItem) pero, los nombres de las propiedades (por ejemplo Property1 y Property2), deben coincidir exactamente con la clave que tengas en el fichero appsettings.json.

Además, como consejo o advertencia, intenta que esta clase sea lo más sencilla posible y evita cosas complejas o innecesarias como las herencias, con ello evitarás errores a la hora de convertir el appsettings.json a un objeto.

Instalar paquetes NuGet necesarios para convertir

El siguiente paso consiste en instalar los paquetes NuGet para convertir a objeto C# el fichero appsettings.json.

Para ello simplemente haz click derecho en tu proyecto o solución a través de Visual Studio y selecciona la opción «Manage NuGet Packages». Dentro del administrador ve a la pestaña de «Browse» y busca e instala la última versión de los siguientes paquetes:

Microsoft.Extensions.Configuration.Json
Microsoft.Extensions.Configuration.Binder

En último lugar añadelos a tu clase Program a través de la instrucción using:

using Microsoft.Extensions.Configuration;

internal class Program
{
    ...
}

Como alternativa al gestor de paquetes NuGet puedes añadir las siguientes líneas a tu fichero .csproj:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.7" />
  <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.7" />
</ItemGroup>

Código para convertir appsettings.json a objeto C#

Finalmente hemos llegado a la parte más importante del tutorial, el punto donde convertiremos el fichero appsettings.json a un objeto C# a través de código, para ello existen dos alternativas, Get vs Bind:

Método Get, más seguro y restrictivo. En el caso de que existan errores en el JSON este método lanzará mas excepciones que Bind, esto puede ser una ventaja o no según el uso que le quieras dar.
Método Bind, más flexible y tolerante a errores. De manera opuesta al anterior, si existen errores leves en el JSON, inicializa sus propiedades al valor por defecto. De nuevo, esto puede ser una ventaja o un inconveniente según sea tu caso de uso.

Otra diferencia de Get vs Bind, además de lo anterior, es que Get crea un objeto completamente nuevo a partir del fichero appsettings.json mientras que Bind lo que hace es rellenar un objeto existente con lo que haya en appsettings.json. Esto podemos verlo de dos maneras, puede ser una desventaja ya que si rellenamos un objeto existente con los valores de la configuración pueden quedar «valores sucios», esto es un riesgo; sin embargo, si realmente necesitamos esta funcionalidad de rellenar un objeto creado previamente, solo nos la puede proporcionar Bind y sería una ventaja respecto a Get.

Sea cual sea la opción elegida, como primer paso deberás convertir tu clase Program.cs al estilo main ya que, por defecto, suele venir sin este formato:

using AppSettingsNetTutorial;
using Microsoft.Extensions.Configuration;

internal class Program
{
    private static void Main(string[] args)
    {
        ...
    }
}

Como segundo paso deberás crear un ConfigurationBuilder para que lea del fichero appsettings.json dentro del método Main anterior:

var build = new ConfigurationBuilder()
.AddJsonFile("appsettings.json")
.Build();

El tercer lugar tienes que utilizar el método Get o Bind teniendo en cuenta que tienen códigos diferentes para realizar la conversión:

// Alternative 1
var config1 = build.Get<Config>();

// Alternative 2
var config2 = new Config();
build.Bind(config2);

Y finalmente te recomiendo que realices pruebas para verificar que tus objetos están rellenos con los valores del JSON:

// Output
Console.WriteLine($"config1: {config1?.ExampleObjectList.FirstOrDefault()?.Header.Description}");
Console.WriteLine($"config2: {config2.ExampleObjectList.FirstOrDefault()?.Header.Description}");

El código completo para convertir a un objeto C# desde appsettings.json puedes encontrarlo en el repositorio de GitHub enlazado.

Utiliza inyección de dependencias para la configuración

Aunque este paso es opcional, es altamente recomendable que utilices inyección de dependencias en tu aplicación de consola para enviar el objeto de la configuración a todas las clases y métodos que tengas. Si quieres conocer cómo hacerlo puedes consultar el tutorial enlazado.

Utilizar inyección de dependencias te permitirá, entre otras cosas, mantener el código limpio y desarrollar rápido ya que para añadir nuevas propiedades o modificar las existentes solo tendrás que modificar los ficheros appsettings.json y Config.cs, nada más.

El código completo para convertir a un objeto C# desde appsettings.json con inyección de dependencias es el siguiente, aunque también puedes consultarlo en el repositorio de GitHub de ejemplo:

using AppSettingsNetTutorial;
using AppSettingsNetTutorial.Services;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

internal class Program
{
    private static void Main(string[] args)
    {
        var build = new ConfigurationBuilder()
        .AddJsonFile("appsettings.json")
        .Build();

        // Alternative 1
        var config1 = build.Get<Config>();

        // Alternative 2
        var config2 = new Config();
        build.Bind(config2);

        // Output
        Console.WriteLine($"config1 from Program: {config1?.ExampleObjectList.FirstOrDefault()?.Header.Description}");
        Console.WriteLine($"config2 from Program: {config2.ExampleObjectList.FirstOrDefault()?.Header.Description}");

        // Send config with dependency injection
        var services = new ServiceCollection();
        services.AddSingleton<Config>(config1);
        services.AddSingleton<IServiceDatabase, ServiceDatabase>();

        // Call service
        var serviceProvider = services.BuildServiceProvider();
        var serviceDatabase = serviceProvider.GetService<IServiceDatabase>();
        serviceDatabase.SaveData("Sample Data");
    }
}

Y después en el servicio accedemos al objeto de la configuración de la siguiente manera:

namespace AppSettingsNetTutorial.Services
{
    public class ServiceDatabase : IServiceDatabase
    {
        private Config _config;

        public ServiceDatabase(Config config)
        {
            _config = config;
        }
        public bool SaveData(string data)
        {
            // todo logic
            Console.WriteLine($"config1 from ServiceDatabase: {_config.ExampleObjectList.FirstOrDefault()?.Header.Description}");

            return true;
        }
    }
}

Resumen de buenas prácticas al leer de appsettings.json

Finalmente voy a enumerar una serie de buenas prácticas para el fichero appsettings.json a tener en cuenta (o malas prácticas a evitar) que he ido recopilando durante mi experiencia como programador .NET:

Utiliza una única clase C# y un objeto que unifique todas las propiedades y subclases o, dicho de otro modo, no dividas la configuración en varias clases separadas con objetos independientes.
Es muy común encontrar este tipo de código, debes evitarlo porque queda muy sucio y confuso:
```
  var build = new ConfigurationBuilder()
  .AddJsonFile("appsettings.json")
  .Build();

  // Avoid this !!!
  var obj1 = build.GetSection("Section1").Get<Section1>();
  var obj2 = build.GetSection("Section2").Get<Section2>();

  Method(obj1, obj2);
```
Utiliza la variable build una sola vez, no varias o, dicho de otro modo, solo se convierte y se accede al JSON una única vez.
A menudo también encuentro que se envía la variable IConfiguration build a otras clases y métodos para que después, cada vez que se necesita leer un valor de la configuración, se utilice para acceder a valores concretos del JSON.
Evita pasar la variable a otros métodos y clases, lo que debes de pasar es el objeto C# completo con toda la configuración y acceder a sus propiedades:
```
  IConfiguration build = new ConfigurationBuilder()
  .AddJsonFile("appsettings.json")
  .Build();

  // Avoid this !!!
  var a = build.Get<Config>().ExampleInt;
  var b = build["ExampleObject:Property1"];

  Method(a, b);
```
Evita el método GetSection, ¿que sentido tiene utilizar el método GetSection para leer una parte del appsettings.json si tenemos una clase común que representa toda nuestra configuración?.
Evita leer y enviar propiedades concretas, si tenemos un único objeto con todas las propiedades y subclases no tiene sentido acceder a propiedades concretas a través de la variable build utilizando líneas similares a build["ExampleObject:Property1"];. Tampoco tiene sentido enviar esas propiedades concretas a otros métodos y clases, lo que debes hacer es enviar el objeto completo y acceder a sus propiedades.
Evita leer valores por su clave string, utiliza, de nuevo, el objeto con toda la configuración y accede a sus propiedades. Leer por clave string es muy propenso a errores humanos y dificulta crear y modificar propiedades de la configuración.
Imagina en el siguiente ejemplo qué ocurriría si queremos modificar el nombre de la propiedad «ExampleInt», deberíamos buscarlo en todo el código y modificarlo a mano:
```
  IConfiguration build = new ConfigurationBuilder()
  .AddJsonFile("appsettings.json")
  .Build();

  // Avoid this !!!
  int a = Int32.Parse(build["ExampleInt"]);
  string b = build["ExampleObject:Property1"];

  Method(a, b);
```
Evita conversiones innecesarias, si tenemos una clase que representa toda la información bien estructurada y definida con sus tipos de datos correctos… ¿qué sentido tiene hacer esta conversión var a = Int32.Parse(build["ExampleInt"])?.
Evita leer el JSON sin convertirlo a un objeto mediante Get o Bind. Aunque no es muy común cuando tratamos con la configuración de una aplicación C#, existen otros métodos para leer y modificar un JSON que no utilizan la variable IConfiguration build, evítalos siempre que puedas.
Utiliza inyección de dependencias para la configuración, aunque no es obligatorio y podemos hacerlo de forma manual enviando el objeto por parámetro, queda mucho más limpio con este método como hemos visto en el apartado anterior.