> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/nuget.md).

# NuGet

NuGet - host .NET packages in Harness Artifacts

Use a **NuGet** registry to host private NuGet packages. The registry works with the NuGet CLI, the .NET CLI, Visual Studio, and PowerShell.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install the NuGet CLI (`nuget`), the .NET CLI (`dotnet`), Visual Studio, or PowerShell with the `Microsoft.PowerShell.PSResourceGet` module on your local machine.
* Install the Harness CLI (`hc`). You use it to publish packages to your registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a NuGet Registry

To create a NuGet registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.

{% hint style="info" %}
**Private registries**

A private NuGet registry restricts package push and pull access to users with the required permissions in your Harness account.
{% endhint %}

6. Select **NuGet** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch NuGet packages from external sources, such as NuGet.org, when they are not available locally. The default upstream is NuGet.org.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **NuGet** as the **Registry type**.
7. Select the **Source**: **NuGet.org** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL** (for example, `https://api.nuget.org/v3/index.json`).
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required. This works for public NuGet feeds.
9. Optionally, configure **Metadata configuration**.
   * **Metadata cache TTL (seconds)**: How long Harness caches package metadata from the upstream source before it checks the source again.
   * **Negative cache TTL (seconds)**: How long Harness caches a package-not-found response from the upstream source before it checks the source again.
10. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing NuGet registry.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a package is not found in your Harness registry, the upstream proxy fetches it from NuGet.org or your custom source and caches it.
{% endhint %}

## NuGet client setup

In your NuGet Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for the NuGet CLI, the .NET CLI, Visual Studio, or PowerShell.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your NuGet Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. Use the token in place of `<TOKEN>` in the following steps.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Select **NuGet**, **Dotnet**, **Visual Studio**, or **PowerShell** for your client. In the code samples, replace the values in angle brackets with your own values.

{% tabs %}
{% tab title="NuGet" %}
**1. Configure authentication**

Add the Harness Registry as a package source:

```bash
nuget sources add -Name harness -Source https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/index.json -Username <USERNAME> -Password <TOKEN>
nuget setapikey <TOKEN> -Source harness
```

{% hint style="info" %}
**NuGet V2 clients**

For a NuGet V2 client, use `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/` instead of the V3 index URL.
{% endhint %}

**2. Publish the package**

Publish your package:

```bash
nuget push <PACKAGE_FILE> -Source harness
```

{% hint style="info" %}
**Publishing to a nested path**

To publish a package under a sub-directory in the registry, target that path directly:

```bash
nuget push <PACKAGE_FILE> -Source https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/<SUB_DIRECTORY> -ApiKey <TOKEN>
```

{% endhint %}

**3. Use the package**

Install a package from the registry:

```bash
nuget install <ARTIFACT_NAME> -Version <VERSION> -Source harness
```

{% endtab %}

{% tab title="Dotnet" %}
**1. Configure authentication**

Add the Harness Registry as a package source:

```bash
dotnet nuget add source https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/index.json --name harness --username <USERNAME> --password <TOKEN> --store-password-in-clear-text
```

{% hint style="warning" %}
`--store-password-in-clear-text` stores the token in plaintext in your NuGet config file (`~/.nuget/NuGet/NuGet.Config` on macOS/Linux, `%AppData%\NuGet\NuGet.Config` on Windows). Do not use this approach on shared machines. For CI/CD pipelines, pass the token through an environment variable and use `dotnet nuget update source` or a `nuget.config` with a credential provider instead.
{% endhint %}

{% hint style="info" %}
**NuGet V2 clients**

For a NuGet V2 client, use `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/` instead of the V3 index URL.
{% endhint %}

**2. Publish the package**

Publish your package:

```bash
dotnet nuget push <PACKAGE_FILE> --api-key <TOKEN> --source harness
```

{% hint style="info" %}
**Publishing to a nested path**

To publish a package under a sub-directory in the registry, target that path directly:

```bash
dotnet nuget push <PACKAGE_FILE> --source https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/<SUB_DIRECTORY> --api-key <TOKEN>
```

{% endhint %}

**3. Use the package**

Add a package reference to your project:

```bash
dotnet add package <ARTIFACT_NAME> --version <VERSION> --source harness
```

{% endtab %}

{% tab title="Visual Studio" %}
**1. Configure authentication**

1. Select **Tools** > **NuGet Package Manager** > **Package Manager Settings**.
2. Select **Package Sources**. Note the location of your `NuGet.Config` file shown at the top of the window. You can edit this file directly instead of using the UI.
3. Select **+** to add a new package source.
4. Set the **Name** to `harness`.
5. Set the **Source** to `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/index.json`.
6. Select **Update**, then select **OK**.

Alternatively, add the source directly to your `NuGet.Config` file:

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="harness" value="https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <harness>
      <add key="Username" value="<USERNAME>" />
      <add key="ClearTextPassword" value="<TOKEN>" />
    </harness>
  </packageSourceCredentials>
</configuration>
```

{% hint style="info" %}
**Client setup details**

Copy this `NuGet.Config` block directly from **Setup Client** in your registry, with your account ID and registry name already filled in.
{% endhint %}

**2. Publish the package**

Select **Build** > **Pack** on your project to produce a `.nupkg` file, then push it from a terminal using the .NET CLI:

```bash
dotnet nuget push <PACKAGE_FILE> --api-key <TOKEN> --source harness
```

**3. Use the package**

In **NuGet Package Manager**, select the `harness` source, then browse and install the package in your project.
{% endtab %}

{% tab title="PowerShell" %}
**1. Configure authentication**

Register the Harness Registry as a PowerShell repository:

```powershell
Register-PSResourceRepository -Name harness -Uri https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/index.json -Credential (Get-Credential)
```

{% hint style="info" %}
**NuGet V2 upstream registries**

For NuGet V2 upstream registries, such as the PowerShell Gallery, use `https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/nuget/v2` instead of the V3 index URL.
{% endhint %}

**2. Publish the package**

Publish a module or script to the registry:

```powershell
Publish-PSResource -Path <PACKAGE_FILE> -Repository harness -ApiKey <TOKEN>
```

**3. Use the package**

Install a module from the registry:

```powershell
Install-PSResource -Name <ARTIFACT_NAME> -Version <VERSION> -Repository harness
```

{% endtab %}
{% endtabs %}

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new project with no `packages` folder and no cached NuGet entries for the Harness source, install or reference the package you published.
2. Confirm that the client downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step packs and pushes a NuGet package using the version from the release tag. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        nuget pack <NUSPEC_FILE> -Version "$PACKAGE_VERSION" -OutputDirectory ./out
        nuget push ./out/<PACKAGE_ID>."$PACKAGE_VERSION".nupkg -Source harness
```

## Troubleshooting

<details>

<summary>`nuget install` or `dotnet add package` fails with `401` or `403`</summary>

Check that the registry address in your client configuration matches the one shown in **Setup Client**, and that the identity token is the one you generated there. If the token has expired or was revoked, generate a new one and update your client configuration.

</details>

<details>

<summary>`nuget push` or `dotnet nuget push` returns `409 Conflict`</summary>

NuGet package versions are immutable after publish. Choose a new version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`nuget install` cannot find the package or resolves an outdated version</summary>

Check that the package ID and version match exactly what you published. Also, check that the registry name and account ID in your client configuration are correct.

</details>

<details>

<summary>Setup Client does not show publish instructions on an upstream proxy</summary>

An upstream proxy registry is pull-only, so **Setup Client** omits publish instructions for it. To publish a package, publish it to a separate private or public NuGet registry, or let the upstream proxy cache public packages automatically when a client requests them.

</details>

<details>

<summary>A client continues to resolve a cached older version after a new publish</summary>

NuGet caches resolved packages locally. Clear the cache with `nuget locals all -clear` or `dotnet nuget locals all --clear`, then reinstall the package.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
