Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).
# Using NuGet
These topics describe how to consume and publish `NuGet` packages using CodeCatalyst.
**Note**
CodeCatalyst supports [NuGet version 4.8](https://docs.microsoft.com/en-us/nuget/release-notes/nuget-4.8-rtm) and higher.
**Topics**
+ [Using CodeCatalyst with Visual Studio](packages-nuget-visual-studio.md)
+ [Configuring and using the nuget or dotnet CLI](packages-nuget-cli.md)
+ [NuGet package name, version, and asset name normalization](nuget-name-normalization.md)
+ [NuGet compatibility](packages-nuget-compatibility.md)
# Using CodeCatalyst with Visual Studio
You can consume packages from CodeCatalyst directly in Visual Studio.
To configure and use NuGet with CLI tools such as `dotnet` or `nuget`, see [Configuring and using the nuget or dotnet CLI](packages-nuget-cli.md).
**Contents**
+ [Configuring Visual Studio with CodeCatalyst](#packages-nuget-vs-configure)
+ [Windows](#packages-nuget-vs-configure-windows)
+ [macOS](#packages-nuget-vs-configure-mac)
## Configuring Visual Studio with CodeCatalyst
### Windows
**To configure Visual Studio with CodeCatalyst**
1. A personal access token (PAT) is required to authenticate with CodeCatalyst. If you already have one, you can use that. If not, follow the instructions in [Grant users repository access with personal access tokens](ipa-tokens-keys.md) to create one.
1. Use `nuget` or `dotnet` to configure your package repository and credentials.
------
#### [ 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 plaintext in your configuration file.
```
dotnet nuget add source https://packages.region.codecatalyst.aws/nuget/space-name/proj-name/repo-name/v3/index.json --name repo_name --password PAT --username user_name
```
------
#### [ nuget ]
```
nuget sources add -name repo_name -Source https://packages.region.codecatalyst.aws/nuget/space-name/proj-name/repo-name/v3/index.json -password PAT --username user_name
```
------
Example output:
```
Package source with Name: repo_name added successfully.
```
1. Configure Visual Studio to use your new package source. In Visual Studio, choose **Tools**, and then choose **Options**.
1. In the **Options** menu, expand the **NuGet Package Manager** section and choose **Package Sources**.
1. In the **Available package sources** list, make sure that your *repo\$1name* source is enabled. If you have configured your package repository with an upstream connection to the NuGet Gallery, disable the **nuget.org** source .
### macOS
**To configure Visual Studio with CodeCatalyst**
1. A personal access token (PAT) is required to authenticate with CodeCatalyst. If you already have one, you can use that. If not, follow the instructions in [Grant users repository access with personal access tokens](ipa-tokens-keys.md) to create one.
1. Choose **Preferences** from the menu bar.
1. In the **NuGet** section, choose **Sources**.
1. Choose **Add** and add your repository information.
1. For **Name**, enter your CodeCatalyst package repository name.
1. For **Location**, enter your CodeCatalyst package repository endpoint. The following snippet shows an example endpoint. Replace *space-name*, *proj-name*, and *repo-name* with your CodeCatalyst space name, project name, and repository name.
```
https://packages.region.codecatalyst.aws/nuget/space-name/proj-name/repo-name/
```
1. For **Username**, enter any valid value.
1. For **Password**, enter your PAT.
1. Choose **Add source**.
1. If you have configured your package repository with an upstream connection to the NuGet Gallery, disable the **nuget.org** source.
After configuration, Visual Studio can consume packages from your CodeCatalyst repository, any of its upstream repositories, or from [NuGet.org](https://www.nuget.org/) if you have it configured as an upstream source. 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*.
# Configuring and using the nuget or dotnet CLI
You can use CLI tools such as `NuGet` and `dotnet` to publish and consume packages from CodeCatalyst. This document provides information about configuring the CLI tools and using them to publish or consume packages.
**Contents**
+ [Configuring NuGet with CodeCatalyst](#nuget-configure-cli)
+ [Consuming NuGet packages from a CodeCatalyst repository](#nuget-consume-cli)
+ [Consuming NuGet packages from NuGet.org through CodeCatalyst](#nuget-consume-nuget-gallery)
+ [Publishing NuGet packages to CodeCatalyst](#nuget-publish-cli)
## Configuring NuGet with CodeCatalyst
To configure NuGet with CodeCatalyst, add a repository endpoint and personal access token to your NuGet configuration file to allow `nuget` or `dotnet` to connect to your CodeCatalyst package repository.
**To configure NuGet with your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. On the overview page for your project, choose **Packages**.
1. Choose your package repository from the list of package repositories.
1. Choose **Connect to repository**.
1. In the **Connect to repository** dialog box, choose **NuGet** or **dotnet** from the list of package manager clients.
1. You will need a personal access token (PAT) to authenticate NuGet with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.
1. Choose **Create token**.
1. Choose **Copy** to copy your PAT.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box.
1. Configure `nuget` or `dotnet` to use your repository's NuGet endpoint and CodeCatalyst PAT. Replace the following values.
**Note**
If copying from the console instructions, the following values should be updated for you and should not be changed.
+ Replace *username* with your CodeCatalyst user name.
+ Replace *PAT* with your CodeCatalyst PAT.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
1. For `nuget`, use the `nuget sources add` command.
```
nuget sources add -name "repo_name" -Source "https://packages.region.codecatalyst.aws/nuget/space_name/proj_name/repo_name/v3/index.json" -username "username" -password "PAT"
```
1. For `dotnet`, use the `dotnet nuget add source` command.
**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 plaintext in your configuration file.
```
dotnet nuget add source "https://packages.region.codecatalyst.aws/nuget/space_name/proj_name/repo_name/v3/index.json" -n "proj_name/repo_name" -u "username" -p "PAT" --store-password-in-clear-text
```
Once you have configured NuGet with CodeCatalyst, you can [consume NuGet packages](#nuget-consume-cli) that are stored in your CodeCatalyst repository or one of its upstream repositories and [publish NuGet packages](#nuget-publish-cli) to your CodeCatalyst repository.
## Consuming NuGet packages from a CodeCatalyst repository
Once you have [configured NuGet with CodeCatalyst](#nuget-configure-cli), you can consume NuGet packages that are stored in your CodeCatalyst repository or one of its upstream repositories.
To consume a package version from a CodeCatalyst repository or one of its upstream repositories with nuget or dotnet, run the following command. Replace *packageName* with the name of the package you want to consume and *packageSourceName* with the source name for your CodeCatalyst package repository in your NuGet configuration file, which should be the repository name.
**To install a package with `dotnet`**
```
dotnet add packageName --source packageSourceName
```
**To install a package with `nuget`**
```
nuget install packageName --source packageSourceName
```
For more information, see [Manage packages using the nuget 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*.
## Consuming NuGet packages from NuGet.org through CodeCatalyst
You can consume NuGet packages from [NuGet.org](https://www.nuget.org/) through a CodeCatalyst repository by configuring the repository with an upstream connection to **NuGet.org**. Packages consumed from **NuGet.org** are ingested and stored in your CodeCatalyst repository.
**To consume packages from NuGet.org**
1. If you haven't already, configure your NuGet package manager with your CodeCatalyst package repository by following the steps in [Configuring NuGet with CodeCatalyst](#nuget-configure-cli).
1. Ensure that your repository has added **NuGet.org** as an upstream connection. You can check which upstream sources are added or add **Nuget.org** as an upstream source by following the instructions in [Adding an upstream repository](packages-upstream-repositories-add.md) and choosing the **NuGet store** repository.
## Publishing NuGet packages to CodeCatalyst
Once you have [configured NuGet with CodeCatalyst](#nuget-configure-cli), you can use `nuget` or `dotnet` to publish package versions to CodeCatalyst repositories.
To push a package version to a CodeCatalyst repository, run the following command with the full path to your `.nupkg` file and the source name for your CodeCatalyst repository in your NuGet configuration file.
**To publish a package with `dotnet`**
```
dotnet nuget push path/to/nupkg/SamplePackage.1.0.0.nupkg --source packageSourceName
```
**To publish a package with `nuget`**
```
nuget push path/to/nupkg/SamplePackage.1.0.0.nupkg --source packageSourceName
```
# NuGet package name, version, and asset name normalization
CodeCatalyst normalizes package and asset names and package versions before storing them, which means the names or versions in CodeCatalyst may be different than the ones provided when the package or asset was published.
**Package name normalization: ** CodeCatalyst normalizes NuGet package names by converting all letters to lowercase.
**Package version normalization: ** CodeCatalyst 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: ** CodeCatalyst constructs the NuGet package asset name from the normalized package name and package version.
# NuGet compatibility
This guide contains information about CodeCatalyst'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
CodeCatalyst supports NuGet 4.8 and higher.
CodeCatalyst 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 following [nuget command support](#nuget-command-support) section for more information.
CodeCatalyst does not support PowerShellGet 2.x.
## NuGet command line support
CodeCatalyst supports the NuGet (`nuget`) and .NET Core (`dotnet`) CLI tools.
### nuget command support
Because CodeCatalyst only supports V3 of NuGet's HTTP protocol, the following commands will not work when used against CodeCatalyst resources:
+ `list`: The `nuget list` command displays a list of packages from a given source. To get a list of packages in a CodeCatalyst package repository, navigate to the repository in the CodeCatalyst console.