From f96f4c8de784ced5bdad76a7c1cb121a3697f8af Mon Sep 17 00:00:00 2001 From: Sebastien Marichal Date: Mon, 23 Dec 2024 15:37:47 +0100 Subject: [PATCH] NET-915 Modify rule S2930: Include tracked types in the description (#4588) --- rules/S2930/csharp/rule.adoc | 42 +++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/rules/S2930/csharp/rule.adoc b/rules/S2930/csharp/rule.adoc index 211e22ba7c8..4e33cbcbe1e 100644 --- a/rules/S2930/csharp/rule.adoc +++ b/rules/S2930/csharp/rule.adoc @@ -1,17 +1,29 @@ == Why is this an issue? -When writing https://learn.microsoft.com/en-us/dotnet/standard/managed-code[managed code], there is no need to worry about memory allocation or deallocation as it is taken care of by the https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection[garbage collector]. However, certain objects, such as `Bitmap`, utilize unmanaged memory for specific purposes like https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/unsafe-code[pointer arithmetic]. These objects may have substantial unmanaged memory footprints while having minimal managed footprints. Unfortunately, the garbage collector only recognizes the small managed footprint and does not promptly reclaim the corresponding unmanaged memory (by invoking the finalizer method of `Bitmap`) for efficiency reasons. +When writing https://learn.microsoft.com/en-us/dotnet/standard/managed-code[managed code], there is no need to worry about memory allocation or deallocation as it is taken care of by the https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection[garbage collector]. However, certain objects, such as `Bitmap`, utilize unmanaged memory for specific purposes like https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/unsafe-code[pointer arithmetic]. These objects may have substantial unmanaged memory footprints while having minimal managed footprints. Unfortunately, the garbage collector only recognizes the small managed footprint and does not promptly reclaim the corresponding unmanaged memory (by invoking the finalizer method of `Bitmap`) for efficiency reasons. In addition, it's essential to manage other system resources besides memory. The operating system has limits on the number of https://en.wikipedia.org/wiki/File_descriptor[file descriptors] (e.g., `FileStream`) or https://en.wikipedia.org/wiki/Network_socket[sockets] (e.g., `WebClient`) that can remain open simultaneously. Therefore, it's crucial to `Dispose` of these resources promptly when they are no longer required, instead of relying on the garbage collector to invoke the finalizers of these objects at an unpredictable time in the future. This rule keeps track of `private` fields and local variables of specific types that implement `IDisposable` or `IAsyncDisposable`. It identifies instances of these types that are not properly disposed, closed, aliased, returned, or passed to other methods. This applies to instances that are either directly created using the `new` operator or instantiated through a predefined list of factory methods. +Here is the list of the types tacked by this rule: + +* `FluentAssertions.Execution.AssertionScope` +* `System.Drawing.Bitmap` +* `System.Drawing.Image` +* `System.IO.FileStream` +* `System.IO.StreamReader` +* `System.IO.StreamWriter` +* `System.Net.Sockets.TcpClient` +* `System.Net.Sockets.UdpClient` +* `System.Net.WebClient` + Here is the list of predefined factory methods tracked by this rule: -* `System.IO.File.Create()` -* `System.IO.File.Open()` * `System.Drawing.Image.FromFile()` * `System.Drawing.Image.FromStream()` +* `System.IO.File.Create()` +* `System.IO.File.Open()` === Exceptions @@ -48,7 +60,7 @@ When creating the disposable resource for a one-time use (cases not covered by t [source,csharp,diff-id=1,diff-type=noncompliant] ---- -public class ResourceHolder +public class ResourceHolder { private FileStream fs; // Noncompliant: dispose or close are never called @@ -79,7 +91,7 @@ public class ResourceHolder : IDisposable, IAsyncDisposable this.fs = new FileStream(path, FileMode.Open); } - public void Dispose() + public void Dispose() { this.fs.Dispose(); } @@ -104,16 +116,16 @@ public class ResourceHolder : IDisposable, IAsyncDisposable === Documentation -* https://learn.microsoft.com/en-us/dotnet/standard/managed-code[What is "managed code"?] -* https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection[Garbage collection] -* https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/finalizers[Finalizers] -* https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/unsafe-code[Unsafe code, pointer types, and function pointers] -* https://en.wikipedia.org/wiki/File_descriptor[File descriptor - Wiki] -* https://en.wikipedia.org/wiki/Network_socket[Network socket - Wiki] -* https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/dispose-pattern[Dispose pattern] -** https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/implementing-dispose[Implement a Dispose method] -** https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/implementing-disposeasync[Implement a DisposeAsync method] -* https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/statements/using[using statement and using declaration] +* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/standard/managed-code[What is "managed code"?] +* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection[Garbage collection] +* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/finalizers[Finalizers] +* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/unsafe-code[Unsafe code, pointer types, and function pointers] +* Wikipedia - https://en.wikipedia.org/wiki/File_descriptor[File descriptor] +* Wikipedia - https://en.wikipedia.org/wiki/Network_socket[Network socket] +* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/dispose-pattern[Dispose pattern] +** Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/implementing-dispose[Implement a Dispose method] +** Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/implementing-disposeasync[Implement a DisposeAsync method] +* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/statements/using[using statement and using declaration] * CWE - https://cwe.mitre.org/data/definitions/459[CWE-459 - Incomplete Cleanup] ifdef::env-github,rspecator-view[]