Skip to content

Commit b2db9c5

Browse files
ktoliverktoliver
authored
Merge pull request #3209 from gewarren/code-met
Update code metrics topics
2 parents a5e278c + dcbb018 commit b2db9c5

File tree

3 files changed

+155
-55
lines changed

3 files changed

+155
-55
lines changed

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Calculate code metrics in Visual Studio
3-
ms.date: 12/12/2017
3+
ms.date: 11/02/2018
44
ms.prod: visual-studio-dev15
55
ms.technology: vs-ide-code-analysis
66
ms.topic: "conceptual"
@@ -34,6 +34,9 @@ The following list shows the code metrics results that Visual Studio calculates:
3434

3535
- **Lines of Code** - Indicates the approximate number of lines in the code. The count is based on the IL code and is therefore not the exact number of lines in the source code file. A very high count might indicate that a type or method is trying to do too much work and should be split up. It might also indicate that the type or method might be hard to maintain.
3636

37+
> [!NOTE]
38+
> The [command-line version](../code-quality/how-to-generate-code-metrics-data.md#command-line-code-metrics) of the code metrics tool counts actual lines of code because it analyzes the source code instead of IL.
39+
3740
## Anonymous methods
3841

3942
An *anonymous method* is just a method that has no name. Anonymous methods are most frequently used to pass a code block as a delegate parameter. Metrics results for an anonymous method that is declared in a member, such as a method or accessor, are associated with the member that declares the method. They are not associated with the member that calls the method.

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

Lines changed: 133 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: How to generate code metrics data in Visual Studio
3-
ms.date: 12/12/2017
2+
title: Generate code metrics from the IDE or command line
3+
ms.date: 11/02/2018
44
ms.prod: visual-studio-dev15
55
ms.technology: vs-ide-code-analysis
66
ms.topic: "conceptual"
@@ -16,33 +16,149 @@ ms.workload:
1616
---
1717
# How to: Generate code metrics data
1818

19-
You can generate code metrics results for an entire solution or the selected project.
19+
You can generate code metrics results for one or more projects or an entire solution. Code metrics is available within the Visual Studio interactive development environment (IDE) and, for C# and Visual Basic projects, at the command line.
2020

21-
## To generate code metrics results for an entire solution
21+
In addition, you can install a [NuGet package](https://dotnet.myget.org/feed/roslyn-analyzers/package/nuget/Microsoft.CodeAnalysis.FxCopAnalyzers/2.6.2-beta2-63202-01) that includes four code metrics [analyzer](roslyn-analyzers-overview.md) rules: CA1501, CA1502, CA1505, and CA1506. These rules are disabled by default, but you can enable them from **Solution Explorer** or in a [rule set](using-rule-sets-to-group-code-analysis-rules.md) file.
2222

23-
- From the menu bar, choose **Analyze** > **Calculate Code Metrics** > **For Solution**.
23+
## Visual Studio IDE code metrics
2424

25-
\- or -
25+
### Generate code metrics results for an entire solution
2626

27-
- In **Solution Explorer**, right-click the solution and then choose **Calculate Code Metrics**.
27+
You can generate code metrics results for an entire solution in any of the following ways:
28+
29+
- From the menu bar, choose **Analyze** > **Calculate Code Metrics** > **For Solution**.
2830

29-
\- or -
31+
- In **Solution Explorer**, right-click the solution and then choose **Calculate Code Metrics**.
3032

3133
- In the **Code Metrics Results** window, choose the **Calculate Code Metrics for Solution** button.
3234

33-
The results are generated and the **Code Metrics Results** window is displayed.
35+
The results are generated and the **Code Metrics Results** window is displayed. To view the results details, expand the tree in the **Hierarchy** column.
3436

35-
## To generate code metrics results for one or more selected projects
37+
### Generate code metrics results for one or more projects
3638

3739
1. In **Solution Explorer**, select one or more projects.
3840

39-
1. From the menu bar, choose **Analyze** > **Calculate Code Metrics** > **For <project\>**.
40-
41-
The results are generated and the **Code Metrics Results** window is displayed.
42-
43-
## To view the results details
44-
45-
In the **Code Metrics Results** window, expand the tree in the **Hierarchy** column.
41+
1. From the menu bar, choose **Analyze** > **Calculate Code Metrics** > **For Selected Project(s)**.
42+
43+
The results are generated and the **Code Metrics Results** window is displayed. To view the results details, expand the tree in the **Hierarchy**.
44+
45+
## Command-line code metrics
46+
47+
You can generate code metrics data from the command line for C# and Visual Basic projects for .NET Framework, .NET Core, and .NET Standard apps. The command line code metrics tools is called *Metrics.exe*.
48+
49+
To obtain the *Metrics.exe* executable, you must [generate it yourself](#generate-the-executable). In the near future, a [published version of *Metrics.exe* will be available](https://github.com/dotnet/roslyn-analyzers/issues/1756) so you don't have to build it yourself.
50+
51+
### Generate the executable
52+
53+
To generate the executable *Metrics.exe*, follow these steps:
54+
55+
1. Clone the [dotnet/roslyn-analyzers](https://github.com/dotnet/roslyn-analyzers) repo.
56+
2. Open Developer Command Prompt for Visual Studio as an administrator.
57+
3. From the root of the **roslyn-analyzers** repo, execute the following command: `Restore.cmd`
58+
4. Change directory to *src\Tools*.
59+
5. Execute the following command to build the **Metrics.csproj** project:
60+
61+
```shell
62+
msbuild /m /v:m /p:Configuration=Release Metrics.csproj
63+
```
64+
65+
An executable named *Metrics.exe* is generated in the *Binaries* directory under the repo root.
66+
67+
> [!TIP]
68+
> To build *Metrics.exe* in [legacy mode](#legacy-mode), execute the following command:
69+
>
70+
> ```shell
71+
> msbuild /m /v:m /t:rebuild /p:LEGACY_CODE_METRICS_MODE=true Metrics.csproj
72+
> ```
73+
74+
### Usage
75+
76+
To run *Metrics.exe*, supply a project or solution and an output XML file as arguments. For example:
77+
78+
```shell
79+
C:\>Metrics.exe /project:ConsoleApp20.csproj /out:report.xml
80+
Loading ConsoleApp20.csproj...
81+
Computing code metrics for ConsoleApp20.csproj...
82+
Writing output to 'report.xml'...
83+
Completed Successfully.
84+
```
85+
86+
### Output
87+
88+
The generated XML output takes the following format:
89+
90+
```xml
91+
<?xml version="1.0" encoding="utf-8"?>
92+
<CodeMetricsReport Version="1.0">
93+
<Targets>
94+
<Target Name="ConsoleApp20.csproj">
95+
<Assembly Name="ConsoleApp20, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null">
96+
<Metrics>
97+
<Metric Name="MaintainabilityIndex" Value="100" />
98+
<Metric Name="CyclomaticComplexity" Value="1" />
99+
<Metric Name="ClassCoupling" Value="1" />
100+
<Metric Name="DepthOfInheritance" Value="1" />
101+
<Metric Name="LinesOfCode" Value="11" />
102+
</Metrics>
103+
<Namespaces>
104+
<Namespace Name="ConsoleApp20">
105+
<Metrics>
106+
<Metric Name="MaintainabilityIndex" Value="100" />
107+
<Metric Name="CyclomaticComplexity" Value="1" />
108+
<Metric Name="ClassCoupling" Value="1" />
109+
<Metric Name="DepthOfInheritance" Value="1" />
110+
<Metric Name="LinesOfCode" Value="11" />
111+
</Metrics>
112+
<Types>
113+
<NamedType Name="Program">
114+
<Metrics>
115+
<Metric Name="MaintainabilityIndex" Value="100" />
116+
<Metric Name="CyclomaticComplexity" Value="1" />
117+
<Metric Name="ClassCoupling" Value="1" />
118+
<Metric Name="DepthOfInheritance" Value="1" />
119+
<Metric Name="LinesOfCode" Value="7" />
120+
</Metrics>
121+
<Members>
122+
<Method Name="void Program.Main(string[] args)" File="C:\Users\mavasani\source\repos\ConsoleApp20\ConsoleApp20\Program.cs" Line="7">
123+
<Metrics>
124+
<Metric Name="MaintainabilityIndex" Value="100" />
125+
<Metric Name="CyclomaticComplexity" Value="1" />
126+
<Metric Name="ClassCoupling" Value="1" />
127+
<Metric Name="LinesOfCode" Value="4" />
128+
</Metrics>
129+
</Method>
130+
</Members>
131+
</NamedType>
132+
</Types>
133+
</Namespace>
134+
</Namespaces>
135+
</Assembly>
136+
</Target>
137+
</Targets>
138+
</CodeMetricsReport>
139+
```
140+
141+
### Tool differences
142+
143+
Previous versions of Visual Studio, including Visual Studio 2015, included a command-line code metrics tool called *Metrics.exe*. This previous version of the tool did a binary analysis, that is, an assembly-based analysis. The new tool analyzes source code instead. Because the new *Metrics.exe* is source code-based, the results are different to what's generated by previous versions of *Metrics.exe* and within the Visual Studio 2017 IDE.
144+
145+
The new *Metrics.exe* tool can compute metrics even in the presence of source code errors, as long as the solution and project can be loaded.
146+
147+
#### Metric value differences
148+
149+
The `LinesOfCode` metric is more accurate and reliable in the new *Metrics.exe*. It is independent of any codegen differences and doesn’t change when the toolset or runtime changes. The new *Metrics.exe* counts actual lines of code, including blank lines and comments.
150+
151+
Other metrics such as `CyclomaticComplexity` and `MaintainabilityIndex` use the same formulas as previous versions of *Metrics.exe*, but the new *Metrics.exe* counts the number of `IOperations` (logical source instructions) instead of intermediate language (IL) instructions. The numbers will be slightly different from previous versions of *Metrics.exe* and from the Visual Studio 2017 IDE code metrics results.
152+
153+
### Legacy mode
154+
155+
You can also choose to build *Metrics.exe* in *legacy mode*. The legacy mode version of the tool generates metric values that are closer to what older versions of the tool generated. Additionally, in legacy mode, *Metrics.exe* generates code metrics for the same set of method types that previous versions of the tool generated code metrics for. For example, it doesn't generate code metrics data for field and property initializers. Legacy mode is useful for backwards compatibility or if you have code check-in gates based on code metrics numbers. The command to build *Metrics.exe* in legacy mode is:
156+
157+
```shell
158+
msbuild /m /v:m /t:rebuild /p:LEGACY_CODE_METRICS_MODE=true Metrics.csproj
159+
```
160+
161+
For more information, see [Enable generating code metrics in legacy mode](https://github.com/dotnet/roslyn-analyzers/pull/1841).
46162

47163
## See also
48164

‎docs/code-quality/working-with-code-metrics-data.md

Lines changed: 18 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: The Code Metrics Results window in Visual Studio
2+
title: Code Metrics window
33
ms.date: 12/12/2017
44
ms.prod: visual-studio-dev15
55
ms.technology: vs-ide-code-analysis
6-
ms.topic: "conceptual"
6+
ms.topic: reference
77
f1_keywords:
88
- "vs.codemetrics.output"
99
helpviewer_keywords:
@@ -16,33 +16,31 @@ manager: douge
1616
ms.workload:
1717
- "multiple"
1818
---
19-
# Using the Code Metrics Results window
19+
# Use the Code Metrics Results window
2020

2121
The **Code Metrics Results** window displays the data that is generated by the code metrics analysis. For more information about code metrics data values, see [Code metrics values](../code-quality/code-metrics-values.md).
2222

23-
## Displaying code metrics results
23+
## Display code metrics results
2424

2525
The **Code Metrics Results** window is displayed automatically when you generate code metrics results. You can also display the window at any time.
2626

27-
### To display the Code Metrics Results window
27+
You can display the Code Metrics Results window using one of the following menu sequences:
2828

2929
- On the **Analyze** menu, choose **Windows** > **Code Metrics Results**.
3030

31-
\- or -
32-
3331
- On the **View** menu, choose **Other Windows** > **Code Metrics Results**.
3432

35-
The **Code Metrics Results** window is displayed, even if it contains no results.
33+
The **Code Metrics Results** window opens, even if it contains no results.
3634

3735
### To view code metrics details
3836

3937
If code metrics results have been generated, expand the tree in the **Hierarchy** column.
4038

41-
## Filtering code metrics results
39+
## Filter code metrics results
4240

4341
You can filter the results that are displayed in the **Code Metrics Results** window by using the toolbar at the top. For example, you might want to see only the results that have a maintainability index below 65.
4442

45-
The **Filter** drop-down box contains the names of the results columns. When a filter is defined, it is added to the bottom of the list together with an indentation. The list can contain the last ten filters that were defined.
43+
The **Filter** drop-down box contains the names of the results columns. When a filter is defined, it is added to the bottom of the list together with an indentation. The list can contain the last 10 filters that were defined.
4644

4745
### To filter the code metrics results
4846

@@ -56,46 +54,29 @@ The **Filter** drop-down box contains the names of the results columns. When a f
5654

5755
5. To see the result details, expand the hierarchy tree.
5856

59-
## Adding, removing, and rearranging data columns
60-
61-
You can add or remove results columns from the **Code Metrics Results** window . In addition, you can rearrange results columns so that they appear in the order that you want.
57+
## Add, remove, and rearrange data columns
6258

63-
### To remove a column
59+
You can add or remove results columns from the **Code Metrics Results** window. In addition, you can rearrange results columns so that they appear in the order that you want.
6460

65-
1. Click the **Add/Remove Columns** button.
61+
### Add or remove a column
6662

67-
\- or -
68-
Right-click any column heading and then click **Add/Remove Columns**.
63+
1. Click the **Add/Remove Columns** button, or right-click any column heading and then click **Add/Remove Columns**.
6964

70-
1. In the **Add/Remove Columns** dialog box, clear the check box for the column that you want to remove and then click **OK**.
65+
1. In the **Add/Remove Columns** dialog box, select or clear the check box for the column that you want to add or remove, and then choose **OK**.
7166

72-
### To add a previously removed column
67+
### Rearrange columns
7368

7469
1. Click the **Add/Remove Columns** button.
7570

76-
\- or -
77-
78-
Right-click any column heading and then click **Add/Remove Columns**.
79-
80-
1. In the **Add/Remove Columns** dialog box, select the check box for the column that you want to add and then click **OK**.
81-
82-
### To rearrange columns
83-
84-
1. Click the **Add/Remove Columns** button.
85-
86-
\- or -
87-
88-
Right-click any column heading and then click **Add/Remove Columns**.
89-
90-
1. In the **Add/Remove Columns** dialog box, select the column that you want to move and then click either the up arrow or the down arrow.
71+
1. In the **Add/Remove Columns** dialog box, select the column that you want to move and then choose either the up arrow or the down arrow.
9172

92-
1. When the column is positioned where you want it, click **OK**.
73+
1. When the column is positioned where you want it, choose **OK**.
9374

94-
## Copying data to the clipboard or Excel
75+
## Copy data to the clipboard or Excel
9576

9677
You can select and copy a selected row of code metrics data to the clipboard as a text string that contains one line for the name and value of each data column. You can also click **Open Selection in Microsoft Excel** to export all of the code metrics results to an Excel spreadsheet.
9778

98-
## Creating a work item based on code metric results
79+
## Create a work item based on code metric results
9980

10081
You can create an [Azure Boards](/azure/devops/boards/index?view=vsts) work item that is based on results in the **Code Metric Results** window. When the work item is created, Visual Studio automatically enters a title in the **Title** field and code metrics data under the **History** tab.
10182

0 commit comments

Comments
 (0)