feat: Cache NuGet global-packages folder (#303)

* feat: cache NuGet global-packages folder

* fix: remove unused files

* docs: fix incorrect action

* ci: add e2e test for cache

* docs: accept suggested changes on README

* docs: add simple cache example

* build: change main script path

* fix: change relative path to install scripts

* fix: change relative path to problem matcher

* refactor: accept changes on cache-utils

* fix: revert main script path changes

* test: fix cache-utils unit test

* test: fix cache-utils unit test

* feat: add `cache-dependency-path` variables

* build: change main script dist path

* ci: add `cache-dependency-path` e2e test & missing lock file

* fix: accept change suggestions

* ci: copy NuGet lock file to root

to pass "test-setup-with-cache" e2e test

* docs: change README guide

* fix: apply suggestions from code review

Co-authored-by: Ivan <98037481+IvanZosimov@users.noreply.github.com>

* test: fix some failed unit tests

- fix `restoreCache()` test for 9703c8
- update installer script

* build: rebuild dist

* Update unit-tests
- Additional unit test were added to setup-dotnet.test.ts

* Update unit tests for unix systems

* Format and lint unit tests

* fix: avoid use '/' on `path.join`

* fix: rebuild dist

* fix: apply suggestions from code review

Co-authored-by: Ivan <98037481+IvanZosimov@users.noreply.github.com>

* build: add `DisableImplicitNuGetFallbackFolder` option

also add guide on README

* docs: highlight warnings and notes

* docs: update note about handling NU1403

---------

Co-authored-by: Ivan <98037481+IvanZosimov@users.noreply.github.com>
Co-authored-by: IvanZosimov <ivanzosimov@github.com>

.github/workflows/e2e-tests.yml

@@ -251,6 +251,66 @@ jobs:
         shell: pwsh
         run: __tests__/verify-dotnet.ps1 -Patterns "^7\.0\.\d+-"
 
+  test-setup-with-cache:
+    runs-on: ${{ matrix.operating-system }}
+    strategy:
+      fail-fast: false
+      matrix:
+        operating-system: [ubuntu-latest, windows-latest, macos-latest]
+    env:
+      NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Clear toolcache
+        shell: pwsh
+        run: __tests__/clear-toolcache.ps1 ${{ runner.os }}
+      - name: Copy NuGet lock file to root
+        shell: bash
+        run: cp ./__tests__/e2e-test-csproj/packages.lock.json ./packages.lock.json
+      - name: Setup .NET Core 3.1
+        id: setup-dotnet
+        uses: ./
+        with:
+          dotnet-version: 3.1
+          cache: true
+      - name: Verify Cache
+        if: steps.setup-dotnet.outputs.cache-hit == 'true'
+        shell: bash
+        run: if [[ -e ${NUGET_PACKAGES} ]]; then exit 0; else exit 1; fi
+      - name: Verify dotnet
+        shell: pwsh
+        run: __tests__/verify-dotnet.ps1 -Patterns "^3.1"
+
+  test-setup-with-cache-dependency-path:
+    runs-on: ${{ matrix.operating-system }}
+    strategy:
+      fail-fast: false
+      matrix:
+        operating-system: [ubuntu-latest, windows-latest, macos-latest]
+    env:
+      NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Clear toolcache
+        shell: pwsh
+        run: __tests__/clear-toolcache.ps1 ${{ runner.os }}
+      - name: Setup .NET Core 3.1
+        id: setup-dotnet
+        uses: ./
+        with:
+          dotnet-version: 3.1
+          cache: true
+          cache-dependency-path: './__tests__/e2e-test-csproj/packages.lock.json'
+      - name: Verify Cache
+        if: steps.setup-dotnet.outputs.cache-hit == 'true'
+        shell: bash
+        run: if [[ -e ${NUGET_PACKAGES} ]]; then exit 0; else exit 1; fi
+      - name: Verify dotnet
+        shell: pwsh
+        run: __tests__/verify-dotnet.ps1 -Patterns "^3.1"
+
   test-dotnet-version-output-during-single-version-installation:
     runs-on: ${{ matrix.operating-system }}
     strategy:

.licensed.yml

@@ -3,6 +3,7 @@ sources:
 
 allowed:
   - apache-2.0
+  - 0bsd
   - bsd-2-clause
   - bsd-3-clause
   - isc
@@ -12,3 +13,4 @@ allowed:
 
 reviewed:
   npm:
+    - sax # ISC + MIT

README.md

@@ -82,6 +82,63 @@ steps:
   working-directory: csharp
 ```
 
+## Caching NuGet Packages
+The action has a built-in functionality for caching and restoring dependencies. It uses [toolkit/cache](https://github.com/actions/toolkit/tree/main/packages/cache) under the hood for caching global packages data but requires less configuration settings. The `cache` input is optional, and caching is turned off by default.
+
+The action searches for [NuGet Lock files](https://learn.microsoft.com/nuget/consume-packages/package-references-in-project-files#locking-dependencies) (`packages.lock.json`) in the repository root, calculates their hash and uses it as a part of the cache key. If lock file does not exist, this action throws error. Use `cache-dependency-path` for cases when multiple dependency files are used, or they are located in different subdirectories.
+
+> **Warning**: Caching NuGet packages is available since .NET SDK 2.1.500 and 2.2.100 as the NuGet lock file [is available](https://learn.microsoft.com/nuget/consume-packages/package-references-in-project-files#locking-dependencies) only for NuGet 4.9 and above.
+
+```yaml
+steps:
+- uses: actions/checkout@v3
+- uses: actions/setup-dotnet@v3
+  with:
+    dotnet-version: 6.x
+    cache: true
+- run: dotnet restore --locked-mode
+```
+
+> **Note**: This action will only restore `global-packages` folder, so you will probably get the [NU1403](https://learn.microsoft.com/nuget/reference/errors-and-warnings/nu1403) error when running `dotnet restore`.
+> To avoid this, you can use [`DisableImplicitNuGetFallbackFolder`](https://github.com/dotnet/reproducible-builds/blob/abfe986832aa28597d3340b92469d1a702013d23/Documentation/Reproducible-MSBuild/Techniques/DisableImplicitNuGetFallbackFolder.md) option.
+
+```xml
+<PropertyGroup>
+  <DisableImplicitNuGetFallbackFolder>true</DisableImplicitNuGetFallbackFolder>
+</PropertyGroup>
+```
+
+### Reduce caching size
+
+> **Note**: Use [`NUGET_PACKAGES`](https://learn.microsoft.com/nuget/reference/cli-reference/cli-ref-environment-variables) environment variable if available. Some action runners already has huge libraries. (ex. Xamarin)
+
+```yaml
+env:
+  NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
+steps:
+- uses: actions/checkout@v3
+- uses: actions/setup-dotnet@v3
+  with:
+    dotnet-version: 6.x
+    cache: true
+- run: dotnet restore --locked-mode
+```
+
+### Caching NuGet packages in monorepos
+
+```yaml
+env:
+  NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
+steps:
+- uses: actions/checkout@v3
+- uses: actions/setup-dotnet@v3
+  with:
+    dotnet-version: 6.x
+    cache: true
+    cache-dependency-path: subdir/packages.lock.json
+- run: dotnet restore --locked-mode
+```
+
 ## Matrix Testing
 Using `setup-dotnet` it's possible to use [matrix syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix) to install several versions of .NET SDK:
 ```yml
@@ -214,6 +271,9 @@ When the `dotnet-version` input is used along with the `global-json-file` input,
     - run: echo '${{ steps.stepid.outputs.dotnet-version }}' # outputs 2.2.207
 ```
 
+### `cache-hit`
+A boolean value to indicate an exact match was found for the cache key (follows [actions/cache](https://github.com/actions/cache#outputs))
+
 ## Environment variables
 
 Some environment variables may be necessary for your particular case or to improve logging. Some examples are listed below, but the full list with complete details can be found here: https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-environment-variables
@@ -224,25 +284,28 @@ Some environment variables may be necessary for your particular case or to impro
 | DOTNET_NOLOGO      |Removes logo and telemetry message from first run of dotnet cli|*false*|
 | DOTNET_CLI_TELEMETRY_OPTOUT   |Opt-out of telemetry being sent to Microsoft|*false*|
 | DOTNET_MULTILEVEL_LOOKUP   |Configures whether the global install location is used as a fall-back|*true*|
+| NUGET_PACKAGES |Configures a path to the [NuGet `global-packages` folder](https://learn.microsoft.com/nuget/consume-packages/managing-the-global-packages-and-cache-folders)|*default value for each OS* |
 
-The default value of the `DOTNET_INSTALL_DIR` environment variable depends on the operation system which is used on a runner:
-| **Operation system**      | **Default value** |
-| ----------- | ----------- |
-| **Windows** | `C:\Program Files\dotnet` |
-| **Ubuntu** | `/usr/share/dotnet` |
-| **macOS** | `/Users/runner/.dotnet` |
+The default values of the `DOTNET_INSTALL_DIR` and `NUGET_PACKAGES` environment variables depend on the operation system which is used on a runner:
+| **Operation system** | `DOTNET_INSTALL_DIR` | `NUGET_PACKAGES` |
+| ----------- | ----------- | ----------- |
+| **Windows** | `C:\Program Files\dotnet` | `%userprofile%\.nuget\packages` |
+| **Ubuntu** | `/usr/share/dotnet` | `~/.nuget/packages` |
+| **macOS** | `/Users/runner/.dotnet` | `~/.nuget/packages` |
 
-**Example usage**:
+**Example usage of environment variable**:
 ```yml
 build:
   runs-on: ubuntu-latest
   env:
     DOTNET_INSTALL_DIR: "path/to/directory"
+    NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
   steps:
     - uses: actions/checkout@main
     - uses: actions/setup-dotnet@v3
       with:
         dotnet-version: '3.1.x'
+        cache: true
 ```
 
 ## License

__tests__/cache-restore.test.ts

@@ -0,0 +1,101 @@
+import {readdir} from 'node:fs/promises';
+import * as cache from '@actions/cache';
+import * as core from '@actions/core';
+import * as glob from '@actions/glob';
+import {restoreCache} from '../src/cache-restore';
+import {getNuGetFolderPath} from '../src/cache-utils';
+import {lockFilePatterns} from '../src/constants';
+
+jest.mock('node:fs/promises');
+jest.mock('@actions/cache');
+jest.mock('@actions/core');
+jest.mock('@actions/glob');
+jest.mock('../src/cache-utils');
+
+describe('cache-restore tests', () => {
+  describe.each(lockFilePatterns)('restoreCache("%s")', lockFilePattern => {
+    /** Store original process.env.GITHUB_WORKSPACE */
+    let githubWorkspace: string | undefined;
+    beforeAll(() => {
+      githubWorkspace = process.env.GITHUB_WORKSPACE;
+      jest.mocked(getNuGetFolderPath).mockResolvedValue({
+        'global-packages': 'global-packages',
+        'http-cache': 'http-cache',
+        temp: 'temp',
+        'plugins-cache': 'plugins-cache'
+      });
+    });
+    beforeEach(() => {
+      process.env.GITHUB_WORKSPACE = './';
+      jest.mocked(glob.hashFiles).mockClear();
+      jest.mocked(core.saveState).mockClear();
+      jest.mocked(core.setOutput).mockClear();
+      jest.mocked(cache.restoreCache).mockClear();
+    });
+    afterEach(() => (process.env.GITHUB_WORKSPACE = githubWorkspace));
+
+    it('throws error when lock file is not found', async () => {
+      jest.mocked(glob.hashFiles).mockResolvedValue('');
+
+      await expect(restoreCache(lockFilePattern)).rejects.toThrow();
+
+      expect(jest.mocked(core.saveState)).not.toHaveBeenCalled();
+      expect(jest.mocked(core.setOutput)).not.toHaveBeenCalled();
+      expect(jest.mocked(cache.restoreCache)).not.toHaveBeenCalled();
+    });
+
+    it('does not call core.saveState("CACHE_RESULT") when cache.restoreCache() returns falsy', async () => {
+      jest.mocked(glob.hashFiles).mockResolvedValue('hash');
+      jest.mocked(cache.restoreCache).mockResolvedValue(undefined);
+
+      await restoreCache(lockFilePattern);
+
+      const expectedKey = `dotnet-cache-${process.env.RUNNER_OS}-hash`;
+      expect(jest.mocked(core.saveState)).toHaveBeenCalledWith(
+        'CACHE_KEY',
+        expectedKey
+      );
+      expect(jest.mocked(core.saveState)).not.toHaveBeenCalledWith(
+        'CACHE_RESULT',
+        expectedKey
+      );
+      expect(jest.mocked(core.setOutput)).toHaveBeenCalledWith(
+        'cache-hit',
+        false
+      );
+    });
+
+    it('calls core.saveState("CACHE_RESULT") when cache.restoreCache() returns key', async () => {
+      const expectedKey = `dotnet-cache-${process.env.RUNNER_OS}-hash`;
+      jest.mocked(glob.hashFiles).mockResolvedValue('hash');
+      jest.mocked(cache.restoreCache).mockResolvedValue(expectedKey);
+
+      await restoreCache(lockFilePattern);
+
+      expect(jest.mocked(core.saveState)).toHaveBeenCalledWith(
+        'CACHE_KEY',
+        expectedKey
+      );
+      expect(jest.mocked(core.saveState)).toHaveBeenCalledWith(
+        'CACHE_RESULT',
+        expectedKey
+      );
+      expect(jest.mocked(core.setOutput)).toHaveBeenCalledWith(
+        'cache-hit',
+        true
+      );
+    });
+
+    it('calls glob.hashFiles("/packages.lock.json") if cacheDependencyPath is falsy', async () => {
+      const expectedKey = `dotnet-cache-${process.env.RUNNER_OS}-hash`;
+      jest.mocked(glob.hashFiles).mockResolvedValue('hash');
+      jest.mocked(cache.restoreCache).mockResolvedValue(expectedKey);
+      jest.mocked(readdir).mockResolvedValue([lockFilePattern] as any);
+
+      await restoreCache('');
+
+      expect(jest.mocked(glob.hashFiles)).not.toHaveBeenCalledWith('');
+      expect(jest.mocked(glob.hashFiles)).toHaveBeenCalledWith(lockFilePattern);
+    });
+  });
+});

__tests__/cache-save.test.ts

@@ -0,0 +1,87 @@
+import * as cache from '@actions/cache';
+import * as core from '@actions/core';
+import fs from 'node:fs';
+import {run} from '../src/cache-save';
+import {getNuGetFolderPath} from '../src/cache-utils';
+
+jest.mock('@actions/cache');
+jest.mock('@actions/core');
+jest.mock('node:fs');
+jest.mock('../src/cache-utils');
+
+describe('cache-save tests', () => {
+  beforeAll(() => {
+    jest.mocked(getNuGetFolderPath).mockResolvedValue({
+      'global-packages': 'global-packages',
+      'http-cache': 'http-cache',
+      temp: 'temp',
+      'plugins-cache': 'plugins-cache'
+    });
+  });
+  beforeEach(() => {
+    jest.mocked(core.setFailed).mockClear();
+    jest.mocked(core.getState).mockClear();
+    jest.mocked(core.setOutput).mockClear();
+    jest.mocked(cache.saveCache).mockClear();
+    jest.mocked(fs.existsSync).mockClear();
+  });
+
+  it('does not save cache when inputs:cache === false', async () => {
+    jest.mocked(core.getBooleanInput).mockReturnValue(false);
+
+    await run();
+
+    expect(jest.mocked(core.setFailed)).not.toHaveBeenCalled();
+    expect(jest.mocked(core.getState)).not.toHaveBeenCalled();
+    expect(jest.mocked(fs.existsSync)).not.toHaveBeenCalled();
+    expect(jest.mocked(cache.saveCache)).not.toHaveBeenCalled();
+  });
+
+  it('does not save cache when core.getState("CACHE_KEY") returns ""', async () => {
+    jest.mocked(core.getBooleanInput).mockReturnValue(true);
+    jest.mocked(core.getState).mockReturnValue('');
+
+    await run();
+
+    expect(jest.mocked(core.setFailed)).not.toHaveBeenCalled();
+    expect(jest.mocked(core.getState)).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(fs.existsSync)).not.toHaveBeenCalled();
+    expect(jest.mocked(cache.saveCache)).not.toHaveBeenCalled();
+  });
+
+  it('throws Error when cachePath not exists', async () => {
+    jest.mocked(core.getBooleanInput).mockReturnValue(true);
+    jest.mocked(core.getState).mockReturnValue('cache-key');
+    jest.mocked(fs.existsSync).mockReturnValue(false);
+
+    await run();
+
+    expect(jest.mocked(core.setFailed)).toHaveBeenCalled();
+    expect(jest.mocked(core.getState)).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(cache.saveCache)).not.toHaveBeenCalled();
+  });
+
+  it('does not save cache when state.CACHE_KEY === state.CACHE_RESULT', async () => {
+    jest.mocked(core.getBooleanInput).mockReturnValue(true);
+    jest.mocked(core.getState).mockReturnValue('cache-key');
+    jest.mocked(fs.existsSync).mockReturnValue(true);
+
+    await run();
+
+    expect(jest.mocked(core.setFailed)).not.toHaveBeenCalled();
+    expect(jest.mocked(core.getState)).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(cache.saveCache)).not.toHaveBeenCalled();
+  });
+
+  it('saves cache when state.CACHE_KEY !== state.CACHE_RESULT', async () => {
+    jest.mocked(core.getBooleanInput).mockReturnValue(true);
+    jest.mocked(core.getState).mockImplementation(s => s);
+    jest.mocked(fs.existsSync).mockReturnValue(true);
+
+    await run();
+
+    expect(jest.mocked(core.setFailed)).not.toHaveBeenCalled();
+    expect(jest.mocked(core.getState)).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(cache.saveCache)).toHaveBeenCalled();
+  });
+});

__tests__/cache-utils.test.ts

@@ -0,0 +1,122 @@
+import * as cache from '@actions/cache';
+import * as exec from '@actions/exec';
+
+import {getNuGetFolderPath, isCacheFeatureAvailable} from '../src/cache-utils';
+
+jest.mock('@actions/cache');
+jest.mock('@actions/core');
+jest.mock('@actions/exec');
+
+describe('cache-utils tests', () => {
+  describe('getNuGetFolderPath()', () => {
+    it.each([
+      [
+        `
+http-cache: /home/codespace/.local/share/NuGet/v3-cache
+global-packages: /var/nuget
+temp: /tmp/NuGetScratch
+plugins-cache: /home/codespace/.local/share/NuGet/plugins-cache
+`,
+        {
+          'http-cache': '/home/codespace/.local/share/NuGet/v3-cache',
+          'global-packages': '/var/nuget',
+          temp: '/tmp/NuGetScratch',
+          'plugins-cache': '/home/codespace/.local/share/NuGet/plugins-cache'
+        }
+      ],
+      [
+        `
+  http-cache: /home/codespace/.local/share/NuGet/v3-cache
+  global-packages: /var/nuget
+  temp: /tmp/NuGetScratch
+  plugins-cache: /home/codespace/.local/share/NuGet/plugins-cache
+`,
+        {
+          'http-cache': '/home/codespace/.local/share/NuGet/v3-cache',
+          'global-packages': '/var/nuget',
+          temp: '/tmp/NuGetScratch',
+          'plugins-cache': '/home/codespace/.local/share/NuGet/plugins-cache'
+        }
+      ],
+      [
+        `
+http-cache: C:\\Users\\user\\AppData\\Local\\NuGet\\v3-cache
+global-packages: C:\\Users\\user\\.nuget\\packages\\
+temp: C:\\Users\\user\\AppData\\Local\\Temp\\NuGetScratch
+plugins-cache: C:\\Users\\user\\AppData\\Local\\NuGet\\plugins-cache
+        `,
+        {
+          'http-cache': 'C:\\Users\\user\\AppData\\Local\\NuGet\\v3-cache',
+          'global-packages': 'C:\\Users\\user\\.nuget\\packages\\',
+          temp: 'C:\\Users\\user\\AppData\\Local\\Temp\\NuGetScratch',
+          'plugins-cache':
+            'C:\\Users\\user\\AppData\\Local\\NuGet\\plugins-cache'
+        }
+      ],
+      [
+        `
+  http-cache: C:\\Users\\user\\AppData\\Local\\NuGet\\v3-cache
+  global-packages: C:\\Users\\user\\.nuget\\packages\\
+  temp: C:\\Users\\user\\AppData\\Local\\Temp\\NuGetScratch
+  plugins-cache: C:\\Users\\user\\AppData\\Local\\NuGet\\plugins-cache
+        `,
+        {
+          'http-cache': 'C:\\Users\\user\\AppData\\Local\\NuGet\\v3-cache',
+          'global-packages': 'C:\\Users\\user\\.nuget\\packages\\',
+          temp: 'C:\\Users\\user\\AppData\\Local\\Temp\\NuGetScratch',
+          'plugins-cache':
+            'C:\\Users\\user\\AppData\\Local\\NuGet\\plugins-cache'
+        }
+      ]
+    ])('(stdout: "%s") returns %p', async (stdout, expected) => {
+      jest
+        .mocked(exec.getExecOutput)
+        .mockResolvedValue({stdout, stderr: '', exitCode: 0});
+      const pathes = await getNuGetFolderPath();
+      expect(pathes).toStrictEqual(expected);
+    });
+
+    it.each([
+      `
+error: An invalid local resource name was provided. Provide one of the following values: http-cache, temp, global-packages, all.
+Usage: dotnet nuget locals [arguments] [options]
+Arguments:
+  Cache Location(s)  Specifies the cache location(s) to list or clear.
+<all | http-cache | global-packages | temp>
+Options:
+  -h|--help               Show help information
+  --force-english-output  Forces the application to run using an invariant, English-based culture.
+  -c|--clear              Clear the selected local resources or cache location(s).
+  -l|--list               List the selected local resources or cache location(s).
+      `,
+      'bash: dotnet: command not found',
+      ''
+    ])('(stderr: "%s", exitCode: 1) throws Error', async stderr => {
+      jest
+        .mocked(exec.getExecOutput)
+        .mockResolvedValue({stdout: '', stderr, exitCode: 1});
+      await expect(getNuGetFolderPath()).rejects.toThrow();
+    });
+  });
+
+  describe.each(['', 'https://github.com/', 'https://example.com/'])(
+    'isCacheFeatureAvailable()',
+    url => {
+      // Save & Restore env
+      let serverUrlEnv: string | undefined;
+      beforeAll(() => (serverUrlEnv = process.env['GITHUB_SERVER_URL']));
+      beforeEach(() => (process.env['GITHUB_SERVER_URL'] = url));
+      afterEach(() => (process.env['GITHUB_SERVER_URL'] = serverUrlEnv));
+
+      it('returns true when cache.isFeatureAvailable() === true', () => {
+        jest.mocked(cache.isFeatureAvailable).mockReturnValue(true);
+        expect(isCacheFeatureAvailable()).toBe(true);
+      });
+
+      it('returns false when cache.isFeatureAvailable() === false', () => {
+        jest.mocked(cache.isFeatureAvailable).mockReturnValue(false);
+        expect(isCacheFeatureAvailable()).toBe(false);
+      });
+    }
+  );
+});

__tests__/e2e-test-csproj/test.csproj

@@ -3,6 +3,7 @@
   <PropertyGroup>
     <TargetFramework>$(TEST_TARGET_FRAMEWORK)</TargetFramework>
     <IsPackable>false</IsPackable>
+    <DisableImplicitNuGetFallbackFolder>true</DisableImplicitNuGetFallbackFolder>
   </PropertyGroup>
 
   <ItemGroup>

__tests__/installer.test.ts

@@ -1,5 +1,7 @@
 import each from 'jest-each';
 import semver from 'semver';
+import fs from 'fs';
+import fspromises from 'fs/promises';
 import * as exec from '@actions/exec';
 import * as core from '@actions/core';
 import * as io from '@actions/io';
@@ -21,14 +23,25 @@ describe('installer tests', () => {
     const warningSpy = jest.spyOn(core, 'warning');
     const whichSpy = jest.spyOn(io, 'which');
     const maxSatisfyingSpy = jest.spyOn(semver, 'maxSatisfying');
+    const chmodSyncSpy = jest.spyOn(fs, 'chmodSync');
+    const readdirSpy = jest.spyOn(fspromises, 'readdir');
 
     describe('installDotnet() tests', () => {
+      beforeAll(() => {
         whichSpy.mockImplementation(() => Promise.resolve('PathToShell'));
+        chmodSyncSpy.mockImplementation(() => {});
+        readdirSpy.mockImplementation(() => Promise.resolve([]));
+      });
+
+      afterAll(() => {
+        jest.resetAllMocks();
+      });
 
       it('should throw the error in case of non-zero exit code of the installation script. The error message should contain logs.', async () => {
         const inputVersion = '3.1.100';
         const inputQuality = '' as QualityOptions;
         const errorMessage = 'fictitious error message!';
+
         getExecOutputSpy.mockImplementation(() => {
           return Promise.resolve({
             exitCode: 1,
@@ -36,6 +49,7 @@ describe('installer tests', () => {
             stderr: errorMessage
           });
         });
+
         const dotnetInstaller = new installer.DotnetCoreInstaller(
           inputVersion,
           inputQuality

__tests__/setup-dotnet.test.ts

@@ -5,12 +5,15 @@ import * as auth from '../src/authutil';
 
 import * as setup from '../src/setup-dotnet';
 import {DotnetCoreInstaller} from '../src/installer';
+import * as cacheUtils from '../src/cache-utils';
+import * as cacheRestore from '../src/cache-restore';
 
 describe('setup-dotnet tests', () => {
   const inputs = {} as any;
 
   const getInputSpy = jest.spyOn(core, 'getInput');
   const getMultilineInputSpy = jest.spyOn(core, 'getMultilineInput');
+  const getBooleanInputSpy = jest.spyOn(core, 'getBooleanInput');
   const setFailedSpy = jest.spyOn(core, 'setFailed');
   const warningSpy = jest.spyOn(core, 'warning');
   const debugSpy = jest.spyOn(core, 'debug');
@@ -26,13 +29,18 @@ describe('setup-dotnet tests', () => {
     'installDotnet'
   );
   const addToPathSpy = jest.spyOn(DotnetCoreInstaller, 'addToPath');
-
+  const isCacheFeatureAvailableSpy = jest.spyOn(
+    cacheUtils,
+    'isCacheFeatureAvailable'
+  );
+  const restoreCacheSpy = jest.spyOn(cacheRestore, 'restoreCache');
   const configAuthenticationSpy = jest.spyOn(auth, 'configAuthentication');
 
   describe('run() tests', () => {
     beforeEach(() => {
       getMultilineInputSpy.mockImplementation(input => inputs[input as string]);
       getInputSpy.mockImplementation(input => inputs[input as string]);
+      getBooleanInputSpy.mockImplementation(input => inputs[input as string]);
     });
 
     afterEach(() => {
@@ -169,5 +177,54 @@ describe('setup-dotnet tests', () => {
       expect(infoSpy).toHaveBeenCalledWith(warningMessage);
       expect(setOutputSpy).not.toHaveBeenCalled();
     });
+
+    it(`should get 'cache-dependency-path' and call restoreCache() if input cache is set to true and cache feature is available`, async () => {
+      inputs['dotnet-version'] = ['6.0.300'];
+      inputs['dotnet-quality'] = '';
+      inputs['cache'] = true;
+      inputs['cache-dependency-path'] = 'fictitious.package.lock.json';
+
+      installDotnetSpy.mockImplementation(() => Promise.resolve(''));
+      addToPathSpy.mockImplementation(() => {});
+
+      isCacheFeatureAvailableSpy.mockImplementation(() => true);
+      restoreCacheSpy.mockImplementation(() => Promise.resolve());
+
+      await setup.run();
+      expect(isCacheFeatureAvailableSpy).toHaveBeenCalledTimes(1);
+      expect(restoreCacheSpy).toHaveBeenCalledWith(
+        inputs['cache-dependency-path']
+      );
+    });
+
+    it(`shouldn't call restoreCache() if input cache isn't set to true`, async () => {
+      inputs['dotnet-version'] = ['6.0.300'];
+      inputs['dotnet-quality'] = '';
+      inputs['cache'] = false;
+
+      installDotnetSpy.mockImplementation(() => Promise.resolve(''));
+      addToPathSpy.mockImplementation(() => {});
+
+      isCacheFeatureAvailableSpy.mockImplementation(() => true);
+      restoreCacheSpy.mockImplementation(() => Promise.resolve());
+
+      await setup.run();
+      expect(restoreCacheSpy).not.toHaveBeenCalled();
+    });
+
+    it(`shouldn't call restoreCache() if cache feature isn't available`, async () => {
+      inputs['dotnet-version'] = ['6.0.300'];
+      inputs['dotnet-quality'] = '';
+      inputs['cache'] = true;
+
+      installDotnetSpy.mockImplementation(() => Promise.resolve(''));
+      addToPathSpy.mockImplementation(() => {});
+
+      isCacheFeatureAvailableSpy.mockImplementation(() => false);
+      restoreCacheSpy.mockImplementation(() => Promise.resolve());
+
+      await setup.run();
+      expect(restoreCacheSpy).not.toHaveBeenCalled();
+    });
   });
 });

action.yml

@@ -17,9 +17,20 @@ inputs:
     description: 'Optional OWNER for using packages from GitHub Package Registry organizations/users other than the current repository''s owner. Only used if a GPR URL is also provided in source-url'
   config-file:
     description: 'Optional NuGet.config location, if your NuGet.config isn''t located in the root of the repo.'
+  cache:
+    description: 'Optional input to enable caching of the NuGet global-packages folder'
+    required: false
+    default: false
+  cache-dependency-path:
+    description: 'Used to specify the path to a dependency file: packages.lock.json. Supports wildcards or a list of file names for caching multiple dependencies.'
+    required: false
 outputs:
+  cache-hit:
+    description: 'A boolean value to indicate if a cache was hit.'
   dotnet-version:
     description: 'Contains the installed by action .NET SDK version for reuse.'
 runs:
   using: 'node16'
-  main: 'dist/index.js'
+  main: 'dist/setup/index.js'
+  post: 'dist/cache-save/index.js'
+  post-if: success()

package.json

@@ -3,9 +3,9 @@
   "version": "3.0.2",
   "private": true,
   "description": "setup dotnet action",
-  "main": "lib/setup-dotnet.js",
+  "main": "dist/setup/index.js",
   "scripts": {
-    "build": "tsc && ncc build",
+    "build": "ncc build -o dist/setup src/setup-dotnet.ts && ncc build -o dist/cache-save src/cache-save.ts",
     "format": "prettier --no-error-on-unmatched-pattern --config ./.prettierrc.js --write \"**/*.{ts,yml,yaml}\"",
     "format-check": "prettier --no-error-on-unmatched-pattern --config ./.prettierrc.js --check \"**/*.{ts,yml,yaml}\"",
     "lint": "eslint --config ./.eslintrc.js \"**/*.ts\"",
@@ -26,29 +26,31 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
+    "@actions/cache": "^3.0.0",
     "@actions/core": "^1.10.0",
-    "@actions/exec": "^1.0.4",
+    "@actions/exec": "^1.1.1",
     "@actions/github": "^1.1.0",
+    "@actions/glob": "^0.3.0",
     "@actions/http-client": "^2.0.1",
     "@actions/io": "^1.0.2",
     "fast-xml-parser": "^4.0.10",
     "semver": "^6.3.0"
   },
   "devDependencies": {
-    "@types/jest": "^27.0.2",
+    "@types/jest": "^27.5.2",
     "@types/node": "^16.11.25",
     "@types/semver": "^6.2.2",
     "@typescript-eslint/eslint-plugin": "^5.54.0",
     "@typescript-eslint/parser": "^5.54.0",
-    "@vercel/ncc": "^0.33.4",
+    "@vercel/ncc": "^0.34.0",
     "eslint": "^8.35.0",
     "eslint-config-prettier": "^8.6.0",
     "eslint-plugin-jest": "^27.2.1",
     "eslint-plugin-node": "^11.1.0",
     "husky": "^8.0.1",
-    "jest": "^27.2.5",
-    "jest-circus": "^27.2.5",
-    "jest-each": "^27.2.5",
+    "jest": "^27.5.1",
+    "jest-circus": "^27.5.1",
+    "jest-each": "^27.5.1",
     "prettier": "^2.8.4",
     "ts-jest": "^27.0.5",
     "typescript": "^4.8.4",

src/cache-restore.ts

@@ -0,0 +1,50 @@
+import {readdir} from 'node:fs/promises';
+import {join} from 'node:path';
+import * as cache from '@actions/cache';
+import * as core from '@actions/core';
+import * as glob from '@actions/glob';
+
+import {getNuGetFolderPath} from './cache-utils';
+import {lockFilePatterns, State, Outputs} from './constants';
+
+export const restoreCache = async (cacheDependencyPath?: string) => {
+  const lockFilePath = cacheDependencyPath || (await findLockFile());
+  const fileHash = await glob.hashFiles(lockFilePath);
+  if (!fileHash) {
+    throw new Error(
+      'Some specified paths were not resolved, unable to cache dependencies.'
+    );
+  }
+
+  const platform = process.env.RUNNER_OS;
+  const primaryKey = `dotnet-cache-${platform}-${fileHash}`;
+  core.debug(`primary key is ${primaryKey}`);
+
+  core.saveState(State.CachePrimaryKey, primaryKey);
+
+  const {'global-packages': cachePath} = await getNuGetFolderPath();
+  const cacheKey = await cache.restoreCache([cachePath], primaryKey);
+  core.setOutput(Outputs.CacheHit, Boolean(cacheKey));
+
+  if (!cacheKey) {
+    core.info('Dotnet cache is not found');
+    return;
+  }
+
+  core.saveState(State.CacheMatchedKey, cacheKey);
+  core.info(`Cache restored from key: ${cacheKey}`);
+};
+
+const findLockFile = async () => {
+  const workspace = process.env.GITHUB_WORKSPACE!;
+  const rootContent = await readdir(workspace);
+
+  const lockFile = lockFilePatterns.find(item => rootContent.includes(item));
+  if (!lockFile) {
+    throw new Error(
+      `Dependencies lock file is not found in ${workspace}. Supported file patterns: ${lockFilePatterns.toString()}`
+    );
+  }
+
+  return join(workspace, lockFile);
+};

src/cache-save.ts

@@ -0,0 +1,57 @@
+import * as core from '@actions/core';
+import * as cache from '@actions/cache';
+import fs from 'node:fs';
+import {getNuGetFolderPath} from './cache-utils';
+import {State} from './constants';
+
+// Catch and log any unhandled exceptions.  These exceptions can leak out of the uploadChunk method in
+// @actions/toolkit when a failed upload closes the file descriptor causing any in-process reads to
+// throw an uncaught exception.  Instead of failing this action, just warn.
+process.on('uncaughtException', e => {
+  const warningPrefix = '[warning]';
+  core.info(`${warningPrefix}${e.message}`);
+});
+
+export async function run() {
+  try {
+    if (core.getBooleanInput('cache')) {
+      await cachePackages();
+    }
+  } catch (error) {
+    core.setFailed(error.message);
+  }
+}
+
+const cachePackages = async () => {
+  const state = core.getState(State.CacheMatchedKey);
+  const primaryKey = core.getState(State.CachePrimaryKey);
+
+  if (!primaryKey) {
+    core.info('Primary key was not generated, not saving cache.');
+    return;
+  }
+
+  const {'global-packages': cachePath} = await getNuGetFolderPath();
+
+  if (!fs.existsSync(cachePath)) {
+    throw new Error(
+      `Cache folder path is retrieved for .NET CLI but doesn't exist on disk: ${cachePath}`
+    );
+  }
+
+  if (primaryKey === state) {
+    core.info(
+      `Cache hit occurred on the primary key ${primaryKey}, not saving cache.`
+    );
+    return;
+  }
+
+  const cacheId = await cache.saveCache([cachePath], primaryKey);
+  if (cacheId == -1) {
+    return;
+  }
+
+  core.info(`Cache saved with the key: ${primaryKey}`);
+};
+
+run();

src/cache-utils.ts

@@ -0,0 +1,98 @@
+import * as cache from '@actions/cache';
+import * as core from '@actions/core';
+import * as exec from '@actions/exec';
+
+import {cliCommand} from './constants';
+
+type NuGetFolderName =
+  | 'http-cache'
+  | 'global-packages'
+  | 'temp'
+  | 'plugins-cache';
+
+/**
+ * Get NuGet global packages, cache, and temp folders from .NET CLI.
+ * @returns (Folder Name)-(Path) mappings
+ * @see https://docs.microsoft.com/nuget/consume-packages/managing-the-global-packages-and-cache-folders
+ * @example
+ * Windows
+ * ```json
+ * {
+ *   "http-cache": "C:\\Users\\user1\\AppData\\Local\\NuGet\\v3-cache",
+ *   "global-packages": "C:\\Users\\user1\\.nuget\\packages\\",
+ *   "temp": "C:\\Users\\user1\\AppData\\Local\\Temp\\NuGetScratch",
+ *   "plugins-cache": "C:\\Users\\user1\\AppData\\Local\\NuGet\\plugins-cache"
+ * }
+ * ```
+ *
+ * Mac/Linux
+ * ```json
+ * {
+ *   "http-cache": "/home/user1/.local/share/NuGet/v3-cache",
+ *   "global-packages": "/home/user1/.nuget/packages/",
+ *   "temp": "/tmp/NuGetScratch",
+ *   "plugins-cache": "/home/user1/.local/share/NuGet/plugins-cache"
+ * }
+ * ```
+ */
+export const getNuGetFolderPath = async () => {
+  const {stdout, stderr, exitCode} = await exec.getExecOutput(
+    cliCommand,
+    undefined,
+    {ignoreReturnCode: true, silent: true}
+  );
+
+  if (exitCode) {
+    throw new Error(
+      !stderr.trim()
+        ? `The '${cliCommand}' command failed with exit code: ${exitCode}`
+        : stderr
+    );
+  }
+
+  const result: Record<NuGetFolderName, string> = {
+    'http-cache': '',
+    'global-packages': '',
+    temp: '',
+    'plugins-cache': ''
+  };
+
+  const regex = /(?:^|\s)(?<key>[a-z-]+): (?<path>.+[/\\].+)$/gm;
+
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(stdout)) !== null) {
+    const key = match.groups!.key;
+    if ((key as NuGetFolderName) in result) {
+      result[key] = match.groups!.path;
+    }
+  }
+
+  return result;
+};
+
+export function isCacheFeatureAvailable(): boolean {
+  if (cache.isFeatureAvailable()) {
+    return true;
+  }
+
+  if (isGhes()) {
+    core.warning(
+      'Cache action is only supported on GHES version >= 3.5. If you are on version >=3.5 Please check with GHES admin if Actions cache service is enabled or not.'
+    );
+    return false;
+  }
+  core.warning(
+    'The runner was not able to contact the cache service. Caching will be skipped'
+  );
+
+  return false;
+}
+
+/**
+ * Returns this action runs on GitHub Enterprise Server or not.
+ * (port from https://github.com/actions/toolkit/blob/457303960f03375db6f033e214b9f90d79c3fe5c/packages/cache/src/internal/cacheUtils.ts#L134)
+ */
+function isGhes(): boolean {
+  const url = process.env['GITHUB_SERVER_URL'] || 'https://github.com';
+  return new URL(url).hostname.toUpperCase() !== 'GITHUB.COM';
+}

src/constants.ts

@@ -0,0 +1,19 @@
+/** NuGet lock file patterns */
+export const lockFilePatterns = ['packages.lock.json'];
+
+/**
+ * .NET CLI command to list local NuGet resources.
+ * @see https://docs.microsoft.com/dotnet/core/tools/dotnet-nuget-locals
+ */
+export const cliCommand =
+  'dotnet nuget locals all --list --force-english-output';
+
+export enum State {
+  CachePrimaryKey = 'CACHE_KEY',
+  CacheMatchedKey = 'CACHE_RESULT'
+}
+
+export enum Outputs {
+  CacheHit = 'cache-hit',
+  DotnetVersion = 'dotnet-version'
+}

src/installer.ts

@@ -203,7 +203,7 @@ export class DotnetCoreInstaller {
     ];
     const scriptName = IS_WINDOWS ? 'install-dotnet.ps1' : 'install-dotnet.sh';
     const escapedScript = path
-      .join(__dirname, '..', 'externals', scriptName)
+      .join(__dirname, '..', '..', 'externals', scriptName)
       .replace(/'/g, "''");
     let scriptArguments: string[];
     let scriptPath = '';

src/setup-dotnet.ts

@@ -4,6 +4,9 @@ import * as fs from 'fs';
 import path from 'path';
 import semver from 'semver';
 import * as auth from './authutil';
+import {isCacheFeatureAvailable} from './cache-utils';
+import {restoreCache} from './cache-restore';
+import {Outputs} from './constants';
 
 const qualityOptions = [
   'daily',
@@ -80,7 +83,12 @@ export async function run() {
 
     outputInstalledVersion(installedDotnetVersions, globalJsonFileInput);
 
-    const matchersPath = path.join(__dirname, '..', '.github');
+    if (core.getBooleanInput('cache') && isCacheFeatureAvailable()) {
+      const cacheDependencyPath = core.getInput('cache-dependency-path');
+      await restoreCache(cacheDependencyPath);
+    }
+
+    const matchersPath = path.join(__dirname, '..', '..', '.github');
     core.info(`##[add-matcher]${path.join(matchersPath, 'csc.json')}`);
   } catch (error) {
     core.setFailed(error.message);
@@ -109,20 +117,20 @@ function outputInstalledVersion(
   globalJsonFileInput: string
 ): void {
   if (!installedVersions.length) {
-    core.info(`The 'dotnet-version' output will not be set.`);
+    core.info(`The '${Outputs.DotnetVersion}' output will not be set.`);
     return;
   }
 
   if (installedVersions.includes(null)) {
     core.warning(
-      `Failed to output the installed version of .NET. The 'dotnet-version' output will not be set.`
+      `Failed to output the installed version of .NET. The '${Outputs.DotnetVersion}' output will not be set.`
     );
     return;
   }
 
   if (globalJsonFileInput) {
     const versionToOutput = installedVersions.at(-1); // .NET SDK version parsed from the global.json file is installed last
-    core.setOutput('dotnet-version', versionToOutput);
+    core.setOutput(Outputs.DotnetVersion, versionToOutput);
     return;
   }
 
@@ -134,7 +142,7 @@ function outputInstalledVersion(
     }
   );
 
-  core.setOutput('dotnet-version', versionToOutput);
+  core.setOutput(Outputs.DotnetVersion, versionToOutput);
 }
 
 run();