Marking Methods "Obsolete" In C# Class Library

The following are the objectives of this article:

What’s an obsolete method?
Why & when should a method be marked as obsolete?
Available options in C#

What’s an obsolete method?

A method in a class library which is old or out-of-use and some other method instead of this is suggested to be used.

Generally, when you are introducing some new functionality in your class library but still want to keep an old method intact for some time until the next big release then it’s better to mark that old method as “Obsolete” and offer new functionality in a new method.

Why & when should a method be marked as obsolete?

You are introducing some changes in your class library, and replacing a method with a new one with some added features, at that time it is a good idea to not suddenly remove that method from your class library because it may break some code. But if you mark that method as obsolete then it is an indication that this method is already out-of-use and something else should be used in its place.

Available options in C#

Let’s now see what options are available in C# to mark a method as obsolete.

Open Visual Studio 2015 or 2017 and create a C# class library project named “TestClassLibrary”:

Add a new static class in that project names “TestClass”. Add the following method in that class,

public static string ToUpper(string input) {
return input.ToUpper();
}

Now right click on solution and add a new console application project named “TestConsoleApplication”.

Add reference of class library project in console application project,

Go to the Program.cs class and add following “using” statement at top,

using TestClassLibrary;

Go to the “Main” method and add following code

Console.WriteLine(TestClass.ToUpper("test input"));
Console.ReadKey();

Build the solution by pressing F6 and it should build fine without any error or warning.

Now, let’s go to the TestClass and mark the ToUpper method as obsolete. For that just add “[Obsolete()]” attribute above the ToUpper method.

The whole TestClass.cs will look like this,

What have we done here?

We have marked the method with “Obsolete” attribute indicating its users that this method is now deprecated and will be removed in future release. So, it’s advisable not to use it.

If you go to the console application, then you will see a green line below the code where this method is called, if you move your mouse over that green line you will see the warning message,

If you build the project and then see error list window, you will see a warning,

Note here the warning code CS0612. It’s a compiler warning code. If you click on the link CS0612, then you will see Microsoft documentation for this code will open in your browser,

But this does not look like a good direction to the programmers on what to use if not this method.

Let’s add one more method to class library.

Go to TestClass.cs in class library project and add following method which has better error handling and its culture-neutral.

public static string MakeUpperCase(string input) {
if (String.IsNullOrEmpty(input)) throw new ArgumentNullException(nameof(input));
return input.ToUpperInvariant();
}

Now we want to indicate to the programmers that instead of “ToUpper” method, they should use “MakeUpperCase” method. Add a message inside “Obsolete” attribute on top of “ToUpper” method:

[Obsolete("This method should not be used, Use MakeUpperCase instead.")]

The whole method will look like,

What have we done here?

We have marked the method with “Obsolete” attribute and added a message to be shown to the user which can work as an indicator to use some other replacement method.

If you now build the project and go to the Main method, you will see a warning with the above message,

Now this looks like a good direction to a programmer who is going to use your class library.

Later, if you think that you have given enough warning and time to programmers using your class library that they should not use this method, and you want to raise an error if they do, then you can convert this warning into error by passing “true” Boolean value after the message:

[Obsolete("This method should not be used, Use MakeUpperCase instead.", true)]

The whole method will look like this,

What have we done here?

We have marked the method with “Obsolete” attribute and added a flag indicating compiler should raise an error if this method is used somewhere.

If you build your project now, it will throw an error,

Use this error flag in your class library when you want to introduce breaking changes in code.

In summary, we have seen the following three overloads of “Obsolete” attribute,

I have attached a sample project with this article, downloaded it and built it one by one by uncommenting only one “Obsolete” attribute at a time,