Skip to content

Commit d16c681

Browse files
TaojunshenTaojunshen
authored
Merge pull request #1526 from MicrosoftDocs/master
3/1 AM Publish
2 parents 8cbe6b3 + 536d766 commit d16c681

34 files changed

+3060
-3017
lines changed

‎docs/code-quality/ca1063-implement-idisposable-correctly.md

Lines changed: 111 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,129 @@
11
---
22
title: "CA1063: Implement IDisposable correctly | Microsoft Docs"
33
ms.custom: ""
4-
ms.date: "11/04/2016"
4+
ms.date: 02/12/2018
55
ms.reviewer: ""
66
ms.suite: ""
7-
ms.technology:
8-
- "vs-ide-code-analysis"
9-
ms.tgt_pltfrm: ""
7+
ms.technology: vs-ide-code-analysis
108
ms.topic: "article"
11-
f1_keywords:
9+
f1_keywords:
1210
- "ImplementIDisposableCorrectly"
1311
- "CA1063"
14-
helpviewer_keywords:
12+
helpviewer_keywords:
1513
- "CA1063"
1614
- "ImplementIDisposableCorrectly"
1715
ms.assetid: 12afb1ea-3a17-4a3f-a1f0-fcdb853e2359
18-
caps.latest.revision: 17
1916
author: "gewarren"
2017
ms.author: "gewarren"
2118
manager: ghogen
22-
ms.workload:
19+
ms.workload:
2320
- "multiple"
2421
---
2522
# CA1063: Implement IDisposable correctly
26-
|||
27-
|-|-|
28-
|TypeName|ImplementIDisposableCorrectly|
29-
|CheckId|CA1063|
30-
|Category|Microsoft.Design|
31-
|Breaking Change|Non-breaking|
32-
33-
## Cause
34-
`IDisposable` is not implemented correctly. Some reasons for this problem are listed here:
35-
36-
- IDisposable is re-implemented in the class.
37-
38-
- Finalize is re-overridden.
39-
40-
- Dispose is overridden.
41-
42-
- Dispose() is not public, sealed, or named Dispose.
43-
44-
- Dispose(bool) is not protected, virtual, or unsealed.
45-
46-
- In unsealed types, Dispose() must call Dispose(true).
47-
48-
- For unsealed types, the Finalize implementation does not call either or both Dispose(bool) or the case class finalizer.
49-
50-
Violation of any one of these patterns will trigger this warning.
51-
52-
Every unsealed root IDisposable type must provide its own protected virtual void Dispose(bool) method. Dispose() should call Dipose(true) and Finalize should call Dispose(false). If you are creating an unsealed root IDisposable type, you must define Dispose(bool) and call it. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) in the [Framework Design Guidelines](/dotnet/standard/design-guidelines/index) section of the .NET Framework documentation.
53-
54-
## Rule Description
55-
All IDisposable types should implement the Dispose pattern correctly.
56-
57-
## How to Fix Violations
58-
Examine your code and determine which of the following resolutions will fix this violation.
59-
60-
- Remove IDisposable from the list of interfaces that are implemented by {0} and override the base class Dispose implementation instead.
61-
62-
- Remove the finalizer from type {0}, override Dispose(bool disposing), and put the finalization logic in the code path where 'disposing' is false.
63-
64-
- Remove {0}, override Dispose(bool disposing), and put the dispose logic in the code path where 'disposing' is true.
65-
66-
- Ensure that {0} is declared as public and sealed.
67-
68-
- Rename {0} to 'Dispose' and make sure that it is declared as public and sealed.
69-
70-
- Make sure that {0} is declared as protected, virtual, and unsealed.
71-
72-
- Modify {0} so that it calls Dispose(true), then calls GC.SuppressFinalize on the current object instance ('this' or 'Me' in [!INCLUDE[vbprvb](../code-quality/includes/vbprvb_md.md)]), and then returns.
73-
74-
- Modify {0} so that it calls Dispose(false) and then returns.
75-
76-
- If you are writing an unsealed root IDisposable class, make sure that the implementation of IDisposable follows the pattern that is described earlier in this section.
77-
78-
## When to Suppress Warnings
79-
Do not suppress a warning from this rule.
80-
81-
## Pseudo-code Example
82-
The following pseudo-code provides a general example of how Dispose(bool) should be implemented in a class that uses managed and native resources.
83-
84-
```
85-
public class Resource : IDisposable
86-
{
87-
private IntPtr nativeResource = Marshal.AllocHGlobal(100);
88-
private AnotherResource managedResource = new AnotherResource();
89-
90-
// Dispose() calls Dispose(true)
91-
public void Dispose()
92-
{
93-
Dispose(true);
94-
GC.SuppressFinalize(this);
95-
}
96-
// NOTE: Leave out the finalizer altogether if this class doesn't
97-
// own unmanaged resources itself, but leave the other methods
98-
// exactly as they are.
99-
~Resource()
100-
{
101-
// Finalizer calls Dispose(false)
102-
Dispose(false);
103-
}
104-
// The bulk of the clean-up code is implemented in Dispose(bool)
105-
protected virtual void Dispose(bool disposing)
106-
{
107-
if (disposing)
108-
{
109-
// free managed resources
110-
if (managedResource != null)
111-
{
112-
managedResource.Dispose();
113-
managedResource = null;
114-
}
115-
}
116-
// free native resources if there are any.
117-
if (nativeResource != IntPtr.Zero)
118-
{
119-
Marshal.FreeHGlobal(nativeResource);
120-
nativeResource = IntPtr.Zero;
121-
}
122-
}
123-
}
23+
24+
|||
25+
|-|-|
26+
|TypeName|ImplementIDisposableCorrectly|
27+
|CheckId|CA1063|
28+
|Category|Microsoft.Design|
29+
|Breaking Change|Non-breaking|
30+
31+
## Cause
32+
33+
`IDisposable` is not implemented correctly. Some reasons for this problem are listed here:
34+
35+
- IDisposable is re-implemented in the class.
36+
37+
- Finalize is re-overridden.
38+
39+
- Dispose is overridden.
40+
41+
- Dispose() is not public, sealed, or named Dispose.
42+
43+
- Dispose(bool) is not protected, virtual, or unsealed.
44+
45+
- In unsealed types, Dispose() must call Dispose(true).
46+
47+
- For unsealed types, the Finalize implementation does not call either or both Dispose(bool) or the case class finalizer.
48+
49+
Violation of any one of these patterns will trigger this warning.
50+
51+
Every unsealed type that declares and implements the IDisposable interface must provide its own protected virtual void Dispose(bool) method. Dispose() should call Dipose(true) and Finalize should call Dispose(false). If you are creating an unsealed type that declares and implements the IDisposable interface, you must define Dispose(bool) and call it. For more information, see [Cleaning up unmanaged resources](/dotnet/standard/garbage-collection/unmanaged) in the [.NET Framework design guidelines](/dotnet/standard/design-guidelines/index).
52+
53+
## Rule description
54+
55+
All IDisposable types should implement the Dispose pattern correctly.
56+
57+
## How to fix violations
58+
59+
Examine your code and determine which of the following resolutions will fix this violation.
60+
61+
- Remove IDisposable from the list of interfaces that are implemented by {0} and override the base class Dispose implementation instead.
62+
63+
- Remove the finalizer from type {0}, override Dispose(bool disposing), and put the finalization logic in the code path where 'disposing' is false.
64+
65+
- Remove {0}, override Dispose(bool disposing), and put the dispose logic in the code path where 'disposing' is true.
66+
67+
- Ensure that {0} is declared as public and sealed.
68+
69+
- Rename {0} to 'Dispose' and make sure that it is declared as public and sealed.
70+
71+
- Make sure that {0} is declared as protected, virtual, and unsealed.
72+
73+
- Modify {0} so that it calls Dispose(true), then calls GC.SuppressFinalize on the current object instance ('this' or 'Me' in [!INCLUDE[vbprvb](../code-quality/includes/vbprvb_md.md)]), and then returns.
74+
75+
- Modify {0} so that it calls Dispose(false) and then returns.
76+
77+
- If you are creating 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.
78+
79+
## When to suppress warnings
80+
81+
Do not suppress a warning from this rule.
82+
83+
## Pseudo-code example
84+
85+
The following pseudo-code provides a general example of how Dispose(bool) should be implemented in a class that uses managed and native resources.
86+
87+
```csharp
88+
public class Resource : IDisposable
89+
{
90+
private IntPtr nativeResource = Marshal.AllocHGlobal(100);
91+
private AnotherResource managedResource = new AnotherResource();
92+
93+
// Dispose() calls Dispose(true)
94+
public void Dispose()
95+
{
96+
Dispose(true);
97+
GC.SuppressFinalize(this);
98+
}
99+
100+
// NOTE: Leave out the finalizer altogether if this class doesn't
101+
// own unmanaged resources itself, but leave the other methods
102+
// exactly as they are.
103+
~Resource()
104+
{
105+
// Finalizer calls Dispose(false)
106+
Dispose(false);
107+
}
108+
109+
// The bulk of the clean-up code is implemented in Dispose(bool)
110+
protected virtual void Dispose(bool disposing)
111+
{
112+
if (disposing)
113+
{
114+
// free managed resources
115+
if (managedResource != null)
116+
{
117+
managedResource.Dispose();
118+
managedResource = null;
119+
}
120+
}
121+
// free native resources if there are any.
122+
if (nativeResource != IntPtr.Zero)
123+
{
124+
Marshal.FreeHGlobal(nativeResource);
125+
nativeResource = IntPtr.Zero;
126+
}
127+
}
128+
}
124129
```

‎docs/code-quality/code-metrics-values.md

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,12 @@ ms.suite: ""
77
ms.technology: vs-ide-code-analysis
88
ms.tgt_pltfrm: ""
99
ms.topic: "article"
10-
helpviewer_keywords:
10+
helpviewer_keywords:
1111
- "code metrics [Visual Studio]"
1212
author: "gewarren"
1313
ms.author: "gewarren"
1414
manager: ghogen
15-
ms.workload:
15+
ms.workload:
1616
- "multiple"
1717
---
1818
# Code metrics values
@@ -21,9 +21,11 @@ The increased complexity of modern software applications also increases the diff
2121

2222
Developers can use Visual Studio to generate code metrics data that measure the complexity and maintainability of their managed code. Code metrics data can be generated for an entire solution or a single project.
2323

24+
For information about how to generate code metrics data in Visual Studio, see [How to: Generate code metrics data](../code-quality/how-to-generate-code-metrics-data.md).
25+
2426
## Software measurements
2527

26-
The following list shows the code metrics results that [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] calculates:
28+
The following list shows the code metrics results that Visual Studio calculates:
2729

2830
- **Maintainability Index** - Calculates an index value between 0 and 100 that represents the relative ease of maintaining the code. A high value means better maintainability. Color coded ratings can be used to quickly identify trouble spots in your code. A green rating is between 20 and 100 and indicates that the code has good maintainability. A yellow rating is between 10 and 19 and indicates that the code is moderately maintainable. A red rating is a rating between 0 and 9 and indicates low maintainability.
2931

@@ -45,4 +47,9 @@ For more information about how Code Metrics treats anonymous methods, see [Anony
4547

4648
Some software tools and compilers generate code that is added to a project and that the project developer either does not see or should not change. Mostly, Code Metrics ignores generated code when it calculates the metrics values. This enables the metrics values to reflect what the developer can see and change.
4749

48-
Code generated for Windows Forms is not ignored, because it is code that the developer can see and change.
50+
Code generated for Windows Forms is not ignored, because it is code that the developer can see and change.
51+
52+
## Next steps
53+
54+
- [How to: Generate code metrics data](../code-quality/how-to-generate-code-metrics-data.md)
55+
- [Use the Code Metrics Results window](../code-quality/working-with-code-metrics-data.md)

‎docs/code-quality/how-to-enforce-maintainable-code-with-a-code-analysis-check-in-policy.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,15 @@ manager: ghogen
1616
ms.workload:
1717
- "multiple"
1818
---
19-
# How to: Enforce Maintainable Code with a Code Analysis Check-in Policy
19+
# How to: Enforce maintainable code with a code analysis check-in policy
2020

21-
Developers can use the Code Metrics tool to measure the complexity and maintainability of their code, but you cannot invoke code metrics as part of a check-in policy. However, you can enable Code Analysis rules that verify the compliance of your code with Code Metrics standards, and enforce the rules through check-in policies. For more information about code metrics, see the [Code Metrics values](../code-quality/code-metrics-values.md).
21+
Developers can use the Code Metrics tool to measure the complexity and maintainability of their code, but you cannot invoke Code Metrics as part of a check-in policy. However, you can enable Code Analysis rules that verify the compliance of your code with code metrics standards, and enforce the rules through check-in policies. For more information about code metrics, see [Code metrics values](../code-quality/code-metrics-values.md).
2222

2323
You can enable the Depth of Inheritance, Class Coupling, Maintainability Index, and Complexity rules to enforce maintainable code through a Code Analysis check-in policy. All four of these rules are found under the "Maintainability Rules" category in the Code Analysis policy editor.
2424

2525
Administrators of version control for Team Foundation can add the Code Analysis Maintainability Rules to the check-in policy requirements. These check-in policies require developers to run Code Analysis based on these rule changes before initiating a check-in.
2626

27-
## To open the Code Analysis Policy Editor
27+
## To open the Code Analysis Policy editor
2828

2929
1.In **Team Explorer**, right-click the team project, click **Team Project Settings**, and then click **Source Control**.
3030

@@ -38,7 +38,7 @@ Administrators of version control for Team Foundation can add the Code Analysis
3838

3939
The **Code Analysis Policy Editor** dialog box appears.
4040

41-
## To enable Code Analysis Maintainability Rules
41+
## To enable code analysis maintainability rules
4242

4343
1.In the **Code Analysis Policy Editor** dialog box, under **Rule Settings**, expand the **Maintainability Rules** node.
4444

@@ -58,5 +58,5 @@ Administrators of version control for Team Foundation can add the Code Analysis
5858

5959
## See also
6060

61-
[Code Metrics Values](../code-quality/code-metrics-values.md)
62-
[Creating and Using Code Analysis Check-In Policies](../code-quality/creating-and-using-code-analysis-check-in-policies.md)
61+
[Code metrics values](../code-quality/code-metrics-values.md)
62+
[Creating and using code analysis check-in policies](../code-quality/creating-and-using-code-analysis-check-in-policies.md)

‎docs/code-quality/how-to-generate-code-metrics-data.md

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
---
2-
title: "How to generate Code Metrics data in Visual Studio | Microsoft Docs"
2+
title: "How to generate code metrics data in Visual Studio | Microsoft Docs"
33
ms.custom: ""
44
ms.date: "12/12/2017"
55
ms.reviewer: ""
66
ms.suite: ""
77
ms.technology: vs-ide-code-analysis
88
ms.tgt_pltfrm: ""
99
ms.topic: "article"
10-
helpviewer_keywords:
10+
helpviewer_keywords:
1111
- "code metrics data"
1212
- "code metrics results"
1313
- "code metrics [Visual Studio]"
1414
author: "gewarren"
1515
ms.author: "gewarren"
1616
manager: ghogen
17-
ms.workload:
17+
ms.workload:
1818
- "multiple"
1919
---
2020
# How to: Generate code metrics data
@@ -33,7 +33,7 @@ You can generate code metrics results for an entire solution or the selected pro
3333

3434
- In the **Code Metrics Results** window, choose the **Calculate Code Metrics for Solution** button.
3535

36-
The results are generated and the **Code Metrics Results** window is displayed.
36+
The results are generated and the **Code Metrics Results** window is displayed.
3737

3838
## To generate code metrics results for one or more selected projects
3939

@@ -45,8 +45,9 @@ You can generate code metrics results for an entire solution or the selected pro
4545

4646
## To view the results details
4747

48-
- In the **Code Metrics Results** window, expand the tree in the **Hierarchy** column.
48+
In the **Code Metrics Results** window, expand the tree in the **Hierarchy** column.
4949

5050
## See also
5151

52-
[Code Metrics values](../code-quality/code-metrics-values.md)
52+
- [Use the Code Metrics Results window](../code-quality/working-with-code-metrics-data.md)
53+
- [Code metrics values](../code-quality/code-metrics-values.md)

0 commit comments

Comments
 (0)