Algunos consejos y recomendaciones cuando trabajamos con el atributo Obsolete

Cuando estamos creando librerías que van a ser consumidas por terceros, ya sea por nuestro propio equipo de desarrollo o bien otros equipos de desarrollo, a veces sucede que cambiamos una propiedad o una llamada a un método por ejemplo, ya sea porque cambiamos sus parámetros, el nombre del método, etc.

El problema aquí, radica en que si por ejemplo cambiamos el método en cuestión, cuando se actualice la aplicación para utilizar la nueva librería, el código que antes funcionaba, dejará de funcionar.

Aquí por lo tanto, podemos correr con varias estrategias que veremos, y que deberemos elegir de acuerdo a nuestras necesidades, objetivos, etc.

Vamos a partir de una sencilla clase de demostración.

namespace ClassLibrary1
{

    using System;

    public class DemoClass
    {

        public int Sum(int value1, int value2)
        {
            return value1 + value2;
        }

    }

}

Esta clase no tiene ninguna complejidad y poco más que añadir.
Una clase normal, que podemos utilizar desde una aplicación de consola, haciendo referencia a la librería generada.

Ahora bien, vamos a poner el caso de que, debido a nuestras necesidades internas, nuestro método debe cambiar de int a double.
Sin embargo, no queremos que los programadores que utilizan nuestra librería, tengan un problema.

Digamos, que vamos a indicarle un procedimiento de trabajo recomendándoles que hagan los ajustes pertinentes para que ya no usen más el método con int.

Para ello, el código anterior de nuestra librería, podría tener este otro aspecto:

namespace ClassLibrary1
{

    using System;

    public class DemoClass
    {

        [Obsolete("Use Sum with double to retrieve the sum of the values.")]
        public int Sum(int value1, int value2)
        {
            return value1 + value2;
        }

        public double Sum(double value1, double value2)
        {
            return value1 + value2;
        }

    }

}

Si intentamos acceder a esta librería desde el código de la aplicación que lo consuma, podremos apreciar que el editor de código nos avisa indicándonos que el método Sun tiene dos sobrecargas, y que la primera de ellas está obsoleta.

De hecho, si usamos esta librería y el método marcado como obsoleto:

var demoClass = new DemoClass();
var sum = demoClass.Sum(1, 2);

Veremos cuando compilamos, que aparece un warning o aviso, indicándonos que estamos utilizando un método marcado como obsoleto, y que lógicamente, la recomendación es evitar cualquier warning o aviso que aparezca en el entorno.

Ahora bien, ¿qué hacemos si en nuestra librería tenemos dos métodos uno obsoleto y otro que no lo es y queremos que los programadores que utilicen nuestra librería no localicen fácilmente este método obsoleto?.
Bastará con decorar el método con un valor que impida que el editor de código nos muestre el método obsoleto.

El código de nuestra librería por lo tanto, tendrá un aspecto similar al siguiente:

namespace ClassLibrary1
{

    using System;
    using System.ComponentModel;

    public class DemoClass
    {

        [Obsolete("Use Sum to retrieve the sum of the values.")]
        [EditorBrowsable(EditorBrowsableState.Never)]
        public int Sum(int value1, int value2)
        {
            return value1 + value2;
        }

        public double Sum(double value1, double value2)
        {
            return value1 + value2;
        }

    }

}

Como vemos, hemos utilizado el atributo EditorBrowsable indicando que no queremos mostrar el método marcado como obsoleto en el editor de código.
Si intentamos utilizar ahora nuestra librería, veremos que no hay sobrecargas (visibles) de nuestro método Sum.

Esto NO significa que no podamos utilizar el método obsoleto que no aparece ahora en el editor de código, simplemente significa que está «oculto» para que ningún programador lo utilice por error.

Ahora bien, imaginemos que nuestro deseo no es ni tan siquiera ocultar el método para que el programador no lo utilice, sino simplemente, generar un error (en lugar de un warning o aviso) cuando se esté usando.

Dicho de otro modo, que nuestra librería no se compile si usa el método obsoleto.
Útil por ejemplo, cuando hemos enviado una recomendación a nuestros programadores para que cambien el método obsoleto, y un tiempo después volvemos a actualizar la librería, pero esta vez marcamos un error directamente para «forzar» a aquellos programadores que no tomaron en cuenta nuestras recomendaciones.

Pues en este caso, deberemos indicar mediante un valor del atributo Obsolete, que cuando se intente compilar la aplicación, y utilice un método obsoleto, devuelva un error en tiempo de compilación.

Nuestra librería quedaría por lo tanto de esta forma:

namespace ClassLibrary1
{

    using System;
    using System.ComponentModel;

    public class DemoClass
    {

        [Obsolete("Use Sum to retrieve the sum of the values.", error: true)]
        public int Sum(int value1, int value2)
        {
            return value1 + value2;
        }

        public double Sum(double value1, double value2)
        {
            return value1 + value2;
        }

    }

}

Una vez hecho esto, si compilamos la aplicación que utiliza el método marcado como obsoleto y error, nos devolverá un mensaje de error en tiempo de compilación, impidiéndonos compilar la aplicación.

Como vemos, hay diferentes estrategias a la hora de marcar como Obsolete nuestros métodos, etc., de nuestras clases.

Finalmente, indicar que todo esto no se verá si dentro de la solución tenemos la librería con métodos obsoletos y el proyecto que lo consume.
Como recomendación y para verificar esto que indico aquí, recomiendo utilizar un proyecto con la librería, y otro con una aplicación de consola para consumir la librería por ejemplo, y hacer una referencia a la dll de la librería.

¡Happy Coding!