How to Mark a Method as Obsolete or Deprecated in C#

By the end of this page, you will understand how to deprecate methods in C# using the Obsolete attribute, how warnings and errors differ, when to use each option, and how to guide developers toward replacement methods safely.

In C#, the standard way to mark code as no longer recommended is with the Obsolete attribute.

When you apply Obsolete to a method, class, property, constructor, or other member, the compiler notifies anyone using it that the API should no longer be used. This is useful when:

• a better method replaces an older one
• the old implementation is unsafe or confusing
• you want to phase out legacy code gradually
• you need to preserve backward compatibility for a while

A deprecated API is not necessarily removed immediately. Usually, deprecation is a transition step:

1. Mark the old API as obsolete.
2. Provide a message explaining what to use instead.
3. Let users migrate.
4. Remove the old API in a future version if appropriate.

This matters in real programming because public APIs often live for a long time. Removing a method suddenly can break dependent code. Marking it obsolete gives developers a clear upgrade path without immediate breakage.

In C#, Obsolete is built into the language ecosystem through attributes, so it works naturally with the compiler and IDE tooling such as Visual Studio.

Think of an obsolete method like an old road that is still open, but now has a sign saying:

• "Do not use this route for new trips"
• "Use Highway B instead"

The road may still work for now, but the sign warns drivers that there is a better or safer path.

If you make the obsolescence stricter, it becomes more like a closed road with a barrier. At that point, using it is no longer just discouraged—it is blocked.

So:

• Obsolete with warning = old road still open, but discouraged
• Obsolete with error = road closed, must use another route

The basic syntax uses the Obsolete attribute above the method.

Basic syntax

[Obsolete]
public void OldMethod()
{
}

This causes the compiler to warn when the method is used.

Add a helpful message

[Obsolete("Use NewMethod() instead.")]
public void OldMethod()
{
}

public void NewMethod()
{
}

Now the compiler warning includes your custom message.

Turn the warning into a compiler error

[Obsolete("Use NewMethod() instead.", true)]
public void OldMethod()
{
}

public void NewMethod()
{
}

The second argument controls severity:

• false or omitted: compiler warning

Consider this example:

using System;

public class Calculator
{
    [Obsolete("Use AddNumbers(int a, int b) instead.")]
    public int Add(int a, int b)
    {
        return a + b;
    }

    public int AddNumbers(int a, int b)
    {
        return a + b;
    }
}

public class Program
{
    public static void Main()
    {
        var calc = new Calculator();
        int result = calc.Add(2, 3);
        Console.WriteLine(result);
    }
}

Here is what happens step by step:

1. The compiler reads the Calculator class.
2. It sees that Add has the [Obsolete(...)] attribute.

Deprecation is common in real software projects.

Library and framework evolution

A package author may replace an old method with a clearer API:

[Obsolete("Use SendAsync() instead.")]
public void Send()
{
}

This gives users time to migrate without instantly breaking their applications.

Renaming confusing methods

If a method name is misleading, you can keep it temporarily:

[Obsolete("Use CalculateTotalPrice() instead.")]
public decimal Calc()
{
    return CalculateTotalPrice();
}

Replacing unsafe behavior

A method may allow insecure or outdated logic:

[Obsolete("Use HashPasswordSecurely() instead.")]
public string HashPassword(string input)
{
    return input;
}

Migrating configuration APIs

Older configuration patterns often need replacement while preserving compatibility for existing users.

In real projects, developers usually do more than just add the attribute.

Common pattern: redirect to the new method

[Obsolete("Use NewMethod() instead.")]
public void OldMethod()
{
    NewMethod();
}

This reduces duplicated logic and keeps behavior consistent during migration.

Common pattern: start with warning, later change to error

A typical lifecycle is:

1. Add [Obsolete("Use NewMethod() instead.")]
2. Wait one or more releases
3. Change to [Obsolete("Use NewMethod() instead.", true)]
4. Remove the method in a later major version

Helpful migration messages

Good messages are specific. For example:

• bad: "Deprecated"
• good: "Use CreateUserAsync(string name) instead."

Used in public APIs and internal APIs

Teams use Obsolete in:

• reusable class libraries
• SDKs
• NuGet packages
• internal shared utilities
• domain services in large applications

Works well with validation and guard-style migration

1. Forgetting to include a replacement message

This works, but it is not very helpful:

[Obsolete]
public void OldMethod() { }

Better:

[Obsolete("Use NewMethod() instead.")]
public void OldMethod() { }

2. Using true too early

This breaks callers immediately:

[Obsolete("Use NewMethod() instead.", true)]
public void OldMethod() { }

Use warning mode first unless you intentionally want a hard stop.

3. Thinking obsolete means removed

Marking a method obsolete does not delete it. The method still exists and can still run unless you remove it from the codebase.

4. Deprecating without providing an alternative

If you mark something obsolete, try to give developers a next step.

Bad:

Obsolete warning vs error

[Obsolete()]
 { }

[]
 { }

using System;

Mark a method as obsolete

[Obsolete]
public void OldMethod() { }

Mark with a custom warning message

[Obsolete("Use NewMethod() instead.")]
public void OldMethod() { }

Mark with a compiler error

[Obsolete("Use NewMethod() instead.", true)]
public void OldMethod() { }

Severity rules

• No second argument: warning
• false: warning
• true: error

Best practices

• Always provide a clear replacement message
• Prefer warning before error for public APIs
• Keep old methods temporarily if users need migration time
• Forward old logic to the new method when possible

How do I deprecate a method in C#?

Use the Obsolete attribute:

[Obsolete("Use NewMethod() instead.")]
public void OldMethod() { }

Is there a Deprecated attribute in C#?

No. The standard built-in attribute is Obsolete.

Can I make obsolete usage fail compilation?

Yes. Pass true as the second argument:

[Obsolete("Use NewMethod() instead.", true)]

Does an obsolete method still run?

Yes. If it is marked as a warning, it still compiles and runs normally.

Should I use warning or error first?

Usually start with a warning, then switch to an error in a later release if needed.

Can I mark a whole class as obsolete?

Yes.

[Obsolete("Use NewService instead.")]
public class OldService { }

• Attributes in C# — Obsolete is an attribute, so understanding attributes helps you use it correctly.
• Compiler warnings and errors — deprecation relies on compile-time diagnostics.
• Method overloading — useful because you may need to deprecate one overload but keep another.
• API design — deprecation is part of designing maintainable and user-friendly APIs.
• Backward compatibility — marking APIs obsolete helps avoid breaking existing users immediately.
• Refactoring — deprecated methods are often introduced during renaming or redesign.
• XML documentation comments — often used together with Obsolete to explain migration steps.