---
url: /en/artifact/nuget.md
description: >
  Guide for configuring credentials and using the CNB NuGet artifact registry to
  push and pull .NET packages, covering local development with dotnet CLI or
  nuget.exe and CI pipeline workflows.
---
## Prerequisites

1. [Create Artifact Registry](./intro.md#creating-an-artifact-registry)
2. [Obtain Artifact Registry Address](./intro.md#obtaining-the-artifact-registry-address)
3. [Create Access Token](./intro.md#creating-an-access-token)

## Local Usage

### Client Instructions

| Client/Tool            | dotnet CLI                                   | nuget.exe                      |
| :--------------------- | :------------------------------------------- | :----------------------------- |
| Use Case               | .NET Core/.NET 5+ projects                   | Legacy .NET Framework projects |
| Cross-platform Support | Native support                               | Requires Mono                  |
| Installation           | Installed with .NET SDK, no additional setup | Requires downloading nuget.exe |

### Credential Management Commands

Use CNB's access token as login credentials. Configuration commands:

#### dotnet CLI

##### 1. Configure Username/Password Credentials

Replace `<YOUR_TOKEN>` with the access token, `<SOURCE_NAME>` with a custom source name, `<REPO_URL>` with the Artifact Registry address:

```bash
dotnet nuget add source <REPO_URL> --name <SOURCE_NAME> --username cnb --password <YOUR_TOKEN> --store-password-in-clear-text
# Example: Add credential cnb-nuget-repo
# dotnet nuget add source https://nuget.cnbprod.alpha.qq.com/cnb/nuget-repo/-/packages/v3/index.json --name cnb-nuget-repo --username cnb --password <YOUR_TOKEN> --store-password-in-clear-text
```

##### 2. List all credentials

```bash
dotnet nuget list source
```

##### 3. Remove Credential

Replace `<SOURCE_NAME>` with a custom source name:

```bash
dotnet nuget remove source <SOURCE_NAME>
# Example: Remove credential for cnb-nuget-repo source
# dotnet nuget remove source cnb-nuget-repo
```

##### 4. Credential Storage Location

| Client/Tool |                                                             |
| :---------- | :---------------------------------------------------------- |
| Windows     | %AppData%\NuGet\NuGet.Config                                |
| Linux/macOS | ~/.config/NuGet/NuGet.Config or ~/.nuget/NuGet/NuGet.Config |

#### nuget.exe

##### 1. Configure Username/Password Credentials

Replace `<YOUR_TOKEN>` with the access token, `<SOURCE_NAME>` with a custom source name, `<REPO_URL>` with the Artifact Registry address:

```bash
nuget sources add -source <REPO_URL> -name <SOURCE_NAME> -username cnb -password <YOUR_TOKEN> -StorePasswordInClearText
# Example: Add credential cnb-nuget-repo
# nuget sources add -source https://nuget.cnbprod.alpha.qq.com/cnb/nuget-repo/-/packages/v3/index.json -name cnb-nuget-repo -username cnb -password <YOUR_TOKEN> -StorePasswordInClearText
```

##### 2. Configure API Key Credentials

Replace `<YOUR_TOKEN>` with the access token, `<REPO_URL>` with the Artifact Registry address:

```bash
nuget setapikey <YOUR_TOKEN> -source <REPO_URL>
# Example: Add API key credential
# nuget setapikey <YOUR_TOKEN> -source https://nuget.cnbprod.alpha.qq.com/cnb/nuget-repo/-/packages/v3/index.json
```

##### 3. List All Credentials

```bash
nuget sources
```

##### 4. Remove Credential

Replace `<SOURCE_NAME>` with a custom source name:

```bash
nuget sources remove -name <SOURCE_NAME>
# Example: Remove credential for cnb-nuget-repo source
# nuget sources remove -name cnb-nuget-repo
```

##### 5. Credential Storage Location

| Client/Tool |                                                             |
| :---------- | :---------------------------------------------------------- |
| Windows     | %AppData%\NuGet\NuGet.Config                                |
| Linux/macOS | ~/.config/NuGet/NuGet.Config or ~/.nuget/NuGet/NuGet.Config |

### Artifact Management Commands

Configure credentials before executing artifact management commands.

#### dotnet CLI

##### 1. Pull Artifact

Replace `<PACKAGE_NAME>` with the package name, `<VERSION>` with the version number, `<SOURCE_NAME>` with a custom source name:

```bash
dotnet add package <PACKAGE_NAME> --version <VERSION> --source <SOURCE_NAME>
# Example: Pull version 1.0.0 of mynupkg package from the Artifact Registry named cnb-nuget-repo
# dotnet add package test --version 1.0.0 --source cnb-nuget-repo
```

##### 2. Build Artifact

Replace `<CSPROJ_PATH>` with the .csproj file path, `<PKG_PATH>` with the nupkg package output path, `<VERSION>` with the version number:

```bash
dotnet pack <CSPROJ_PATH> -p:PackageVersion=<VERSION>  --configuration Release --output <PKG_PATH>
# Example: Build artifact
# dotnet pack mynupkg.csproj --configuration Release --output nupkgs
# Or build a specific version artifact
# dotnet pack mynupkg.csproj -p:PackageVersion=1.0.0 --configuration Release --output nupkgs
```

##### 3. Push Artifact

Replace `<NUPKG_PATH>` with the nupkg package path, `<SOURCE_NAME>` with a custom source name, `<YOUR_TOKEN>` with the access token:

```bash
dotnet nuget push <NUPKG_PATH> --source <SOURCE_NAME> -k <YOUR_TOKEN>
# Example: Push version 1.0.0 of mynupkg package
# dotnet nuget push ./mynupkg.1.0.0.nupkg --source cnb-nuget-repo -k <YOUR_TOKEN>
```

##### 4. Delete Artifact

Replace `<PACKAGE_NAME>` with the package name, `<VERSION>` with the version number, `<SOURCE_NAME>` with a custom source name:

```bash
dotnet nuget delete <PACKAGE_NAME> <VERSION> --source <SOURCE_NAME>
# Example: Delete version 1.0.0 of mynupkg package from cnb-nuget-repo source
# dotnet nuget delete mynupkg 1.0.0 --source cnb-nuget-repo
```

##### 5. Query Package Information

Replace `<PACKAGE_NAME>` with the package name, `<SOURCE_NAME>` with a custom source name:

```bash
dotnet package search <PACKAGE_NAME> --source <SOURCE_NAME>
# Example: Query packages containing mynuget from the Artifact Registry named cnb-nuget-repo
# dotnet package search mynuget --source cnb-nuget-repo
```

##### 6. Clear local HTTP request cache

```bash
dotnet nuget locals http-cache --clear
```

##### 7. Clear all local cache

```bash
dotnet nuget locals all --clear
```

#### nuget.exe

##### 1. Pull Artifact

Replace `<PACKAGE_NAME>` with the package name, `<VERSION>` with the version number, `<SOURCE_NAME>` with a custom source name:

```bash
nuget install <PACKAGE_NAME> -version <VERSION> -source <SOURCE_NAME>
# Example: Pull version 1.0.0 of mynupkg package from the Artifact Registry named cnb-nuget-repo
# nuget install mynupkg -version 1.0.0 -source cnb-nuget-repo
```

##### 2. Build Artifact

Replace `<CSPROJ_PATH>` with the .csproj file path, `<PKG_PATH>` with the nupkg package output path:

```bash
nuget pack <CSPROJ_PATH> -Version <VERSION>  -Properties Configuration=Release
# Example: Build artifact
# nuget pack mynupkg.csproj -Properties Configuration=Release
# Or build a specific version artifact
# nuget pack mynupkg.csproj -Version 1.0.0 -Properties Configuration=Release
```

##### 3. Push Artifact

Replace `<NUPKG_PATH>` with the nupkg package path, `<SOURCE_NAME>` with a custom source name:

```bash
nuget push <NUPKG_PATH> -source <SOURCE_NAME>
# Example: Push version 1.0.0 of mynupkg package to the Artifact Registry named cnb-nuget-repo
# nuget push ./mynupkg.1.0.0.nupkg -source cnb-nuget-repo
```

##### 4. Delete Artifact

Replace `<PACKAGE_NAME>` with the package name, `<VERSION>` with the version number, `<SOURCE_NAME>` with a custom source name:

```bash
nuget delete <PACKAGE_NAME> <VERSION> -source <SOURCE_NAME>
# Example: Delete version 1.0.0 of mynupkg package from the Artifact Registry named cnb-nuget-repo
# nuget delete mynupkg 1.0.0 -source cnb-nuget-repo
```

##### 5. Query Package Information

Replace `<PACKAGE_NAME>` with the package name, `<SOURCE_NAME>` with a custom source name:

```bash
nuget search <PACKAGE_NAME> -source <SOURCE_NAME>
# Example: Query packages containing mynuget from the Artifact Registry named cnb-nuget-repo
# nuget search mynuget -source cnb-nuget-repo
```

##### 6. Clear local HTTP request cache

```bash
nuget locals http-cache -clear
```

##### 7. Clear all local cache

```bash
nuget locals all -clear
```

## Usage in Cloud Native Build and Workspaces

### CI Auto-Build Push

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: mcr.microsoft.com/dotnet/sdk:9.0
      stages:
        - name: add nuget source
          script: dotnet nuget add source https://nuget.cnbprod.alpha.qq.com/cnb/nuget-repo/-/packages/v3/index.json --name cnb-nuget-repo --username ${CNB_TOKEN_USER_NAME} --password ${CNB_TOKEN} --store-password-in-clear-text
        - name: pack
          script: dotnet pack mynupkg.csproj --configuration Release --output nupkgs
        - name: push
          script: dotnet nuget push nupkgs/*.nupkg --source cnb-nuget-repo -k ${CNB_TOKEN}
```

### Push in Workspaces

Add dotnet development environment config to `.cnb.yml`, then manually run commands after entering:

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: mcr.microsoft.com/dotnet/sdk:9.0
```

After entering the terminal:

```shell
dotnet nuget add source https://nuget.cnbprod.alpha.qq.com/cnb/nuget-repo/-/packages/v3/index.json --name cnb-nuget-repo --username cnb --password ${CNB_TOKEN} --store-password-in-clear-text
dotnet pack mynupkg.csproj --configuration Release --output nupkgs
dotnet nuget push "nupkgs/*.nupkg" --source cnb-nuget-repo -k ${CNB_TOKEN}
```

## FAQ

### Q1: Encountered 401 Forbidden error

**Possible cause:**
Insufficient permissions for the credential.

**Solution:**
Reconfigure the access token with the required permissions.
Token acquisition: Personal Settings -> Access Tokens -> [Add Access Token](https://cnbprod.alpha.qq.com/profile/token) -> Select the appropriate permissions for the Artifact Registry.

### Q2: Encountered 403 Forbidden error

**Possible cause:**
Incorrect credential configuration.

**Solution:**
Configure the correct access token for the Artifact Registry.
Token acquisition: Personal Settings -> Access Tokens -> [Add Access Token](https://cnbprod.alpha.qq.com/profile/token) -> Select the appropriate permissions for the Artifact Registry.

### Q3: Encountered 409 Forbidden error

**Possible cause:**
Package already exists and overwriting is not allowed.

**Solution:**
To overwrite the package, go to the corresponding Artifact Registry -> Artifact Registry Settings -> Policy Management -> Select "Allow Overwriting Existing Versions".

### Q4: How to support HTTP

**Possible cause:**
Client only supports HTTPS by default.

**Solution:**

| Client/Tool | HTTP support                                                                 |
| :---------- | :--------------------------------------------------------------------------- |
| dotnet CLI  | Specify `--allow-insecure-connections` when adding the repository credential |
| nuget.exe   | Specify `-AllowInsecureConnections` when adding the repository credential    |

## More Usage

For more NuGet usage, please refer to the [NuGet official documentation](https://learn.microsoft.com/en-us/nuget/).