dotnet-api-docs/xml/System/IDisposable.xml at main · dotnet/dotnet-api-docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
<Type Name="IDisposable" FullName="System.IDisposable">
  <TypeSignature Language="C#" Value="public interface IDisposable" />
  <TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract IDisposable" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;net-6.0;net-7.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.6.2-pp;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
  <TypeSignature Language="DocId" Value="T:System.IDisposable" />
  <TypeSignature Language="VB.NET" Value="Public Interface IDisposable" />
  <TypeSignature Language="F#" Value="type IDisposable = interface" />
  <TypeSignature Language="C++ CLI" Value="public interface class IDisposable" />
  <TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract beforefieldinit IDisposable" FrameworkAlternate="net-10.0;net-8.0;net-9.0" />
  <AssemblyInfo>
    <AssemblyName>System.Runtime</AssemblyName>
    <AssemblyVersion>4.0.0.0</AssemblyVersion>
    <AssemblyVersion>4.0.10.0</AssemblyVersion>
    <AssemblyVersion>4.0.20.0</AssemblyVersion>
    <AssemblyVersion>4.1.0.0</AssemblyVersion>
    <AssemblyVersion>4.2.0.0</AssemblyVersion>
    <AssemblyVersion>4.2.1.0</AssemblyVersion>
    <AssemblyVersion>4.2.2.0</AssemblyVersion>
    <AssemblyVersion>5.0.0.0</AssemblyVersion>
    <AssemblyVersion>6.0.0.0</AssemblyVersion>
    <AssemblyVersion>7.0.0.0</AssemblyVersion>
    <AssemblyVersion>8.0.0.0</AssemblyVersion>
    <AssemblyVersion>9.0.0.0</AssemblyVersion>
    <AssemblyVersion>10.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <AssemblyInfo>
    <AssemblyName>mscorlib</AssemblyName>
    <AssemblyVersion>1.0.5000.0</AssemblyVersion>
    <AssemblyVersion>2.0.0.0</AssemblyVersion>
    <AssemblyVersion>2.0.5.0</AssemblyVersion>
    <AssemblyVersion>4.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <AssemblyInfo>
    <AssemblyName>netstandard</AssemblyName>
    <AssemblyVersion>2.0.0.0</AssemblyVersion>
    <AssemblyVersion>2.1.0.0</AssemblyVersion>
  </AssemblyInfo>
  <TypeForwardingChain>
    <TypeForwarding From="mscorlib" FromVersion="4.0.0.0" To="System.Runtime" ToVersion="0.0.0.0" FrameworkAlternate="dotnet-uwp-10.0" />
    <TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="10.0.0.0" FrameworkAlternate="net-10.0" />
    <TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="5.0.0.0" FrameworkAlternate="net-5.0" />
    <TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="6.0.0.0" FrameworkAlternate="net-6.0" />
    <TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="7.0.0.0" FrameworkAlternate="net-7.0" />
    <TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="8.0.0.0" FrameworkAlternate="net-8.0" />
    <TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="9.0.0.0" FrameworkAlternate="net-9.0" />
    <TypeForwarding From="System.Runtime" FromVersion="4.1.1.1" To="mscorlib" ToVersion="4.0.0.0" FrameworkAlternate="netframework-4.6.2-pp" />
  </TypeForwardingChain>
  <Interfaces />
  <Attributes>
    <Attribute FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1">
      <AttributeName Language="C#">[System.Runtime.InteropServices.ComVisible(true)]</AttributeName>
      <AttributeName Language="F#">[&lt;System.Runtime.InteropServices.ComVisible(true)&gt;]</AttributeName>
    </Attribute>
  </Attributes>
  <Docs>
    <summary>Provides a mechanism for releasing unmanaged resources.</summary>
    <remarks>For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-idisposable">Supplemental API remarks for IDisposable</see>.</remarks>
    <example>
      <format type="text/markdown"><![CDATA[
        The following example demonstrates how to create a resource class that implements the <xref:System.IDisposable> interface.

        :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp" id="Snippet1":::
        :::code language="csharp" source="~/snippets/csharp/System/IDisposable/Overview/idisposabledispose.cs" id="Snippet1":::
        :::code language="fsharp" source="~/snippets/fsharp/System/IDisposable/Overview/idisposabledispose.fs" id="Snippet1":::
        :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb" id="Snippet1":::id="Snippet1":::
      ]]></format>
    </example>
    <altmember cref="T:Microsoft.Win32.SafeHandles.SafeFileHandle" />
    <related type="Article" href="/dotnet/standard/garbage-collection/implementing-dispose">Implementing a Dispose Method</related>
  </Docs>
  <Members>
    <Member MemberName="Dispose">
      <MemberSignature Language="C#" Value="public void Dispose ();" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Dispose() cil managed" />
      <MemberSignature Language="DocId" Value="M:System.IDisposable.Dispose" />
      <MemberSignature Language="VB.NET" Value="Public Sub Dispose ()" />
      <MemberSignature Language="F#" Value="abstract member Dispose : unit -&gt; unit" Usage="iDisposable.Dispose " />
      <MemberSignature Language="C++ CLI" Value="public:&#xA; void Dispose();" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>System.Runtime</AssemblyName>
        <AssemblyVersion>4.0.0.0</AssemblyVersion>
        <AssemblyVersion>4.0.10.0</AssemblyVersion>
        <AssemblyVersion>4.0.20.0</AssemblyVersion>
        <AssemblyVersion>4.1.0.0</AssemblyVersion>
        <AssemblyVersion>4.2.0.0</AssemblyVersion>
        <AssemblyVersion>4.2.1.0</AssemblyVersion>
        <AssemblyVersion>4.2.2.0</AssemblyVersion>
        <AssemblyVersion>5.0.0.0</AssemblyVersion>
        <AssemblyVersion>6.0.0.0</AssemblyVersion>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
        <AssemblyVersion>8.0.0.0</AssemblyVersion>
        <AssemblyVersion>9.0.0.0</AssemblyVersion>
        <AssemblyVersion>10.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>mscorlib</AssemblyName>
        <AssemblyVersion>1.0.5000.0</AssemblyVersion>
        <AssemblyVersion>2.0.0.0</AssemblyVersion>
        <AssemblyVersion>2.0.5.0</AssemblyVersion>
        <AssemblyVersion>4.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>netstandard</AssemblyName>
        <AssemblyVersion>2.0.0.0</AssemblyVersion>
        <AssemblyVersion>2.1.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.</summary>
        <remarks>
          <format type="text/markdown"><![CDATA[

## Remarks
 Use this method to close or release unmanaged resources such as files, streams, and handles held by an instance of the class that implements this interface. By convention, this method is used for all tasks associated with freeing resources held by an object, or preparing an object for reuse.

> [!WARNING]
>  If you are using a class that implements the <xref:System.IDisposable> interface, you should call its <xref:System.IDisposable.Dispose%2A> implementation when you are finished using the class. For more information, see the "Using an object that implements IDisposable" section in the <xref:System.IDisposable> topic.

 When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's <xref:System.IDisposable.Dispose%2A> implementation must call <xref:System.IDisposable.Dispose%2A> on B, which must in turn call <xref:System.IDisposable.Dispose%2A> on C.

> [!IMPORTANT]
>  The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the <xref:System.IDisposable.Dispose%2A> method.

 An object must also call the <xref:System.IDisposable.Dispose%2A> method of its base class if the base class implements <xref:System.IDisposable>. For more information about implementing <xref:System.IDisposable> on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the <xref:System.IDisposable> topic.

 If an object's <xref:System.IDisposable.Dispose%2A> method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its <xref:System.IDisposable.Dispose%2A> method is called multiple times. Instance methods other than <xref:System.IDisposable.Dispose%2A> can throw an <xref:System.ObjectDisposedException> when resources are already disposed.

 Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as `Close`, that calls the <xref:System.IDisposable.Dispose%2A> method.

 Because the <xref:System.IDisposable.Dispose%2A> method must be called explicitly, there is always a danger that the unmanaged resources will not be released, because the consumer of an object fails to call its <xref:System.IDisposable.Dispose%2A> method. There are two ways to avoid this:

-   Wrap the managed resource in an object derived from <xref:System.Runtime.InteropServices.SafeHandle?displayProperty=nameWithType>. Your <xref:System.IDisposable.Dispose%2A> implementation then calls the <xref:System.IDisposable.Dispose%2A> method of the <xref:System.Runtime.InteropServices.SafeHandle?displayProperty=nameWithType> instances. For more information, see "The SafeHandle alternative" section in the <xref:System.Object.Finalize%2A?displayProperty=nameWithType> topic.

-   Implement a finalizer to free resources when <xref:System.IDisposable.Dispose%2A> is not called. By default, the garbage collector automatically calls an object's finalizer before reclaiming its memory. However, if the <xref:System.IDisposable.Dispose%2A> method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, <xref:System.IDisposable.Dispose%2A> implementations can call the <xref:System.GC.SuppressFinalize%2A?displayProperty=nameWithType> method.

 When you use an object that accesses unmanaged resources, such as a <xref:System.IO.StreamWriter>, a good practice is to create the instance with a `using` statement. The `using` statement automatically closes the stream and calls <xref:System.IDisposable.Dispose%2A> on the object when the code that is using it has completed. For an example, see the <xref:System.IO.StreamWriter> class.


## Examples
 The following example shows how you can implement the <xref:System.IDisposable.Dispose%2A> method.

 :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/CPP/idisposabledispose.cpp" id="Snippet1":::
 :::code language="csharp" source="~/snippets/csharp/System/IDisposable/Overview/idisposabledispose.cs" id="Snippet1":::
 :::code language="fsharp" source="~/snippets/fsharp/System/IDisposable/Overview/idisposabledispose.fs" id="Snippet1":::
 :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IDisposable.Dispose Example/VB/idisposabledispose.vb" id="Snippet1":::

 ]]></format>
        </remarks>
        <related type="Article" href="/dotnet/standard/garbage-collection/implementing-dispose">Implementing a Dispose Method</related>
      </Docs>
    </Member>
  </Members>
</Type>