Редактиране

Споделяне чрез

CA1001: Types that own disposable fields should be disposable

  • Статия
Property Value
Rule ID CA1001
Title Types that own disposable fields should be disposable
Category Design
Fix is breaking or non-breaking Non-breaking - If the type is not visible outside the assembly.

Breaking - If the type is visible outside the assembly.
Enabled by default in .NET 8 No

Cause

A class declares and implements an instance field that is an System.IDisposable type, and the class does not implement IDisposable.

By default, this rule analyzes the entire codebase, but this is configurable.

Rule description

A class that declares an IDisposable field indirectly owns an unmanaged resource. The class should implement the IDisposable interface to dispose of the unmanaged resource that it owns once the resource is no longer in use. If the class does not directly own any unmanaged resources, it should not implement a finalizer.

This rule respects types implementing System.IAsyncDisposable as disposable types.

How to fix violations

To fix a violation of this rule, implement the IDisposable interface. In the IDisposable.Dispose method, call the Dispose method of the field's type.

When to suppress warnings

In general, do not suppress a warning from this rule. It's okay to suppress the warning when the dispose ownership of the field is not held by the containing type.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

#pragma warning disable CA1001
// The code that's violating the rule is on this line.
#pragma warning restore CA1001

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

[*.{cs,vb}]
dotnet_diagnostic.CA1001.severity = none

For more information, see How to suppress code analysis warnings.

Configure code to analyze

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

These options can be configured 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.

Exclude specific symbols

You can exclude specific symbols, such as types and methods, from analysis. For example, to specify that the rule should not run on any code within types named MyType, add the following key-value pair to an .editorconfig file in your project:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Allowed symbol name formats in the option value (separated by |):

  • Symbol name only (includes all symbols with the name, regardless of the containing type or namespace).
  • Fully qualified names in the symbol's documentation ID format. Each symbol name requires a symbol-kind prefix, such as M: for methods, T: for types, and N: for namespaces.
  • .ctor for constructors and .cctor for static constructors.

Examples:

Option Value Summary
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Matches all symbols named MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Matches all symbols named either MyType1 or MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Matches specific method MyMethod with the specified fully qualified signature.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Matches specific methods MyMethod1 and MyMethod2 with the respective fully qualified signatures.

Exclude specific types and their derived types

You can exclude specific types and their derived types from analysis. For example, to specify that the rule should not run on any methods within types named MyType and their derived types, add the following key-value pair to an .editorconfig file in your project:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Allowed symbol name formats in the option value (separated by |):

  • Type name only (includes all types with the name, regardless of the containing type or namespace).
  • Fully qualified names in the symbol's documentation ID format, with an optional T: prefix.

Examples:

Option Value Summary
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Matches all types named MyType and all of their derived types.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Matches all types named either MyType1 or MyType2 and all of their derived types.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Matches specific type MyType with given fully qualified name and all of its derived types.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Matches specific types MyType1 and MyType2 with the respective fully qualified names, and all of their derived types.

Example

The following example shows a class that violates the rule and a class that satisfies the rule by implementing IDisposable. The class does not implement a finalizer because the class does not directly own any unmanaged resources.

Imports System
Imports System.IO

Namespace ca1001

    ' This class violates the rule.
    Public Class NoDisposeMethod

        Dim newFile As FileStream

        Sub New()
            newFile = New FileStream("c:\temp.txt", FileMode.Open)
        End Sub

    End Class

    ' This class satisfies the rule.
    Public Class HasDisposeMethod
        Implements IDisposable

        Dim newFile As FileStream

        Sub New()
            newFile = New FileStream("c:\temp.txt", FileMode.Open)
        End Sub

        Protected Overridable Overloads Sub Dispose(disposing As Boolean)

            If disposing Then
                ' dispose managed resources
                newFile.Close()
            End If

            ' free native resources

        End Sub 'Dispose


        Public Overloads Sub Dispose() Implements IDisposable.Dispose

            Dispose(True)
            GC.SuppressFinalize(Me)

        End Sub 'Dispose

    End Class

End Namespace

// This class violates the rule.
public class NoDisposeMethod
{
    FileStream _newFile;

    public NoDisposeMethod()
    {
        _newFile = new FileStream(@"c:\temp.txt", FileMode.Open);
    }
}

// This class satisfies the rule.
public class HasDisposeMethod : IDisposable
{
    FileStream _newFile;

    public HasDisposeMethod()
    {
        _newFile = new FileStream(@"c:\temp.txt", FileMode.Open);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (disposing)
        {
            // Dispose managed resources.
            _newFile.Close();
        }
        // Free native resources.
    }

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

See also