CA1063: Implement IDisposable correctly

Article
04/22/2023

Property	Value
Rule ID	CA1063
Title	Implement IDisposable correctly
Category	Design
Fix is breaking or non-breaking	Non-breaking
Enabled by default in .NET 8	No

Cause

The System.IDisposable interface is not implemented correctly. Possible reasons for this include:

IDisposable is reimplemented in the class.
Finalize is overridden again.
Dispose() is overridden.
The Dispose() method is not public, sealed, or named Dispose.
Dispose(bool) is not protected, virtual, or unsealed.
In unsealed types, Dispose() must call Dispose(true).
For unsealed types, the Finalize implementation does not call either or both Dispose(bool) or the base class finalizer.

Violation of any one of these patterns triggers warning CA1063.

Every unsealed type that declares and implements the IDisposable interface must provide its own protected virtual void Dispose(bool) method. Dispose() should call Dispose(true), and the finalizer should call Dispose(false). If you create an unsealed type that declares and implements the IDisposable interface, you must define Dispose(bool) and call it. For more information, see Clean up unmanaged resources (.NET guide) and Implement a Dispose method.

By default, this rule only looks at externally visible types, but this is configurable.

Rule description

All IDisposable types should implement the Dispose pattern correctly.

How to fix violations

Examine your code and determine which of the following resolutions will fix this violation:

Remove IDisposable from the list of interfaces that are implemented by your type, and override the base class Dispose implementation instead.
Remove the finalizer from your type, override Dispose(bool disposing), and put the finalization logic in the code path where 'disposing' is false.
Override Dispose(bool disposing), and put the dispose logic in the code path where 'disposing' is true.
Make sure that Dispose() is declared as public and sealed.
Rename your dispose method to Dispose and make sure that it's declared as public and sealed.
Make sure that Dispose(bool) is declared as protected, virtual, and unsealed.
Modify Dispose() so that it calls Dispose(true), then calls SuppressFinalize on the current object instance (this, or Me in Visual Basic), and then returns.
Modify your finalizer so that it calls Dispose(false) and then returns.
If you create an unsealed type that declares and implements the IDisposable interface, make sure that the implementation of IDisposable follows the pattern that is described earlier in this section.

When to suppress warnings

Do not suppress a warning from this rule.

Note

You might see false positive warnings from this rule if all of the following apply:

You're using Visual Studio 2022 version 17.5 or later with an older version of the .NET SDK, that is, .NET 6 or earlier.
You're using the analyzers from the .NET 6 SDK or an older version of the analyzer packages, such as Microsoft.CodeAnalysis.FxCopAnalyzers.
You have attributes on your IDispose implementation.

In this case, it's safe to suppress a false positive warning. The false positives are due to a breaking change in the C# compiler. Consider using a newer analyzer that contains the fix for the false positive warnings. Upgrade to Microsoft.CodeAnalysis.NetAnalyzers version 7.0.0-preview1.22464.1 or newer or use the analyzers from the .NET 7 SDK.

Configure code to analyze

Use the following option to configure which parts of your codebase to run this rule on.

Include specific API surfaces

You can configure this option for just this rule, for all rules it applies to, or for all rules in this category (Design) that it applies to. For more information, see Code quality rule configuration options.

Include specific API surfaces

You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an .editorconfig file in your project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Pseudo-code example

The following pseudo-code provides a general example of how Dispose(bool) should be implemented in a class that uses managed and native resources.

public class Resource : IDisposable
{
    private bool isDisposed;
    private IntPtr nativeResource = Marshal.AllocHGlobal(100);
    private AnotherResource managedResource = new AnotherResource();

    // Dispose() calls Dispose(true)
    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    // The bulk of the clean-up code is implemented in Dispose(bool)
    protected virtual void Dispose(bool disposing)
    {
        if (isDisposed) return;

        if (disposing)
        {
            // free managed resources
            managedResource.Dispose();
        }

        // free native resources if there are any.
        if (nativeResource != IntPtr.Zero)
        {
            Marshal.FreeHGlobal(nativeResource);
            nativeResource = IntPtr.Zero;
        }

        isDisposed = true;
    }

    // NOTE: Leave out the finalizer altogether if this class doesn't
    // own unmanaged resources, but leave the other methods
    // exactly as they are.
    ~Resource()
    {
        // Finalizer calls Dispose(false)
        Dispose(false);
    }
}