Merge branch '10io-improve-nuget-documentation' into 'master'

Improve the nuget repository documentation

See merge request gitlab-org/gitlab!24972

doc/user/packages/index.md

@@ -13,7 +13,7 @@ The Packages feature allows GitLab to act as a repository for the following:
 | [Conan Repository](conan_repository/index.md) **(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.6+ |
 | [Maven Repository](maven_repository/index.md) **(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ |
 | [NPM Registry](npm_registry/index.md) **(PREMIUM)**  | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ |
-| [NuGet Repository](nuget_repository/index.md) **(PREMIUM)**  | *PLANNED* The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ |
+| [NuGet Repository](nuget_repository/index.md) **(PREMIUM)**  | The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ |
 
 ## Suggested contributions
 

doc/user/packages/nuget_repository/index.md

@@ -2,18 +2,21 @@
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8.
 
-CAUTION: **Work in progress**
-This feature is in development, sections on uploading and installing packages will be coming soon, please follow along and help us make sure we're building the right solution for you in the [NuGet issue](https://gitlab.com/gitlab-org/gitlab/issues/20050).
-
 With the GitLab NuGet Repository, every project can have its own space to store NuGet packages.
 
-The GitLab NuGet Repository works with either [nuget CLI](https://www.nuget.org/) or [Visual Studio](https://visualstudio.microsoft.com/vs/).
+The GitLab NuGet Repository works with:
+
+- [NuGet CLI](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference)
+- [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/)
+- [Visual Studio](https://visualstudio.microsoft.com/vs/)
 
 ## Setting up your development environment
 
-You will need [nuget CLI](https://www.nuget.org/) 5.2 or above. Previous versions have not been tested against the GitLab NuGet Repository and might not work. You can install it by visiting the [downloads page](https://www.nuget.org/downloads).
+You will need [NuGet CLI 5.2 or later](https://www.nuget.org/downloads). Earlier versions have not been tested
+against the GitLab NuGet Repository and might not work. If you have [Visual Studio](https://visualstudio.microsoft.com/vs/),
+NuGet CLI is probably already installed.
 
-If you have [Visual Studio](https://visualstudio.microsoft.com/vs/), [nuget CLI](https://www.nuget.org/) is probably already installed.
+Alternatively, you can use [.NET SDK 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0), which installs NuGet CLI.
 
 You can confirm that [nuget CLI](https://www.nuget.org/) is properly installed with:
 
@@ -37,7 +40,7 @@ Available commands:
 
 NOTE: **Note:**
 This option is available only if your GitLab administrator has
-[enabled support for the NuGet Repository](../../../administration/packages/index.md).**(PREMIUM ONLY)**
+[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)**
 
 After the NuGet Repository is enabled, it will be available for all new projects
 by default. To enable it for existing projects, or if you want to disable it:
@@ -48,7 +51,7 @@ by default. To enable it for existing projects, or if you want to disable it:
 
 You should then be able to see the **Packages** section on the left sidebar.
 
-## Adding the GitLab NuGet Repository as a source to nuget
+## Adding the GitLab NuGet Repository as a source to NuGet
 
 You will need the following:
 
@@ -57,23 +60,23 @@ You will need the following:
 - A suitable name for your source.
 - Your project ID which can be found on the home page of your project.
 
-You can now add a new source to nuget either using [nuget CLI](https://www.nuget.org/) or [Visual Studio](https://visualstudio.microsoft.com/vs/).
+You can now add a new source to NuGet with:
+
+- [NuGet CLI](#add-nuget-repository-source-with-nuget-cli)
+- [Visual Studio](#add-nuget-repository-source-with-visual-studio).
+- [.NET CLI](#add-nuget-repository-source-with-net-cli)
 
-### Using nuget CLI
+### Add NuGet Repository source with NuGet CLI
 
 To add the GitLab NuGet Repository as a source with `nuget`:
 
 ```shell
-nuget source Add -Name <source_name> -Source "https://example.gitlab.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username> -Password <gitlab_token>
+nuget source Add -Name <source_name> -Source "https://gitlab-instance.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username> -Password <gitlab_personal_access_token>
 ```
 
-Replace:
+Where:
 
-- `<source_name>` with your desired source name.
-- `<your_project_id>` with your project ID.
-- `<gitlab-username>` with your GitLab username.
-- `<gitlab-token>` with your personal access token.
-- `example.gitlab.com` with the URL of the GitLab instance you're using.
+- `<source_name>` is your desired source name.
 
 For example:
 
@@ -81,7 +84,7 @@ For example:
 nuget source Add -Name "GitLab" -Source "https//gitlab.example/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf
 ```
 
-### Using Visual Studio
+### Add NuGet Repository source with Visual Studio
 
 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/).
 1. Open the **FILE > OPTIONS** (Windows) or **Visual Studio > Preferences** (Mac OS).
@@ -102,3 +105,109 @@ nuget source Add -Name "GitLab" -Source "https//gitlab.example/api/v4/projects/1
    ![Visual Studio NuGet source added](img/visual_studio_nuget_source_added.png)
 
 In case of any warning, please make sure that the **Location**, **Username** and **Password** are correct.
+
+### Add NuGet Repository source with .NET CLI
+
+To add the GitLab NuGet Repository as a source for .NET, create a file named `nuget.config` in the root of your project with the following content:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+    <packageSources>
+        <clear />
+        <add key="gitlab" value="https://gitlab-instance.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" />
+    </packageSources>
+    <packageSourceCredentials>
+        <gitlab>
+            <add key="Username" value="<gitlab_username>" />
+            <add key="ClearTextPassword" value="<gitlab_personal_access_token>" />
+        </gitlab>
+    </packageSourceCredentials>
+</configuration>
+```
+
+## Uploading packages
+
+When uploading packages, note that:
+
+- The maximum allowed size is 50 Megabytes.
+- If you upload the same package with the same version multiple times, each consecutive upload
+  is saved as a separate file. When installing a package, GitLab will serve the most recent file.
+- When uploading packages to GitLab, they will not be displayed in the packages UI of your project
+  immediately. It can take up to 10 minutes to process a package.
+
+### Upload packages with NuGet CLI
+
+This section assumes that your project is properly built and you already [created a NuGet package with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package).
+Upload your package using the following command:
+
+```shell
+nuget push <package_file> -Source <source_name>
+```
+
+Where:
+
+- `<package_file>` is your package filename, ending in `.nupkg`.
+- `<source_name>` is the [source name used during setup](#adding-the-gitlab-nuget-repository-as-a-source-to-nuget).
+
+### Upload packages with .NET CLI
+
+This section assumes that your project is properly built and you already [created a NuGet package with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli.).
+Upload your package using the following command:
+
+```shell
+dotnet nuget push <package_file> --source <source_name>
+```
+
+Where:
+
+- `<package_file>` is your package filename, ending in `.nupkg`.
+- `<source_name>` is the [source name used during setup](#adding-the-gitlab-nuget-repository-as-a-source-to-nuget).
+
+For example:
+
+```shell
+dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab
+```
+
+## Install packages
+
+### Install a package with NuGet CLI
+
+CAUTION: **Warning:**
+By default, `nuget` checks the official source at `nuget.org` first. If you have a package in the
+GitLab NuGet Repository with the same name as a package at `nuget.org`, you must specify the source
+name or the wrong package will be installed.
+Install the latest version of a package using the following command:
+
+```shell
+nuget install <package_id> -OutputDirectory <output_directory> \
+  -Version <package_version> \
+  -Source <source_name>
+```
+
+Where:
+
+- `<package_id>` is the package id.
+- `<output_directory>` is the output directory, where the package will be installed.
+- `<package_version>` (Optional) is the package version.
+- `<source_name>` (Optional) is the source name.
+
+### Install a package with .NET CLI
+
+CAUTION: **Warning:**
+If you have a package in the GitLab NuGet Repository with the same name as a package at a different source,
+you should verify the order in which `dotnet` checks sources during install. This is defined in the
+`nuget.config` file.
+
+Install the latest version of a package using the following command:
+
+```shell
+dotnet add package <package_id> \
+       -v <package_version>
+```
+
+Where:
+
+- `<package_id>` is the package id.
+- `<package_version>` (Optional) is the package version.