action.yml

name: .NET Build with Static Code Analysis
description: Builds the .NET solution in the given directory with static code analysis.

inputs:
  directory:
    required: false
    default: .
    description: Path to the directory where a solution file can be found.
  configuration:
    required: false
    default: Release
    description: Configuration parameter for dotnet build, e.g. Release (default) or Debug.
  verbosity:
    required: false
    default: quiet
    description: Verbosity parameter for dotnet build.
  enable-code-analysis:
    required: false
    default: 'true'
    description: If set to "true", static code analysis is enabled during the build.
  enable-nuget-caching:
    required: false
    default: 'false'
    description: >
      If set to "true", the NuGet packages will be cached by GitHub. This is faster if you have a lot of NuGet packages,
      but negligible or even slower if you only have a handful.
  enable-npm-caching:
    required: false
    default: 'false'
    description: >
      If set to "true", the NPM packages will be cached by GitHub. This is faster if you have a lot of NPM packages, but
      negligible or even slower if you only have a handful.
  cache-version:
    required: false
    default: '0'
    description: >
      Change this to any other value to alter the cache key, effectively invalidating the latest cache. You can also
      manage cache entries from the UI, see:
      https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows/caching-dependencies-to-speed-up-workflows#deleting-cache-entries.
  publish-version:
    required: false
    default: 1.${{ github.run_number }}.${{ github.run_attempt }}-${{ github.run_id }}
    description: The value given to `dotnet build`'s `-Version` switch.
  dotnet-build-switches:
    required: false
    default: ''
    description: >
      Additional command line switches given to `dotnet build`. You must split these into multiple lines, even the
      parameter value.
  solution-or-project-path:
    required: false
    default: '*.sln?'
    description: >
      The path of the solution or project file to be built. If you have exactly one .sln or .slnx file in the current
      directory then this can be omitted. Otherwise make sure to specify it to avoid an "MSB1008: Only one project can
      be specified." error that is thrown when the `*.sln?` wildcard results in multiple files. To build a project file
      you must specify a path that ends with `.csproj`. An example: "./src/*Web/*.Web.csproj". The value is given to
      PowerShell's `Get-ChildItem` cmdlet as-is, so grepping is still possible but a name with spaces must be escaped
      separately.
  expected-code-analysis-errors:
    required: false
    default: ''
    description: >
      If not empty, it indicates that the static code analysis should fail. Then each line should contain one error
      code. The static code analysis should yield these and only these errors. This is ignored if `enable-code-analysis`
      is not "true". You may add a colon and then an explanation of the expected error.
  create-binary-log:
    required: false
    default: 'false'
    description: >
      Configures MSBuild to create a binary log. This is useful to inspect and debug builds. See
      https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md for details.
  binary-log-artifact-retention-days:
    required: false
    default: '14'
    description: >
      Duration in days after which the artifact of the binary log (if any) will expire. See
      https://github.com/actions/upload-artifact#retention-period for more details.
  warnings-as-errors:
    required: false
    default: 'true'
    description: >
      Whether compiler warnings should be treated as errors during the build process. The default value is "true", the
      compiler flag "-warnaserror" will be used, causing the build to fail if any warnings are generated. If set to
      "false", the flag "-warnaserror" will not be used, allowing warnings to be generated without causing the build to
      fail.
  dotnet-clean:
    required: false
    default: 'false'
    description: >
      If set to "true", it runs "dotnet clean" on the "solution-or-project-path" after build. This can be used to save
      disk space if you only ran this action to verify the code using the "enable-code-analysis" option.
  git-clean:
    required: false
    default: 'false'
    description: >
      If set to "true", it runs "git clean" on the working directory (as specified by the "directory" input) after
      build. This can be used to save disk space if you only ran this action to verify the code using the
      "enable-code-analysis" option.
  rebuild-directory:
    required: false
    default: ''
    description: >
      If a path is provided, C# project files are searched and rebuilt inside that directory. This is to be considered a
      workaround for a build order problem, and should be avoided when possible.
  timeout-minutes:
    required: false
    default: '360'
    description: >
      The maximum time the for the "build" step in minutes. Can be useful in combination with "create-binary-log" if the
      build hangs.

runs:
  using: composite
  steps:
    - name: Setup Scripts
      shell: pwsh
      run: |
        '${{ github.action_path }}' >> $Env:GITHUB_PATH
        (Resolve-Path '${{ github.action_path }}/../../../Scripts').Path >> $Env:GITHUB_PATH

    - name: Setup & Detect Cache Configuration
      id: detect-cache-configuration
      shell: pwsh
      run: |
        $isNuget = $${{ inputs.enable-nuget-caching == 'true' }}
        $isNpm = $${{ inputs.enable-npm-caching == 'true' }}
        $key = @'
        ${{ github.repository }}-${{ runner.os }}-${{ inputs.cache-version }}-${{ inputs.directory }}
        '@.Trim()

        $hashes = @{
            'nuget' = '${{ hashFiles('**/*.csproj') }}';
            'npm' = '${{ hashFiles('**/package-lock.json', '**/pnpm-lock.yaml') }}';
            'nugetnpm' = '${{ hashFiles('**/*.csproj', '**/package-lock.json', '**/pnpm-lock.yaml') }}';
        }

        if ($isNuget -and $isNpm)
        {
            $type = 'nugetnpm'
        }
        elseif ($isNuget)
        {
            $type = 'nuget'
        }
        elseif ($isNpm)
        {
            $type = 'npm'
        }
        else
        {
            exit 0
        }

        Write-CacheConfiguration $isNuget $isNpm "${key}-${type}" $hashes[$type]

    - name: Cache Packages with GitHub Cache
      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
      if: steps.detect-cache-configuration.outputs.cache-enabled == 'true' && !contains(runner.name, 'buildjet') && !contains(runner.name, 'warp')
      with:
        path: ${{ format(steps.detect-cache-configuration.outputs.paths, fromJSON('"\n"')) }}
        key: ${{ steps.detect-cache-configuration.outputs.key }}
        restore-keys: ${{ steps.detect-cache-configuration.outputs.restore-keys }}

    - name: Cache Packages with BuildJet Cache
      uses: buildjet/cache@3e70d19e31d6a8030aeddf6ed8dbe601f94d09f4 # v4.0.2
      if: steps.detect-cache-configuration.outputs.cache-enabled == 'true' && contains(runner.name, 'buildjet')
      with:
        path: ${{ format(steps.detect-cache-configuration.outputs.paths, fromJSON('"\n"')) }}
        key: ${{ steps.detect-cache-configuration.outputs.key }}
        restore-keys: ${{ steps.detect-cache-configuration.outputs.restore-keys }}

    - name: Cache Packages with WarpBuild Cache
      uses: WarpBuilds/cache@dad44e2487e9dc889ad6e6bd198e77bb2d828eee # v2.0.0
      if: steps.detect-cache-configuration.outputs.cache-enabled == 'true' && contains(runner.name, 'warp')
      with:
        path: ${{ format(steps.detect-cache-configuration.outputs.paths, fromJSON('"\n"')) }}
        key: ${{ steps.detect-cache-configuration.outputs.key }}
        restore-keys: ${{ steps.detect-cache-configuration.outputs.restore-keys }}

    - name: Write Desired .NET SDK Version to global.json
      # We do this to force `dotnet build` to use that exact version and avoid breaking builds by silent upgrades.
      shell: pwsh
      working-directory: ${{ inputs.directory }}
      run: |
        # Read from file or use empty object.
        $globalJsonContent = (Test-Path -Path .\global.json -PathType Leaf) ? (Get-Content .\global.json -Raw) : '{}'
        $globalJsonObject = $globalJsonContent | ConvertFrom-Json -AsHashTable

        # Only set the sdk property if it does not exist yet.
        if (-not $globalJsonObject.ContainsKey('sdk'))
        {
            $globalJsonObject['sdk'] = @{
              "version" = $Env:DOTNET_SDK_TO_USE
            }
        }

        # Write back to file.
        $globalJsonObject | ConvertTo-Json | Set-Content .\global.json

    - name: Build and Static Code Analysis
      id: build
      shell: pwsh
      working-directory: ${{ inputs.directory }}
      run: |
        Write-Output "Using .NET SDK from ./global.json:`n$(Get-Content .\global.json -Raw)"

        Initialize-ArtifactNameSuffix '${{ inputs.directory }}'

        $buildSwitches = @'
            ${{ inputs.dotnet-build-switches }}
        '@

        $expectedCodeAnalysisErrors = @'
            ${{ inputs.expected-code-analysis-errors }}
        '@

        # Allowing the use of an empty solution or project path, to enable the default dotnet build behavior of
        # "build the only project or only solution, or fail if there are multiple projects".
        $solutionOrProjectPathInput = '${{ inputs.solution-or-project-path }}'
        $solutionOrProjectPath = $solutionOrProjectPathInput ? (Get-SolutionOrProjectPath $solutionOrProjectPathInput) : ''

        $block = {
            $ErrorActionPreference = 'Stop'
            $buildSwitches = $args[0]

            Build-DotNetSolutionOrProject @buildSwitches

            if ($LASTEXITCODE -gt 0)
            {
                throw "Build failed with exit code $LASTEXITCODE."
            }
        }

        $switches = @{
            Configuration = "${{ inputs.configuration }}"
            SolutionOrProject = $solutionOrProjectPath
            Verbosity = "${{ inputs.verbosity }}"
            EnableCodeAnalysis = "${{ inputs.enable-code-analysis }}"
            Version = "${{ inputs.publish-version }}"
            Switches = $buildSwitches
            ExpectedCodeAnalysisErrors = $expectedCodeAnalysisErrors
            RebuildDirectory = "${{ inputs.rebuild-directory }}"
            CreateBinaryLog = $${{ inputs.create-binary-log }}
            WarningsAsErrors = $${{ inputs.warnings-as-errors }}
        }

        $startTime = [DateTime]::Now
        Invoke-ScriptBlock `
            -TimeoutMinutes ${{ inputs.timeout-minutes }} `
            -Name 'Build-DotNetSolutionOrProject' `
            -ScriptBlock $block `
            -ArgumentList $switches
        $endTime = [DateTime]::Now

        Write-Output ("Solution or project build took {0:0.###} seconds." -f ($endTime - $startTime).TotalSeconds)

    - name: Upload MSBuild Binary Log
      uses: Lombiq/GitHub-Actions/.github/actions/upload-artifact@issue/OSOE-1308
      if: (success() || failure()) && inputs.create-binary-log == 'true'
      with:
        name: build-binary-log-${{ steps.build.outputs.artifact-name-suffix }}.binlog
        path: ${{ inputs.directory }}/build.binlog
        if-no-files-found: ignore
        retention-days: ${{ inputs.binary-log-artifact-retention-days }}

    - name: Run dotnet clean
      if: inputs.dotnet-clean == 'true'
      shell: pwsh
      working-directory: ${{ inputs.directory }}
      run: |
        $solutionOrProjectPathInput = '${{ inputs.solution-or-project-path }}'
        $solutionOrProjectPath = Get-SolutionOrProjectPath ($solutionOrProjectPathInput || '*.sln?')

        $arguments = @(
            $solutionOrProjectPath
            '--configuration', '${{ inputs.configuration }}'
            '--verbosity', '${{ inputs.verbosity }}'
        )

        Write-Output "Running `"dotnet clean $arguments`" in the `"$PWD`" directory."
        # It shouldn't be breaking if clean fails here, so we write out the dotnet version to clean the last exit code.
        dotnet clean @arguments || Write-Output "::warning::The `"dotnet clean $arguments`" command did not finish successfully."
        dotnet --version

    - name: Run git clean
      if: inputs.git-clean == 'true'
      shell: pwsh
      working-directory: ${{ inputs.directory }}
      run: |
        Write-Output "Cleaning out and resetting the git repo in `"$PWD`" and its submodules."
        git reset --hard
        git submodule sync --recursive
        git submodule update --init --force --recursive
        git clean -ffdx
        # We shouldn't fail the run if the cleanout fails for any reason, so " || true" is added to this command.
        git submodule foreach --recursive 'git clean -ffdx || true'