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
• true: compiler error

Complete example

using System;

public class MyService
{
    [Obsolete("OldMethod is deprecated. Use NewMethod() instead.")]
    public void OldMethod()
    {
        Console.WriteLine("Running old logic");
    }

    public void NewMethod()
    {
        Console.WriteLine("Running new logic");
    }
}

public class Program
{
    public static void Main()
    {
        var service = new MyService();
        service.OldMethod();
        service.NewMethod();
    }
}

If you compile this, OldMethod() still works, but the compiler shows a warning.

Applying it to other members

You can also mark other code elements as obsolete:

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

public class Example
{
    [Obsolete("Use NewProperty instead.")]
    public string OldProperty { get; set; }

    public string NewProperty { get; set; }
}

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.
3. It records that Add should produce a warning when used.
4. In Main, the line calc.Add(2, 3) calls the obsolete method.
5. The compiler emits a warning with the message: Use AddNumbers(int a, int b) instead.
6. The program still compiles because the attribute did not specify true for error mode.
7. At runtime, Add(2, 3) executes normally and returns 5.
8. Console.WriteLine(result) prints 5.

Important point: Obsolete mainly affects compile-time behavior, not runtime behavior. The method still runs unless you remove it or change the design.

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.

Large internal applications

In enterprise codebases, teams often mark legacy service methods as obsolete before fully removing them, so other teams can update their usage gradually.

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

Sometimes the old method still exists only to validate input and forward the call:

[Obsolete("Use Save(Order order) instead.")]
public void SaveOrder(Order order)
{
    if (order == null)
        throw new ArgumentNullException(nameof(order));

    Save(order);
}

This keeps migration safe while maintaining compatibility.

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("Do not use this.")]
public void OldMethod() { }

Better:

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

5. Misspelling the attribute name

Broken code:

[Deprecated]
public void OldMethod() { }

In C#, the built-in attribute is Obsolete, not Deprecated.

6. Forgetting the namespace in some contexts

You may need:

using System;

Without access to System, Obsolete may not resolve depending on the project setup.

7. Marking the wrong member

Sometimes developers mark only one overload but forget the others. If multiple old overloads should be phased out, each relevant member must be marked.

Obsolete warning vs error

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

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

• OldMethod1() can still be called, but the compiler warns.
• OldMethod2() causes a compile-time error if called.

Obsolete vs just renaming

If you simply rename a method, existing callers break immediately.

If you keep the old method and mark it obsolete, users get a smoother transition path.

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
• Mark all outdated overloads if needed

Can be used on

• methods
• classes
• properties
• constructors
• fields
• structs
• enums

Important note

Obsolete affects compile-time guidance. It does not automatically remove runtime behavior.

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 { }

Do IDEs show obsolete methods differently?

Yes. Most C# IDEs and editors display warnings and often show the deprecation message in tooltips.

Should I remove the method right after marking it obsolete?

Usually no. Obsolete is commonly used as a transition step before removal.

• 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.