Merge pull request #644 from telerik/dess-nuget-keys

added Telerik NuGet Source article

Author: YoanKar

getting-started/Installation/images/access-nuget-keys-from-license-keys.png

@@ -18,9 +18,14 @@ This article describes how you can install the Document Processing Libraries usi
 
 ## Manually Download NuGet Packages
 
-1\. First you need to log in using your Telerik licensed account. Telerik Document Processing is a part of several Telerik bundles and is available in the Downloads section of the suite with which you've obtained the product, e.g. UI for Blazor. This way you will be able to download the packages:
+This approach allows you to setup a local NuGet package source, so you can install the Telerik products without an active Internet connection and without setting up our private feed.
+
+1\. Copy all the .nupkg files we provide to your preferred local feed location. First you need to log in using your Telerik licensed account. Telerik Document Processing is a part of several Telerik bundles and is available in the Downloads section of the suite with which you've obtained the product, e.g. UI for Blazor. This way you will be able to download the packages:
 
 ![install-using-nuget001](images/install-using-nuget001.png)
+
+
+**Telerik Document Processing** is also available as a separate distibution in your account: [Download Product Files]({%slug installation-nuget-packages%})
 
 2\. Then, you need to add packages to Visual Studio. Open the NuGet manager and then click the Options button:
 

getting-started/Installation/images/copy-nuget-key.png

@@ -1,7 +1,7 @@
 ---
 title: Restoring NuGet Packages in CI
 page_title: Restoring NuGet Packages in CI 
-description: "Learn how to use NuGet Keys to authenticate with the Telerik NuGet server and restore Telerik Document Processing packages in your CI or desktop environment."
+description: Learn how to use NuGet Keys to authenticate with the Telerik NuGet server and restore Telerik Document Processing packages in your CI or desktop environment.
 slug: using-nuget-keys
 tags: telerik, document, processing, restore, nuget, packages, ci, continuous, integration, installation
 published: True
@@ -25,14 +25,21 @@ Unlike your Telerik credentials, a NuGet Key has a limited scope and can be used
 
 1. Go to the [**Manage NuGet Keys**](https://www.telerik.com/account/downloads/nuget-keys) page in your Telerik account.
 
-1. Select the **DOWNLOADS** tab and then **Manage NuGet Keys**.
+1. Alternatively, select the **Downloads** tab from your Telerik account and then **NuGet Keys**.
 
     ![Manage NuGet Keys](images/manage-nuget-keys.png)
 
+    The **NuGet Keys** can be accessed from the **License Keys** section as well:
+
+    ![NuGet Keys from License Keys](images/access-nuget-keys-from-license-keys.png) 
+
+
 1. To create a new key, select the **Generate New Key** button.
 
 1. Enter a name for the NuGet Key, and then select **Generate Key**.
 
+    ![Generate NuGet Key](images/generate-nuget-key.png)
+ 
 1. To copy the key, select **Copy and Close**. Once you close the window, you can no longer copy the generated key. For security reasons, the **NuGet Keys** page displays only a portion of the key.
 
     ![Copy Generated NuGet Key](images/copy-nuget-key.png)
@@ -63,6 +70,8 @@ There are two popular ways to use the Telerik NuGet server in a build:
 
 For more information on how to use NuGet keys in a build, check the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy.
 
+The examples below assume that the secret environment variable name is `TELERIK_NUGET_KEY`.
+
 ### Using a nuget.config File with Your Projects
 
 1. In your `nuget.config` file, set the `Username` value to `api-key` and the `ClearTextPassword` value to an environment variable name:
@@ -77,16 +86,16 @@ For more information on how to use NuGet keys in a build, check the [Announcing
         <packageSourceCredentials>
             <MyTelerikFeed>
             <add key="Username" value="api-key" />
-            <add key="ClearTextPassword" value="%MY_API_KEY%" />
+            <add key="ClearTextPassword" value="%TELERIK_NUGET_KEY%" />
             </MyTelerikFeed>
         </packageSourceCredentials>
         ...
         </configuration>
     ```
 
-1. Set the `MY_API_KEY` environment variable by using the value of your pipeline/workflow secret.
+1. Set the `TELERIK_NUGET_KEY` environment variable by using the value of your pipeline/workflow secret.
 
-The exact steps to set the `MY_API_KEY` environment variable depend on your workflow. For more details, refer to the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy.
+The exact steps to set the `TELERIK_NUGET_KEY` environment variable depend on your workflow. For more details, refer to the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy.
 
 ### Using Only CLI Commands
 

getting-started/Installation/images/generate-nuget-key.png

@@ -0,0 +1,193 @@
+---
+title: Telerik NuGet Source
+page_title: Telerik NuGet Feed
+description: Explore the different ways to add the Telerik NuGet feed to your system, and start using NuGet packages to install the Telerik Document Processing libraries.
+slug: telerik-nuget-source
+tags: get, started, installation, nuget, feed
+published: True
+position: 8
+---
+
+# Telerik NuGet Source
+
+This article explains how to add the Telerik NuGet package feed to your environment. You can use it to obtain the Telerik Document Processing libraries instead of [setting up a local NuGet feed]({%slug installation-nuget-packages%}#manually-download-nuget-packages).
+
+The benefit of using an online NuGet source is that you will receive notifications for newer component versions.
+
+You can set up the remote Telerik NuGet feed in the following ways:
+
+* [Use Visual Studio](#use-visual-studio)
+* [Use the .NET CLI](#use-the-net-cli)
+* [Edit the Nuget.Config file](#edit-the-nuget-config-file)
+
+>tip When working with the .NET CLI or editing the `NuGet.Config` manually, you can use your Telerik account credentials or a [NuGet API Key](#use-nuget-api-key). If you are logging in to telerik.com through single sign-on (SSO), use a [NuGet API Key](#use-nuget-api-key).
+
+>warning Never hard-code Telerik account credentials or NuGet API keys in a `NuGet.Config` file in a GitHub repository, Docker image, or any location that may be accessed by unauthorized parties. A NuGet key is valuable, and bad actors can use it to access the NuGet packages that are licensed under your account. A credentials abuse can lead to a review of the affected Telerik account.
+
+For NuGet-related issues, see [Troubleshooting Telerik NuGet]({%slug troubleshooting-telerik-nuget%}).
+
+For information on automated builds, CI, and CD, see [Restoring NuGet Packages in Your CI Workflow]({%slug using-nuget-keys%}).
+
+
+## Use Visual Studio
+
+When adding NuGet sources in Visual Studio, the credentials are encrypted and stored outside the `NuGet.Config` file.
+
+Refer to the [Microsoft documentation about using packages in Visual Studio](https://learn.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio), or follow the steps below for Visual Studio on Windows.
+
+1. Open Visual Studio and go to Tools > NuGet Package Manager > Package Manager Settings > Package Sources.
+
+1. Click the **+** button at the top right-hand side.
+
+1. Add the Telerik Feed URL `https://nuget.telerik.com/v3/index.json` and choose a Name for that package source (for example, "TelerikOnlineFeed").
+
+1. Click OK.
+
+1. Open a project that references a Telerik NuGet package. 
+    * Make sure to remove local `NuGet.Config` files from the solution that contain information about Telerik packages. 
+    
+1. Rebuild the solution.
+
+1. A Windows prompt will ask for the Telerik feed credentials. Enter your Telerik email and password.
+    * Check the Remember My Password checkbox.
+    
+1. Your project should now build and restore all packages - including those from nuget.org and from Telerik.
+    * If you experience issues, see the [Troubleshooting Telerik NuGet]({%slug troubleshooting-telerik-nuget%}).
+
+
+## Use the .NET CLI
+
+When adding NuGet sources from the .NET CLI, the credentials are stored in the `NuGet.Config` file. The [password can be encrypted on Windows, but with limitations](#store-encrypted-credentials). You can use a plain text password, but for better security, [generate a NuGet API Key](#use-nuget-api-key), and use it with the .NET CLI instead of a password.
+
+To add the Telerik NuGet package source with the .NET CLI, use the [`dotnet nuget add source`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-add-source) command. This command creates or updates a `NuGet.Config` file for you, so you don't have to [edit it manually](#edit-the-nuget-config-file).
+
+The command below stores the password or NuGet API Key in plain text in the [global config file](https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior#config-file-locations-and-uses).
+
+The backslashes `\` below enable multi-line commands for better readability in terminals that support them.
+
+>caption Use the .NET CLI to add the Telerik NuGet source
+
+````SH.skip-repl
+dotnet nuget add source https://nuget.telerik.com/v3/index.json \
+--name TelerikOnlineFeed \
+--username <TELERIK EMAIL or api-key> \
+--password <TELERIK PASSWORD or NUGET API KEY> \
+--store-password-in-clear-text
+````
+
+If you have already stored the Telerik package source, you can update the configuration with the command below.
+
+>caption Use the .NET CLI to update the Telerik NuGet source
+
+````SH.skip-repl
+dotnet nuget update source "TelerikOnlineFeed" \
+--source "https://nuget.telerik.com/v3/index.json" \
+--username <TELERIK EMAIL or api-key> \
+--password <TELERIK PASSWORD or NUGET API KEY> \
+--store-password-in-clear-text
+````
+
+### Store Encrypted Credentials
+
+The .NET CLI supports NuGet password encryption only on the Windows platform. Note that [the encrypted password in the `NuGet.Config` file will work only for one user and one machine](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file#packagesourcecredentials).
+
+If you [add the Telerik package source in Visual Studio](#use-visual-studio), the credentials will be encrypted and stored in the Windows Credential Manager on Windows and in the Keychain on macOS.
+
+You can read more about the options provided by the NuGet tooling in the <a href="https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#packagesourcecredentials" target="_blank">packageSourceCredentials section of the NuGet.Config reference</a> article by Microsoft. Note the difference between the `password` and `cleartextpassword` options. 
+
+
+## Edit the NuGet.Config File
+
+NuGet package sources and other settings are stored in a `NuGet.Config` file. You can read more about the file structure in the Microsoft article [NuGet.Config Reference](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file).
+
+Make sure you are familiar with how such configurations work. Refer to [Common NuGet Configurations](https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior) for details about the possible file locations and how multiple `NuGet.Config` files work.
+
+To edit a `NuGet.Config` file and add the Telerik feed, you need to:
+
+1. Ensure you are editing the [correct and desired config file](https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior#config-file-locations-and-uses). You can also create a new one with the [`dotnet new nugetconfig` command](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new).
+
+2. Add the Telerik package source to the config file. Use plain text credentials because the .NET Core NuGet tooling does not fully support encrypted credentials. Here is an example of how your `NuGet.Config` file can look like:
+
+````XML.skip-repl
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+    <packageSources>
+    <!--To inherit the global NuGet package sources remove the <clear/> line below -->
+    <clear />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+    <add key="TelerikOnlineFeed" value="https://nuget.telerik.com/v3/index.json" />
+    </packageSources>
+    <packageSourceCredentials>
+    <TelerikOnlineFeed>
+        <add key="Username" value="<TELERIK EMAIL or api-key>" />
+        <add key="ClearTextPassword" value="<TELERIK PASSWORD or NUGET API KEY>" />
+    </TelerikOnlineFeed>
+    </packageSourceCredentials>
+</configuration>
+````
+
+### Use NuGet API Key
+
+There are two ways to authenticate with the Telerik NuGet server when you add the Telerik NuGet source [with the .NET CLI](#use-the-net-cli) or [edit the `NuGet.Config` file manually](#edit-the-nuget-config-file):
+
+* Use your Telerik account email as the username, and your Telerik password.
+* Use `api-key` as the username and your personal [NuGet API Key]({%slug using-nuget-keys%}) as the password.
+
+You can [generate your Telerik NuGet API Key on telerik.com](https://www.telerik.com/account/downloads/nuget-keys). Read more about  [Restoring NuGet Packages in Your CI Workflow]({%slug using-nuget-keys%}).
+
+> Always use the NuGet API Key in plain text.
+
+
+### Package Source Mapping
+
+The Document Processing Libraries' NuGet packages and most of its dependencies reside on `nuget.telerik.com`. On the other hand, the [`Telerik.Licensing` package]({%slug setting-up-license-key%}) resides on `nuget.org`. The correct [package source mapping](https://learn.microsoft.com/en-us/nuget/consume-packages/package-source-mapping) configuration should be similar to the one below.
+
+> Make sure that the `key` values in the `packageSourceMapping` section match the `key` values in the `packageSources` section, otherwise you will get a "Package not found" error.
+
+>caption packageSourceMapping configuration for Telerik Document Processing and other Telerik Packages
+
+<div class="skip-repl"></div>
+
+````XML
+<?xml version="1.0" encoding="utf-8" ?>
+<configuration>
+    <packageSources>
+        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+        <add key="TelerikOnlineFeed" value="https://nuget.telerik.com/v3/index.json" />
+    </packageSources>
+
+    <packageSourceMapping>
+        <packageSource key="nuget.org">
+            <package pattern="*" />
+            <package pattern="Telerik.Licensing" />
+        </packageSource>
+        <packageSource key="TelerikOnlineFeed">
+            <package pattern="Telerik*" />
+        </packageSource>
+    </packageSourceMapping>
+</configuration>
+````
+
+
+### Access NuGet Packages behind Firewall
+
+To access the Telerik NuGet feed behind a firewall that restricts outgoing requests, you may need to allow the following domains:
+
+* `nuget.telerik.com`, which provides authentication and license verification
+* `downloads.cdn.telerik.com`, which hosts the NuGet packages
+
+The firewall must allow some of the requests to be redirected from `nuget.telerik.com` to `downloads.cdn.telerik.com`.
+
+### Obsolete Telerik NuGet URL
+
+The NuGet v2 server at `https://nuget.telerik.com/nuget` was sunset in November 2024 and is no longer available. The v3 protocol offers faster package searches and restores, improved security, and more reliable infrastructure. To redirect your feed to the NuGet v3 protocol, all you have to do is change your NuGet package source URL to `https://nuget.telerik.com/v3/index.json`.
+
+
+### Troubleshooting
+
+See the [NuGet Troubleshooting](slug:troubleshooting-nuget) article for tips about common pitfalls when working with the Telerik NuGet feed.
+
+## See Also
+
+* [Restoring NuGet Packages in Your CI Workflow]({%slug using-nuget-keys%})
+* [Install using NuGet Packages]({%slug installation-nuget-packages%})