Skip to content
alert-circle

GitHub Action

.NET version sweeper

v2.0 Latest version

.NET version sweeper

alert-circle

.NET version sweeper

A Github action that scans .NET projects, and creates issues that report versions that are not within long term support

Installation

Copy and paste the following snippet into your .yml file.

              

- name: .NET version sweeper

uses: dotnet/versionsweeper@v2.0

Learn more about this action in dotnet/versionsweeper

Choose a version

🎯 LTS (or STS) versions

.NET version sweeper

build & test target supported version code-ql analysis GitHub marketplace GitHub license GitHub contributors GitHub repo size GitHub issues-opened GitHub issues-closed GitHub pulls-opened GitHub pulls-merged GitHub pulls-unmerged

Get started

The .NET version sweeper is designed to alert repositories (by either creating issues, pull requests, or both) that there are projects targeting versions that are no longer supported (or won't be soon). For example, projects targeting .NET Core 3.0 or .NET Framework 4.5.1 could trigger an issue to be created to update these projects to supported versions, or even a pull request that upgrades it for you. For example issues, see issues created in this repo based on the non-lts directory.

This is intended to be used as a GitHub action that will run as a scheduled CRON job. Ideally, once a month or as often as necessary to align with .NET version updates.

A schedule/cron job that runs on the first of every month is detailed below in the example workflow, '0 0 1 * *'.

Required inputs

Option Details
-o, owner The owner of the repo.
Assign from ${{ github.repository_owner }}. Example, "dotnet".
-n, name The repository name.
Assign from ${{ github.repository }}. Example, "dotnet/samples".
-b, branch The branch name.
Assign from ${{ github.ref }}. Example, "main".
-t, token The GitHub personal-access token (PAT), or the token from GitHub action context.
Assign from ${{ github.token }}.

Optional inputs

Option Details
-d, dir The root directory, defaults to "/github/workspace".
-p, pattern The search pattern, defaults to "*.csproj;*.fsproj;*.vbproj;*.xproj;project.json".
-s, sdk-compliance Whether or not to report projects that are not using the new SDK-style project format.

GitHub Action outputs

Output Type Details
has-remaining-work bool When true, the upgrade-projects array will be populated with project directories that require upgrade.
upgrade-projects string[] An array of project directories that are in need of being upgraded.

Note Outputs are only present when configured to run as pull request mode. For more information, see Configure action.

Example workflow

# This is a basic workflow to help you get started with Actions

name: "target supported version"

# Controls when the action will run.
on:
  # Triggers the workflow on push or pull request events but only for the default branch
  schedule:
    - cron: "0 0 1 * *"
  workflow_dispatch:
    inputs:
      reason:
        description: "The reason for running the workflow"
        required: true
        default: "Manual run"
      support:
        description: "The support level to target (STS, LTS, or Preview)."
        required: true
        default: "STS"

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  version-sweep:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    permissions:
      issues: write
      pull-requests: write

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3

      # Runs a single command using the runners shell
      - name: "Print manual run reason"
        if: ${{ github.event_name == 'workflow_dispatch' }}
        run: |
          echo 'Reason: ${{ github.event.inputs.reason }}'

      # Start the .NET version sweeper, scan projects/slns for non-LTS (or currrent) versions
      - name: .NET version sweeper
        id: dotnet-version-sweeper
        uses: dotnet/versionsweeper@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          owner: ${{ github.repository_owner }}
          name: ${{ github.repository }}
          branch: ${{ github.ref }}
      
      - name: Create pull requests
        if: steps.dotnet-version-sweeper.outputs.has-remaining-work == 'true'
        run: |
          upgradeProjects: ${{ steps.dotnet-version-sweeper.outputs.upgrade-projects }}

          # Install .NET Upgrade Assistant global tool
          dotnet tool install --global upgrade-assistant

          # Iterate all upgrade projects
          for projectDir in "${upgradeProjects[@]}"; do
            echo "Project Directory: $projectDir"

            # Create a new branch
            git checkout -b upgrade/$projectDir

            # Perform the upgrade using upgrade-assistant
            upgrade-assistant upgrade "$projectDir" --non-interactive -t ${{ inputs.support }}

            # Commit the changes
            git add .
            git commit -m ".NET Version Sweeper: Upgraded $projectDir"

            # Push the branch to the repository
            git push origin upgrade/$projectDir

            # Create a pull request
            gh pr create \
              --base main \
              --head upgrade/$projectDir \
              --title "Upgraded $projectDir" \
              --body "Proposed upgrade for $projectDir"
          done

Project and solution discovery

The .NET version sweeper currently supports reporting on all of the following types:

  • C# project files: *.csproj
  • F# project files: *.fsproj
  • VB project files: *.vbproj
  • DNX project files: *.xproj
  • Project JSON files: project.json
  • Solution files: *.sln

Dockerfile discovery

The .NET version sweeper also supports reporting Dockerfile target frameworks that are out-of-support, or soon to be, for example:

  • FROM mcr.microsoft.com/dotnet/framework/aspnet:4.8
  • COPY --from=mcr.microsoft.com/dotnet/framework/runtime:3.5-20221011-windowsservercore-ltsc2019

Configure action

To configure the action, you can create a file at the root of the repository named dotnet-versionsweeper.json. This config file contains a node, named "ignore" that is an array of patterns following the globbing matcher detailed here.

The file can also contain a value outOfSupportWithinDays to specify the number of additional days to consider flagging versions that will be out of support.

{
  "ignore": [
    "**/SomePath/**/*.csproj",
    "**/*ThisShouldNeverBeFlagged.csproj",
    "IgnoreDir/**/*.*"
  ],
  "outOfSupportWithinDays": 90,
  "actionType": "All"
}

For an example config file, see dotnet/samples/dotnet-versionsweeper.json.

Configuration Type Details
ignore string[] Glob patterns to ignore.
outOfSupportWithinDays string[] The number of days in advance to monitor for.
actionType ActionType

   "CreateIssue"
   "PullRequest"
   "All"
The type of action to take, defaults to CreateIssue.

Label auto-generation

This tool will create a label named dotnet-target-version for easier tracking of issues and pull requests that it creates. The label is created with the following description and color by default, please do not change the name - as that is what is used to determine whether or not to create a new label.

Example labels in the wild

Example issues

This repo serves as a sample, as it contains a directory non-lts with projects and solutions that are intentionally targeting unsupported versions. There are issues created against these to exemplify how they render. For more information, see these issues.

Official .NET support policies

This action is intended to help determine non-LTS (or STS) versions, but it isn't perfect. When in doubt, please refer to the official .NET support policies.

Acknowledgements

Name NuGet package URL & license
CommandLineParser https://www.nuget.org/packages/CommandLineParser (MIT)
MarkdownBuilder https://www.nuget.org/packages/MarkdownBuilder (MIT)
NSubstitute https://www.nuget.org/packages/NSubstitute (LICENSE)
Octokit https://www.nuget.org/packages/Octokit (MIT)
Octokit.Extensions https://www.nuget.org/packages/Octokit.Extensions (MIT)