# Using CodeArtifact with NuGet
These topics describe how to consume and publish `NuGet` packages using CodeArtifact.
**Note**
AWS CodeArtifact only supports [NuGet.exe version 4.8](https://docs.microsoft.com/en-us/nuget/release-notes/nuget-4.8-rtm) and higher.
**Topics**
+ [Use CodeArtifact with Visual Studio](nuget-visual-studio.md)
+ [Use CodeArtifact with nuget or dotnet](nuget-cli.md)
+ [NuGet package name, version, and asset name normalization](nuget-name-normalization.md)
+ [NuGet compatibility](nuget-compatibility.md)
# Use CodeArtifact with Visual Studio
You can consume packages from CodeArtifact directly in Visual Studio with the CodeArtifact Credential Provider. The credential provider simplifies the setup and authentication of your CodeArtifact repositories in Visual Studio and is available in the [AWS Toolkit for Visual Studio](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/welcome.html).
**Note**
The AWS Toolkit for Visual Studio is not available for Visual Studio for Mac.
To configure and use NuGet with CLI tools, see [Use CodeArtifact with the nuget or dotnet CLI](nuget-cli.md).
**Topics**
+ [Configure Visual Studio with the CodeArtifact Credential Provider](#nuget-vs-cred-provider)
+ [Use the Visual Studio Package Manager console](#built-in-nuget-terminal-vs)
## Configure Visual Studio with the CodeArtifact Credential Provider
The CodeArtifact Credential Provider simplifies the setup and continued authentication between CodeArtifact and Visual Studio. CodeArtifact authentication tokens are valid for a maximum of 12 hours. To avoid having to manually refresh the token while working in Visual Studio, the credential provider periodically fetches a new token before the current token expires.
**Important**
To use the credential provider, ensure that any existing AWS CodeArtifact credentials are cleared from your `nuget.config` file that may have been added manually or by running `aws codeartifact login` to configure NuGet previously.
**Use CodeArtifact in Visual Studio with the AWS Toolkit for Visual Studio**
1. Install the AWS Toolkit for Visual Studio using the following steps. The toolkit is compatible with Visual Studio 2017 and 2019 using these steps. AWS CodeArtifact does not support Visual Studio 2015 and earlier.
1. The Toolkit for Visual Studio for Visual Studio 2017 and Visual Studio 2019 is distributed in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.AWSToolkitforVisualStudio2017). You can also install and update the toolkit within Visual Studio by using **Tools** ≫ **Extensions and Updates** (Visual Studio 2017) or **Extensions** ≫ **Manage Extensions** (Visual Studio 2019).
1. After the toolkit has been installed, open it by choosing **AWS Explorer** from the **View** menu.
1. Configure the Toolkit for Visual Studio with your AWS credentials by following the steps in [Providing AWS Credentials](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/credentials.html) in the *AWS Toolkit for Visual Studio User Guide*.
1. (Optional) Set the AWS profile you want to use with CodeArtifact. If not set, CodeArtifact will use the default profile. To set the profile, go to **Tools > NuGet Package Manager > Select CodeArtifact AWS Profile**.
1. Add your CodeArtifact repository as a package source in Visual Studio.
1. Navigate to your repository in the **AWS Explorer** window, right click and select `Copy NuGet Source Endpoint`.
1. Use the **Tools > Options** command and scroll to **NuGet Package Manager**.
1. Select the **Package Sources** node.
1. Select **\$1**, edit the name, and paste the repository URL endpoint copied in Step 3a in the **Source** box, and select **Update**.
1. Select the checkbox for your newly added package source to enable it.
**Note**
We recommend adding an external connection to **NuGet.org** to your CodeArtifact repository and disabling the **nuget.org** package source in Visual Studio. When using an external connection, all of the packages fetched from **NuGet.org** will be stored in your CodeArtifact repository. If **NuGet.org** becomes unavailable, your application dependencies will still be available for CI builds and local development. For more information about external connections, see [Connect a CodeArtifact repository to a public repository](external-connection.md).
1. Restart Visual Studio for the changes to take effect.
After configuration, Visual Studio can consume packages from your CodeArtifact repository, any of its upstream repositories, or from [NuGet.org](https://www.nuget.org/) if you have added an external connection. For more information about browsing and installing NuGet packages in Visual Studio, see [Install and manage packages in Visual Studio using the NuGet Package Manager](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio) in the *NuGet documentation*.
## Use the Visual Studio Package Manager console
The Visual Studio Package Manager console will not use the Visual Studio version of the CodeArtifact Credential Provider. To use it, you will have to configure the command-line credential provider. See [Use CodeArtifact with the nuget or dotnet CLI](nuget-cli.md) for more information.
# Use CodeArtifact with the nuget or dotnet CLI
You can use CLI tools like `nuget` and `dotnet` to publish and consume packages from CodeArtifact. This document provides information about configuring the CLI tools and using them to publish or consume packages.
**Topics**
+ [Configure the nuget or dotnet CLI](#nuget-configure-cli)
+ [Consume NuGet packages from CodeArtifact](#nuget-consume-cli)
+ [Publish NuGet packages to CodeArtifact](#nuget-publish-cli)
+ [CodeArtifact NuGet Credential Provider reference](#nuget-cred-provider-reference)
+ [CodeArtifact NuGet Credential Provider versions](#nuget-cred-provider-history)
## Configure the nuget or dotnet CLI
You can configure the nuget or dotnet CLI with the CodeArtifact NuGet Credential Provider, with the AWS CLI, or manually. Configuring NuGet with the credential provider is highly recommended for simplified setup and continued authentication.
### Method 1: Configure with the CodeArtifact NuGet Credential Provider
The CodeArtifact NuGet Credential Provider simplifies the authentication and configuration of CodeArtifact with NuGet CLI tools. CodeArtifact authentication tokens are valid for a maximum of 12 hours. To avoid having to manually refresh the token while using the nuget or dotnet CLI, the credential provider periodically fetches a new token before the current token expires.
**Important**
To use the credential provider, ensure that any existing AWS CodeArtifact credentials are cleared from your `nuget.config` file that may have been added manually or by running `aws codeartifact login` to configure NuGet previously.
**Install and configure the CodeArtifact NuGet Credential Provider**
------
#### [ dotnet ]
1. Download the latest version of the [AWS.CodeArtifact.NuGet.CredentialProvider tool from NuGet.org](https://www.nuget.org/packages/AWS.CodeArtifact.NuGet.CredentialProvider) with the following `dotnet` command.
```
dotnet tool install -g AWS.CodeArtifact.NuGet.CredentialProvider
```
1. Use the `codeartifact-creds install` command to copy the credential provider to the NuGet plugins folder.
```
dotnet codeartifact-creds install
```
1. (Optional): Set the AWS profile you want to use with the credential provider. If not set, the credential provider will use the default profile. For more information on AWS CLI profiles, see [Named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
```
dotnet codeartifact-creds configure set profile profile_name
```
------
#### [ nuget ]
Perform the following steps to use the NuGet CLI to install the CodeArtifact NuGet Credential Provider from an Amazon S3 bucket and configure it. The credential provider will use the default AWS CLI profile, for more information on profiles, see [Named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
1. Download the latest version of the [CodeArtifact NuGet Credential Provider (codeartifact-nuget-credentialprovider.zip)](https://a.co/dbGqKq7) from an Amazon S3 bucket.
To view and download earlier versions, see [CodeArtifact NuGet Credential Provider versions](#nuget-cred-provider-history).
1. Unzip the file.
1. Copy the **AWS.CodeArtifact.NuGetCredentialProvider** folder from the **netfx** folder to `%user_profile%/.nuget/plugins/netfx/` on Windows or `~/.nuget/plugins/netfx` on Linux or MacOS.
1. Copy the **AWS.CodeArtifact.NuGetCredentialProvider** folder from the **netcore** folder to `%user_profile%/.nuget/plugins/netcore/` on Windows or `~/.nuget/plugins/netcore` on Linux or MacOS.
------
After you create a repository and configure the credential provider you can use the `nuget` or `dotnet` CLI tools to install and publish packages. For more information, see [Consume NuGet packages from CodeArtifact](#nuget-consume-cli) and [Publish NuGet packages to CodeArtifact](#nuget-publish-cli).
### Method 2: Configure nuget or dotnet with the login command
The `codeartifact login` command in the AWS CLI adds a repository endpoint and authorization token to your NuGet configuration file enabling nuget or dotnet to connect to your CodeArtifact repository. This will modify the user-level NuGet configuration which is located at `%appdata%\NuGet\NuGet.Config` for Windows and `~/.config/NuGet/NuGet.Config` or `~/.nuget/NuGet/NuGet.Config` for Mac/Linux. For more information about NuGet configurations, see [Common NuGet configurations](https://docs.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior).
**Configure nuget or dotnet with the `login` command**
1. Configure your AWS credentials for use with the AWS CLI, as described in [Getting started with CodeArtifact](getting-started.md).
1. Ensure that the NuGet CLI tool (`nuget` or `dotnet`) has been properly installed and configured. For instructions, see the [nuget](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference) or [dotnet](https://docs.microsoft.com/en-us/dotnet/core/install/) documentation.
1. Use the CodeArtifact `login` command to fetch credentials for use with NuGet.
**Note**
If you are accessing a repository in a domain that you own, you don't need to include `--domain-owner`. For more information, see [Cross-account domains](domain-overview.md#domain-overview-cross-account).
------
#### [ dotnet ]
**Important**
**Linux and MacOS users:** Because encryption is not supported on non-Windows platforms, your fetched credentials will be stored as plain text in your configuration file.
```
aws codeartifact login --tool dotnet --domain my_domain --domain-owner 111122223333 --repository my_repo
```
------
#### [ nuget ]
```
aws codeartifact login --tool nuget --domain my_domain --domain-owner 111122223333 --repository my_repo
```
------
The login command will:
+ Fetch an authorization token from CodeArtifact using your AWS credentials.
+ Update your user-level NuGet configuration with a new entry for your NuGet package source. The source that points to your CodeArtifact repository endpoint will be called `domain_name/repo_name`.
The default authorization period after calling `login` is 12 hours, and `login` must be called to periodically refresh the token. For more information about the authorization token created with the `login` command, see [Tokens created with the `login` command](tokens-authentication.md#auth-token-login).
After you create a repository and configure authentication you can use the `nuget`, `dotnet`, or `msbuild` CLI clients to install and publish packages. For more information, see [Consume NuGet packages from CodeArtifact](#nuget-consume-cli) and [Publish NuGet packages to CodeArtifact](#nuget-publish-cli).
### Method 3: Configure nuget or dotnet without the login command
For manual configuration, you must add a repository endpoint and authorization token to your NuGet configuration file to enable nuget or dotnet to connect to your CodeArtifact repository.
**Manually configure nuget or dotnet to connect to your CodeArtifact repository.**
1. Determine your CodeArtifact repository endpoint by using the `get-repository-endpoint` AWS CLI command.
```
aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format nuget
```
Example output:
```
{
"repositoryEndpoint": "https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/nuget/my_repo/"
}
```
1. Get an authorization token to connect to your repository from your package manager by using the `get-authorization-token` AWS CLI command.
```
aws codeartifact get-authorization-token --domain my_domain
```
Example output:
```
{
"authorizationToken": "eyJ2I...viOw",
"expiration": 1601616533.0
}
```
1. Create the full repository endpoint URL by appending `/v3/index.json` to the URL returned by `get-repository-endpoint` in step 3.
1. Configure nuget or dotnet to use the repository endpoint from Step 1 and authorization token from Step 2.
**Note**
The source URL must end in `/v3/index.json` for nuget or dotnet to successfully connect to a CodeArtifact repository.
------
#### [ dotnet ]
**Linux and MacOS users:** Because encryption is not supported on non-Windows platforms, you must add the `--store-password-in-clear-text` flag to the following command. Note that this will store your password as plain text in your configuration file.
```
dotnet nuget add source https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/nuget/my_repo/v3/index.json --name packageSourceName --password eyJ2I...viOw --username aws
```
**Note**
To update an existing source, use the `dotnet nuget update source` command.
------
#### [ nuget ]
```
nuget sources add -name domain_name/repo_name -Source https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/nuget/my_repo/v3/index.json -password eyJ2I...viOw -username aws
```
------
Example output:
```
Package source with Name: domain_name/repo_name added successfully.
```
**Note**
To use a dualstack endpoint, use the `codeartifact.region.on.aws` endpoint.
## Consume NuGet packages from CodeArtifact
Once you have [configured NuGet with CodeArtifact](https://docs.aws.amazon.com//codeartifact/latest/ug/nuget-cli.html), you can consume NuGet packages that are stored in your CodeArtifact repository or one of its upstream repositories.
To consume a package version from a CodeArtifact repository or one of its upstream repositories with `nuget` or `dotnet`, run the following command replacing *packageName* with the name of the package you want to consume and *packageSourceName* with the source name for your CodeArtifact repository in your NuGet configuration file. If you used the `login` command to configure your NuGet configuration, the source name is *domain\$1name/repo\$1name*.
**Note**
When a package is requested, the NuGet client caches which versions of that package exists. Because of this behavior, an install may fail for a package that was previously requested before the desired version became available. To avoid this failure and successfully install a package that exists, you can either clear the NuGet cache ahead of an install with `nuget locals all --clear` or `dotnet nuget locals all --clear`, or avoid using the cache during `install` and `restore` commands by providing the `-NoCache` option for `nuget` or the `--no-cache` option for `dotnet`.
------
#### [ dotnet ]
```
dotnet add package packageName --source packageSourceName
```
------
#### [ nuget ]
```
nuget install packageName -Source packageSourceName
```
------
**To install a specific version of a package**
------
#### [ dotnet ]
```
dotnet add package packageName --version 1.0.0 --source packageSourceName
```
------
#### [ nuget ]
```
nuget install packageName -Version 1.0.0 -Source packageSourceName
```
------
See [Manage packages using the nuget.exe CLI](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-nuget-cli) or [Install and manage packages using the dotnet CLI](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli) in the *Microsoft Documentation* for more information.
### Consume NuGet packages from NuGet.org
You can consume NuGet packages from [NuGet.org](https://www.nuget.org/) through a CodeArtifact repository by configuring the repository with an external connection to **NuGet.org**. Packages consumed from **NuGet.org** are ingested and stored in your CodeArtifact repository. For more information about adding external connections, see [Connect a CodeArtifact repository to a public repository](external-connection.md).
## Publish NuGet packages to CodeArtifact
Once you have [configured NuGet with CodeArtifact](https://docs.aws.amazon.com//codeartifact/latest/ug/nuget-cli.html), you can use `nuget` or `dotnet` to publish package versions to CodeArtifact repositories.
To push a package version to a CodeArtifact repository, run the following command with the full path to your `.nupkg` file and the source name for your CodeArtifact repository in your NuGet configuration file. If you used the `login` command to configure your NuGet configuration, the source name is `domain_name/repo_name`.
**Note**
You can create a NuGet package if you do not have one to publish. For more information, see [Package creation workflow](https://docs.microsoft.com/en-us/nuget/create-packages/overview-and-workflow) in the *Microsoft documentation*.
------
#### [ dotnet ]
```
dotnet nuget push path/to/nupkg/SamplePackage.1.0.0.nupkg --source packageSourceName
```
------
#### [ nuget ]
```
nuget push path/to/nupkg/SamplePackage.1.0.0.nupkg -Source packageSourceName
```
------
## CodeArtifact NuGet Credential Provider reference
The CodeArtifact NuGet Credential Provider makes it easy to configure and authenticate NuGet with your CodeArtifact repositories.
### CodeArtifact NuGet Credential Provider commands
This section includes the list of commands for the CodeArtifact NuGet Credential Provider. These commands must be prefixed with `dotnet codeartifact-creds` like the following example.
```
dotnet codeartifact-creds command
```
+ `configure set profile profile`: Configures the credential provider to use the provided AWS profile.
+ `configure unset profile`: Removes the configured profile if set.
+ `install`: Copies the credential provider to the `plugins` folder.
+ `install --profile profile`: Copies the credential provider to the `plugins` folder and configures it to use the provided AWS profile.
+ `uninstall`: Uninstalls the credential provider. This does not remove the changes to the configuration file.
+ `uninstall --delete-configuration`: Uninstalls the credential provider and removes all changes to the configuration file.
### CodeArtifact NuGet Credential Provider logs
To enable logging for the CodeArtifact NuGet Credential Provider, you must set the log file in your environment. The credential provider logs contain helpful debugging information such as:
+ The AWS profile used to make connections
+ Any authentication errors
+ If the endpoint provided is not a CodeArtifact URL
**Set the CodeArtifact NuGet Credential Provider log file**
```
export AWS_CODEARTIFACT_NUGET_LOGFILE=/path/to/file
```
After the log file is set, any `codeartifact-creds` command will append its log output to the contents of that file.
## CodeArtifact NuGet Credential Provider versions
The following table contains version history information and download links for the CodeArtifact NuGet Credential Provider.
| Version | Changes | Date published | Download link (S3) |
| --- | --- | --- | --- |
| 1.0.2 (latest) | Upgraded dependencies | 06/26/2024 | [Download v1.0.2](https://d12ov9682v6hj.cloudfront.net/codeartifact-nuget-credentialprovider-v1.0.2.zip) |
| 1.0.1 | Added support for net5, net6, and SSO profiles | 03/05/2022 | [Download v1.0.1](https://a.co/cAIkhV1) |
| 1.0.0 | Initial CodeArtifact NuGet Credential Provider release | 11/20/2020 | [Download v1.0.0](https://a.co/8b2cENb) |
# NuGet package name, version, and asset name normalization
CodeArtifact normalizes package and asset names and package versions before storing them, which means the names or versions in CodeArtifact may be different than the ones provided when the package or asset was published.
**Package name normalization: ** CodeArtifact normalizes NuGet package names by converting all letters to lowercase.
**Package version normalization: ** CodeArtifact normalizes NuGet package versions using the same pattern as NuGet. The following information is from [Normalized version numbers](https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#normalized-version-numbers) from the NuGet documentation.
+ Leading zeroes are removed from version numbers:
+ `1.00` is treated as `1.0`
+ `1.01.1` is treated as `1.1.1`
+ `1.00.0.1` is treated as `1.0.0.1`
+ A zero in the fourth part of the version number will be omitted:
+ `1.0.0.0` is treated as `1.0.0`
+ `1.0.01.0` is treated as `1.0.1`
+ SemVer 2.0.0 build metadata is removed:
+ `1.0.7+r3456` is treated as `1.0.7`
**Package asset name normalization: ** CodeArtifact constructs the NuGet package asset name from the normalized package name and package version.
The non-normalized package name and version name can be used with API and CLI requests because CodeArtifact performs normalization on the package name and version inputs for those requests. For example, inputs of `--package Newtonsoft.JSON` and `--version 12.0.03.0` would be normalized and return a package that has a normalized package name of `newtonsoft.json` and version of `12.0.3`.
You must use the normalized package asset name in API and CLI requests as CodeArtifact does not perform normalization on the `--asset` input.
You must use normalized names and versions in ARNs.
To find the normalized name of a package, use the `aws codeartifact list-packages` command. For more information, see [List package names](list-packages.md).
To find the non-normalized name of a package, use the `aws codeartifact describe-package-version` command. The non-normalized name of the package is returned in the `displayName` field. For more information, see [View and update package version details and dependencies](describe-package-version.md).
# NuGet compatibility
This guide contains information about CodeArtifact's compatibility with different NuGet tools and versions.
**Topics**
+ [General NuGet compatibility](#nuget-version-support)
+ [NuGet command line support](#nuget-command-line-support)
## General NuGet compatibility
AWS CodeArtifact supports NuGet 4.8 and higher.
AWS CodeArtifact only supports V3 of the NuGet HTTP protocol. This means that some CLI commands that rely V2 of the protocol are not supported. See the [nuget.exe command support](#nuget-command-support) section for more information.
AWS CodeArtifact does not support PowerShellGet 2.x.
## NuGet command line support
AWS CodeArtifact supports the NuGet (`nuget.exe`) and .NET Core (`dotnet`) CLI tools.
### nuget.exe command support
Because CodeArtifact only supports V3 of NuGet's HTTP protocol, the following commands will not work when used against CodeArtifact resources:
+ `list`: The `nuget list` command displays a list of packages from a given source. To get a list of packages in a CodeArtifact repository, you can use the [List package names](list-packages.md) command from the AWS CLI.