runs.using: 'docker'<\/code><\/td>\nAny app that can run as a Docker container.<\/td>\n<\/tr>\n \nJavaScript<\/a><\/td>\n runs.using: 'javascript'<\/code><\/td>\nAny Node.js app (includes the benefit of using actions\/toolkit<\/code><\/a>).<\/td>\n<\/tr>\n\nComposite<\/a><\/td>\n runs.using: 'composite'<\/code><\/td>\nComposes multiple run<\/code> commands and uses<\/code> actions.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n.NET is capable of running in Docker containers, and when you want a fully functioning .NET app to run as your GitHub Action \u2014 you’ll have to containerize your app. For more information on .NET and Docker, see .NET Docs: Containerize a .NET app<\/a>.<\/p>\nIf you’re curious about creating JavaScript GitHub Actions, I wrote about that too, see Localize .NET applications with machine-translation<\/a>. In that blog post, I cover a TypeScript action that relies on Azure Cognitive Services to automatically generate pull requests for target translations.<\/p><\/blockquote>\nIn addition to containerizing a .NET app, you could alternatively create a .NET global tool that could be installed and called upon using the run<\/code> syntax instead of uses<\/code>. This alternative approach is useful for creating a .NET CLI app that can be used as a global tool, but it’s out of scope for this post. For more information on .NET global tools, see .NET Docs: Global tools<\/a>.<\/p>\nIntent of the tutorial<\/h3>\n
Over on the .NET Docs, there’s a tutorial on creating a GitHub Action with .NET<\/a>. It covers exactly how to containerize a .NET app, how to author the action.yml<\/em> which represents the action’s metadata, as well as how to consume it from a workflow. Rather than repeating the entire tutorial, I’ll summarize the intent of the action, and then we’ll look at how it was updated.<\/p>\nThe app in the tutorial performs code metric analysis by:<\/p>\n
\n- Scanning and discovering *.csproj<\/em> and *.vbproj<\/em> project files in a target repository.<\/li>\n
- Analyzing the discovered source code within these projects for:\n
\n- Cyclomatic complexity<\/li>\n
- Maintainability index<\/li>\n
- Depth of inheritance<\/li>\n
- Class coupling<\/li>\n
- Number of lines of source code<\/li>\n
- Approximated lines of executable code<\/li>\n<\/ul>\n<\/li>\n
- Creating (or updating) a CODE_METRICS.md<\/em> file.<\/li>\n<\/ul>\n
As part of the consuming workflow composition, a pull request is conditionally (and automatically) created when the CODE_METRICS.md<\/em> file changes. In other words, as you push<\/code> changes to your GitHub repository, the workflow runs<\/code> and uses<\/code> the .NET code metrics action \u2014 which updates the markdown representation of the code metrics. The CODE_METRICS.md<\/em> file itself is navigable with automatic links, and collapsible sections. It uses emoji to highlight code metrics at a glance, for example, when a class has high cyclomatic complexity it bubbles an emoji up to the project level heading the markdown. From there, you can drill down into the class and see the metrics for each method.<\/p>\nThe Microsoft.CodeAnalysis.CodeMetrics<\/code> namespace contains the CodeAnalysisMetricData<\/code> type, which exposes the CyclomaticComplexity<\/code> property. This property is a measurement of the structural complexity of the code. It is created by calculating the number of different code paths in the flow of the program. A program that has a complex control flow requires more tests to achieve good code coverage and is less maintainable. When the code is analyzed and the GitHub Action updates the CODE_METRICS.md<\/em> file, it writes an emoji in the header using the following code:<\/p>\ninternal static string ToCyclomaticComplexityEmoji(\r\n this CodeAnalysisMetricData metric) =>\r\n metric.CyclomaticComplexity switch\r\n {\r\n >= 0 and <= 7 => \":heavy_check_mark:\", \/\/ \u2714\ufe0f\r\n 8 or 9 => \":warning:\", \/\/ \u26a0\ufe0f\r\n 10 or 11 => \":radioactive:\", \/\/ \u2622\ufe0f\r\n >= 12 and <= 14 => \":x:\", \/\/ \u274c\r\n _ => \":exploding_head:\" \/\/ \ud83e\udd2f\r\n };<\/code><\/pre>\nAll of the code for this action is provided in the .NET samples repository<\/a> and is also part of the .NET docs code samples browser experience<\/a>. As an example of usage, the action is self-consuming (or dogfooding). As the code updates the action runs, and maintains a CODE_METRICS.md<\/em> file via automated pull requests. Consider the following screen captures showing some of the major parts of the markdown file:<\/p>\nCODE_METRICS.md heading<\/em><\/strong><\/p>\n![\".NET](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/03\/code-metrics-markdown.png\")
<\/p>\n
CODE_METRICS.md ProjectFileReference<\/code> drill-down heading<\/em><\/strong><\/p>\n![\".NET](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/03\/code-metrics-markdown-drill-down.png\")
<\/p>\n
The code metrics markdown file represents the code it analyzes, by providing the following hierarchy:<\/p>\n
Project \u27a1\ufe0f Namespace \u27a1\ufe0f Named Type \u27a1\ufe0f Members table<\/p><\/blockquote>\n
When you drill down into a named type, there is a link at the bottom of the table for the auto-generated class diagram. This is discussed in the Adding new functionality<\/a> section. To navigate the example file yourself, see .NET samples CODE_METRICS.md<\/em><\/a>.<\/p>\nAction metadata<\/h2>\n
For a GitHub repository to be recognized as a GitHub Action, it must define metadata in an action.yml<\/em> file.<\/p>\n# Name, description, and branding. All of which are used for\r\n# displaying the action in the GitHub Action marketplace.\r\nname: '.NET code metric analyzer'\r\ndescription: 'A GitHub action that maintains a CODE_METRICS.md file,\r\n reporting cyclomatic complexity, maintainability index, etc.'\r\nbranding:\r\n icon: sliders\r\n color: purple\r\n\r\n# Specify inputs, some are required and some are not.\r\ninputs:\r\n owner:\r\n description: 'The owner of the repo. Assign from github.repository_owner. Example, \"dotnet\".'\r\n required: true\r\n name:\r\n description: 'The repository name. Example, \"samples\".'\r\n required: true\r\n branch:\r\n description: 'The branch name. Assign from github.ref. Example, \"refs\/heads\/main\".'\r\n required: true\r\n dir:\r\n description: 'The root directory to work from. Example, \"path\/to\/code\".'\r\n required: true\r\n workspace:\r\n description: 'The workspace directory.'\r\n required: false\r\n default: '\/github\/workspace'\r\n\r\n# The action outputs the following values.\r\noutputs:\r\n summary-title:\r\n description: 'The title of the code metrics action.'\r\n summary-details:\r\n description: 'A detailed summary of all the projects that were flagged.'\r\n updated-metrics:\r\n description: 'A boolean value, indicating whether or not the CODE_METRICS.md \r\n was updated as a result of running this action.'\r\n\r\n# The action runs using docker and accepts the following arguments.\r\nruns:\r\n using: 'docker'\r\n image: 'Dockerfile'\r\n args:\r\n - '-o'\r\n - ${{ inputs.owner }}\r\n - '-n'\r\n - ${{ inputs.name }}\r\n - '-b'\r\n - ${{ inputs.branch }}\r\n - '-d'\r\n - ${{ inputs.dir }}\r\n - '-w'\r\n - ${{ inputs.workspace }}<\/code><\/pre>\nThe metadata for the .NET samples code metrics action is nested within a subdirectory, as such, it is not<\/em> recognized as an action that can be displayed in the GitHub Action marketplace<\/a>. However, it can still be used as an action.<\/p>\nFor more information on metadata, see GitHub Docs: Metadata syntax for GitHub Actions<\/a>.<\/p>\nConsuming workflow<\/h2>\n
To consume the .NET code metrics action, a workflow file must exist in the .github\/workflows<\/em> directory from the root of the GitHub repository. Consider the following workflow file:<\/p>\nname: '.NET code metrics'\r\n\r\non:\r\n push:\r\n branches: [ main ]\r\n paths-ignore:\r\n # Ignore CODE_METRICS.md and README.md files\r\n - '**.md'\r\n\r\njobs:\r\n build:\r\n runs-on: ubuntu-latest\r\n permissions:\r\n contents: write\r\n pull-requests: write\r\n\r\n steps:\r\n - uses: actions\/checkout@v2\r\n\r\n # Analyze repositories source metrics:\r\n # Create (or update) CODE_METRICS.md file.\r\n - name: .NET code metrics\r\n id: dotnet-code-metrics\r\n uses: dotnet\/samples\/github-actions\/DotNet.GitHubAction@main\r\n with:\r\n owner: ${{ github.repository_owner }}\r\n name: ${{ github.repository }}\r\n branch: ${{ github.ref }}\r\n dir: ${{ '.\/github-actions\/DotNet.GitHubAction' }}\r\n\r\n # Create a pull request if there are changes.\r\n - name: Create pull request\r\n uses: peter-evans\/create-pull-request@v3.4.1\r\n if: ${{ steps.dotnet-code-metrics.outputs.updated-metrics }} == 'true'\r\n with:\r\n title: '${{ steps.dotnet-code-metrics.outputs.summary-title }}'\r\n body: '${{ steps.dotnet-code-metrics.outputs.summary-details }}'\r\n commit-message: '.NET code metrics, automated pull request.'<\/code><\/pre>\nThis workflow makes use of jobs.<job_id>.permissions<\/code>, setting contents<\/code> and pull-requests<\/code> to write<\/code>. This is required for the action to update contents in the repo and create a pull request from those changes. For more information on permissions, see GitHub Docs: Workflow syntax for GitHub Actions – permissions<\/a>.<\/p>\nTo help visualize how this workflow functions, see the following sequence diagram:<\/p>\n
![\"GitHub](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/03\/code-metrics-action-workflow-sequence-diagram.png\")
<\/p>\n
The preceding sequence diagram shows the workflow for the .NET code metrics action:<\/p>\n
\n- When a developer pushes code to the GitHub repository.\n
\n- The workflow is triggered and starts to run.<\/li>\n<\/ol>\n<\/li>\n
- The source code is checked out into the
$GITHUB_WORKSPACE<\/code>.<\/li>\n- The .NET code metrics action is invoked.\n
\n- The source code is analyzed, and the CODE_METRICS.md<\/em> file is updated.<\/li>\n<\/ol>\n<\/li>\n
- If the .NET code metrics step (
dotnet-code-metrics<\/code>) outputs that metrics were updated, the create-pull-request<\/code> action is invoked.\n\n- The CODE_METRICS.md<\/em> file is checked into the repository.<\/li>\n
- An automated pull request is created. For example pull requests created by the
app\/github-actions<\/code> bot, see .NET samples \/ pull requests<\/a>.<\/li>\n<\/ol>\n<\/li>\n<\/ol>\nAdding new functionality<\/h2>\n
GitHub recently announced diagram support for Markdown powered by Mermaid<\/a>. Since our custom action is capable of analyzing C# as part of its execution, it has a semantic understanding of the classes it’s analyzing. This is used to automatically create Mermaid class diagrams in the CODE_METRICS.md<\/em> file.<\/p>\nThe .NET code metrics GitHub Action sample code was updated to include Mermaid support.<\/p>\n
static void AppendMermaidClassDiagrams(\r\n MarkdownDocument document,\r\n List<(string Id, string Class, string MermaidCode)> diagrams)\r\n{\r\n document.AppendHeader(\"Mermaid class diagrams\", 2);\r\n\r\n foreach (var (id, className, code) in diagrams)\r\n {\r\n document.AppendParagraph($\"<div id=\"{id}\"><\/div>\");\r\n document.AppendHeader($\"`{className}` class diagram\", 5);\r\n document.AppendCode(\"mermaid\", code);\r\n }\r\n}<\/code><\/pre>\nIf you’re interested in seeing the code that generates the diagrams<\/code> argument, see the ToMermaidClassDiagram<\/code><\/a> extension method.\nAs an example of what this renders like within the CODE_METRICS.md<\/em>Markdown file, see the following diagram:<\/p>\n![\".NET](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/03\/mermaid-class-diagram.png\")
<\/p>\n
Summary<\/h2>\n
In this post, you learned about the different types of GitHub Actions with an emphasis on Docker and .NET. I explained how the .NET code metrics GitHub Action was updated to include Mermaid class diagram support. You also saw an example action.yml<\/em> file that serves as the metadata for a GitHub Action. You then saw a visualization of the consuming workflow, and how the code metrics action is consumed. I also covered how to add new functionality to the code metrics action.<\/p>\nWhat will you build, and how will it help others? I encourage you to create and share your own .NET GitHub Actions. For more information on .NET and custom GitHub Actions, see the following resources:<\/p>\n
\n- GitHub Docs: Creating custom actions<\/a><\/li>\n
- .NET Docs: GitHub Actions and .NET<\/a><\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"
Let’s take a look at how you can add code metrics and diagrams for your open-source .NET repositories with GitHub Actions.<\/p>\n","protected":false},"author":24662,"featured_media":39056,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685,7589],"tags":[7605,7222,7608],"class_list":["post-39055","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet","category-github-actions","tag-devops","tag-github","tag-github-actions"],"acf":[],"blog_post_summary":"
Let’s take a look at how you can add code metrics and diagrams for your open-source .NET repositories with GitHub Actions.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/39055","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/24662"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=39055"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/39055\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/39056"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=39055"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=39055"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=39055"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}