---
url: /en/artifact/nuget.md
---
## 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

You can use CNB's access token as login credentials. Configuration commands:

::: tabs
@tab dotnet CLI

#### 1. Configure Username/Password Credentials

Replace `<YOUR_TOKEN>` with the access token, `<TOKEN_NAME>` with the credential name, `<GROUP_NAME>` with the organization name, `<REPO_NAME>` with the Artifact Registry name

```yaml
dotnet nuget add source https://nuget.cnb.build/<GROUP_NAME>/<REPO_NAME>/-/packages/v3/index.json --name <TOKEN_NAME> --username cnb --password <YOUR_TOKEN> --store-password-in-clear-text
# Example: Add credential cnb-nuget-repo
# dotnet nuget add source https://nuget.cnb.build/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

```yaml
dotnet nuget list source
```

#### 3. Remove Credential

Replace `<TOKEN_NAME>` with the credential name

```yaml
dotnet nuget remove source <TOKEN_NAME>
# Example: Remove credential cnb-nuget-repo
# 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 |

@tab nuget.exe

#### 1. Configure Username/Password Credentials

Replace `<YOUR_TOKEN>` with the access token, `<TOKEN_NAME>` with the credential name, `<GROUP_NAME>` with the organization name, `<REPO_NAME>` with the Artifact Registry name

```yaml
nuget sources add -source https://nuget.cnb.build/<GROUP_NAME>/<REPO_NAME>/-/packages/v3/index.json -name <TOKEN_NAME> -username cnb -password <YOUR_TOKEN> -StorePasswordInClearText
# Example: Add credential cnb-nuget-repo
# nuget sources add -source https://nuget.cnb.build/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, `<GROUP_NAME>` with the organization name, `<REPO_NAME>` with the Artifact Registry name

```yaml
nuget setapikey <YOUR_TOKEN> -source https://nuget.cnb.build/<GROUP_NAME>/<REPO_NAME>/-/packages/v3/index.json
# Example: Add API key credential
# nuget setapikey <YOUR_TOKEN> -source https://nuget.cnb.build/cnb/nuget-repo/-/packages/v3/index.json
```

#### 3. List All Credentials

```yaml
nuget sources
```

#### 4. Remove Credential

Replace `<TOKEN_NAME>` with the credential name

```yaml
nuget sources remove -name <TOKEN_NAME>
# Example: Remove credential cnb-nuget-repo
# 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

Ensure credentials are configured before executing artifact management commands.
::: tabs
@tab dotnet CLI

#### 1. Pull Artifact

Replace `<PACKAGE_NAME>` with the package name, `<VERSION>` with the version number, `<TOKEN_NAME>` with the credential name

```yaml
dotnet add package <PACKAGE_NAME> --version <VERSION> --source <TOKEN_NAME>
# Example: Pull version 1.0.0 of mynupkg package from the Artifact Registry named cnb-nuget-repo
# dotnet pack mynupkg.csproj --configuration Release --output nupkgs
```

#### 2. Build Artifact

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

```yaml
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, `<TOKEN_NAME>` with the credential name

```yaml
dotnet nuget push <NUPKG_PATH> --source <TOKEN_NAME>
# Example: Push version 1.0.0 of mynupkg package to the Artifact Registry named cnb-nuget-repo
# dotnet 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, `<TOKEN_NAME>` with the credential name

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

#### 5. Query Package Information

Replace `<PACKAGE_NAME>` with the package name, `<TOKEN_NAME>` with the credential name

```yaml
dotnet package search <PACKAGE_NAME> --source <TOKEN_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

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

#### 7. Clear all local cache

```yaml
dotnet nuget locals all --clear
```

@tab nuget.exe

#### 1. Pull Artifact

Replace `<PACKAGE_NAME>` with the package name, `<VERSION>` with the version number, `<TOKEN_NAME>` with the credential name

```yaml
nuget install <PACKAGE_NAME> -version <VERSION> -source <TOKEN_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

```yaml
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, `<TOKEN_NAME>` with the credential name

```yaml
nuget push <NUPKG_PATH> -source <TOKEN_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, `<TOKEN_NAME>` with the credential name

```yaml
nuget delete <PACKAGE_NAME> <VERSION> -source <TOKEN_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, `<TOKEN_NAME>` with the credential name

```yaml
nuget search <PACKAGE_NAME> -source <TOKEN_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

```yaml
nuget locals http-cache -clear
```

#### 7. Clear all local cache

```yaml
nuget locals all -clear
```

:::

## Usage in Cloud Native Build

Build nupkg packages in the pipeline and push them to the Artifact Registry named by the credential.

Replace `<REPO_URL>` with the Artifact Registry address, `<TOKEN_NAME>` with the credential name, `<CSPROJ_PATH>` with the .csproj file path, `<PKG_PATH>` with the nupkg package output path, `<NUPKG_NAME>` with the nupkg package name

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: mcr.microsoft.com/dotnet/sdk:9.0
      stages:
        - name: Configure nuget repository address, username, and password
          script: dotnet nuget add source <REPO_URL> --name <TOKEN_NAME> --username ${CNB_TOKEN_USER_NAME} --password ${CNB_TOKEN} --store-password-in-clear-text
        - name: Package nuget artifact 
          script: dotnet pack <CSPROJ_PATH> --configuration Release --output <PKG_PATH>  
        - name: Push nuget artifact to CNB
          script: dotnet nuget push <PKG_PATH>/<NUPKG_NAME> --source <TOKEN_NAME>
```

* Example:

```yaml title=".cnb.yml"
main: 
  push: 
    - docker: 
        image: mcr.microsoft.com/dotnet/sdk:9.0 
      stages: 
        - name: Configure nuget repository address, username, and password 
          script: dotnet nuget add source https://nuget.cnb.build/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: Build nuget artifact
          script: dotnet pack mynupkg.csproj --configuration Release --output nupkgs 
        - name: Push nuget artifact to CNB 
          script: dotnet nuget push nupkgs/*.nupkg --source cnb-nuget-repo 
```

## Usage in Workspaces

#### 1. Configure dotnet development environment in .cnb.yml

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

#### 2. Configure nuget repository address, username, and password

Replace `<REPO_URL>` with the Artifact Registry address, `<TOKEN_NAME>` with the credential name, `<YOUR_TOKEN>` with the credential

```yaml
dotnet nuget add source <REPO_URL> --name <TOKEN_NAME> --username cnb --password <YOUR_TOKEN> --store-password-in-clear-text
dotnet pack xxx.csproj --configuration Release --output nupkgs
dotnet nuget push "nupkgs/*.nupkg" --source <TOKEN_NAME>
```

* Example: Add credential cnb-nuget-repo, build nuget artifact, and push it to CNB

```shell
dotnet nuget add source https://nuget.cnb.build/cnb/nuget-repo/-/packages/v3/index.json --name cnb-nuget-repo --username cnb --password <YOUR_TOKEN> --store-password-in-clear-text
dotnet pack mynupkg.csproj --configuration Release --output nupkgs
dotnet nuget push "nupkgs/*.nupkg" --source cnb-nuget-repo
```

## 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://cnb.build/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://cnb.build/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, refer to the official documentation.