• CodeArtifact Credential Provider reference (p. 121)
Configure the nuget or dotnet CLI
You can configure the nuget or dotnet CLI with a CodeArtifact 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 Credential Provider
The CodeArtifact 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 Credential Provider for NuGet dotnet
1. Download the AWS.CodeArtifact.NuGet.CredentialProvider tool from NuGet.org with the following dotnet command.
dotnet tool install -g AWS.CodeArtifact.NuGet.CredentialProvider
2. Use the codeartifact-creds install command to copy the credential provider to the NuGet plugins folder.
dotnet codeartifact-creds install
3. (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.
dotnet codeartifact-creds configure set profile profile_name
nuget
Perform the following steps to use the NuGet CLI to install the CodeArtifact 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.
1. Download AWS.CodeArtifact.NuGet.CredentialProvider.zip from an Amazon S3 bucket.
2. Unzip the file.
3. 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.
4. 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.
Configure the nuget or dotnet CLI
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 (p. 120) and Publish NuGet packages to CodeArtifact (p. 120).
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.
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 (p. 7).
2. Ensure that the NuGet CLI tool (nuget or dotnet) has been properly installed and configured. For instructions, see the nuget or dotnet documentation.
3. Use the CodeArtifact login command to fetch credentials for use with NuGet.
NoteIf 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 (p. 73).
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 (p. 159).
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 (p. 120) and Publish NuGet packages to CodeArtifact (p. 120).
Configure the nuget or dotnet 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/"
}
2. 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
}
3. Configure nuget or dotnet to use the repository endpoint from Step 1 and authorization token from Step 2. Note, you will need to append /v3/index.json to your repository endpoint.
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
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:
Consume NuGet packages
Package source with Name: domain_name/repo_name added successfully.
Consume NuGet packages from CodeArtifact
Once you have configured NuGet with CodeArtifact, 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_name/repo_name.
NoteWhen 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 requested before it was 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 use the --no-cache option when running nuget install or nuget restore.
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 or Install and manage packages using the dotnet CLI in the Microsoft Documentation for more information.
Consume NuGet packages from NuGet.org
You can consume NuGet packages from 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 Add an external connection (p. 26).
Publish NuGet packages to CodeArtifact
Once you have configured NuGet with CodeArtifact, you can use nuget or dotnet to publish package versions to CodeArtifact repositories.