Skip to content

docs(Common): Improve Getting Started experience for non-Windows devs #3423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dimodi wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(Common): Improve Getting Started experience for non-Windows devs #3423

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 28 additions & 16 deletions _contentTemplates/common/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,39 +36,51 @@ Whenever you need to authenticate your system with the Telerik NuGet server, use
#end

#add-nuget-feed
## Step 3: Add the Telerik NuGet Feed to Visual Studio
## Step 3: Add the Telerik NuGet Feed

In this tutorial, you will use the [Telerik NuGet feed](slug:installation/nuget) to download the UI for Blazor components. This NuGet feed is private and requires you to authenticate with a NuGet API key.
In this tutorial, you will use the [Telerik NuGet server](slug:installation/nuget) to download the UI for Blazor components. The NuGet feed is private and requires you to authenticate with a NuGet API key.

To generate your NuGet API key:
### Generate NuGet API Key

1. Go to the [API Keys](https://www.telerik.com/account/downloads/api-keys) page in your Telerik account.

1. Click **Generate New Key +**.

1. In the **Key Note** field, add a note that describes the API key.

1. Click **Generate Key**.

1. Select **Copy and Close**. Once you close the window, you can no longer copy the generated key. For security reasons, the **API Keys** page displays only a portion of the key.

1. Store the generated NuGet API key as you will need it in the next steps.

Next, add the Telerik NuGet feed to Visual Studio:

1. In Visual Studio and go to **Tools** > **NuGet Package Manager** > **Package Manager Settings**.
Next, add the Telerik NuGet feed to your local development environment:

1. Select **Package Sources** and then click the **+** button to add a new package source.
* [Visual Studio on Windows](#visual-studio)
* [All IDEs and operating systems](#all-ides-and-operating-systems)

1. Enter a **Name** for the new package source, for example, `telerik.com`.
>tip For more information on the Telerik NuGet packages and download options, check [section NuGet Packages in the Workflow article](slug:getting-started/what-you-need#nuget-packages).

1. Add the `https://nuget.telerik.com/v3/index.json` URL as a **Source**. Click **OK**.
### Visual Studio

![Add the Telerik NuGet Feed in Visual Studio](images/telerik-nuget-feed.png)
The following approach will store the Telerik NuGet server URL in your [global `NuGet.Config` file](https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior), and save your NuGet API key in the Windows Credential Manager.

1. Go to **Tools** > **NuGet Package Manager** > **Package Manager Settings**.
1. Select **Package Sources** and then click the **+** or **Add** button.
1. Enter a **Name** for the new package source. The examples in this documentation usually use `TelerikOnlineFeed`.
1. Add `https://nuget.telerik.com/v3/index.json` as a **Source** URL. Click **OK** or **Save**.
1. Whenever Visual Studio displays a dialog to enter credentials for `nuget.telerik.com`, use `api-key` as the username and your NuGet API key as the password.

>tip For alternative NuGet package download options, check the [Workflow article](slug:getting-started/what-you-need).
### All IDEs and Operating Systems

Run [`dotnet nuget add source`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-add-source) in your preferred command line interface (cmd, Terminal, PowerShell, Bash). The command will store the Telerik NuGet server URL and your NuGet API key in your [global `NuGet.Config` file](https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior).

Replace `<YOUR-NUGET-API-KEY>` with the API key that you [generated previously](#generate-nuget-api-key).

>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 api-key \
--password <YOUR-NUGET-API-KEY> \
--store-password-in-clear-text
````

#end

Expand Down
18 changes: 3 additions & 15 deletions getting-started/client-blazor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,26 +32,14 @@ This article explains how to get the <a href = "https://www.telerik.com/blazor-u

## Step 2: Create a New Project

1. Open Visual Studio and select **Create a new project**.

1. Select the **Blazor WebAssembly App** project type, enter a name for your project, and then click **Next**.

1. Select the **ASP.NET Core hosted** checkbox and the desired framework, and then click **Create**.
* To create a new Blazor app, open your preferred IDE or [run the `dotnet new` .NET CLI command](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new).
* Use the [**Blazor WebAssembly Standalone App**](https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure) project template.

@[template](/_contentTemplates/common/get-started.md#add-nuget-feed)

## Step 4: Install the Telerik UI for Blazor Components

1. Right-click the `.Client` project in the solution and select **Manage NuGet Packages**.

![Manage NuGet Packages](images/manage-nuget-packages-for-client-app.png)

2. Install the Telerik Blazor NuGet package:

1. Select the `telerik.com` **Package source** that you [added earlier](#step-3-add-the-telerik-nuget-feed-to-visual-studio). As this is a private NuGet feed, you must authenticate using `api-key` as the username and [your NuGet API key](#step-3-add-the-telerik-nuget-feed-to-visual-studio) as the password.
1. Select the **Browse** tab, find the `Telerik.UI.for.Blazor` NuGet package, and click **Install**.

![Add Telerik Blazor Package to Client Project](images/add-telerik-nuget-to-client-app.png)
Add the `Telerik.UI.for.Blazor` NuGet package from the package source that you [added earlier](#step-3-add-the-telerik-nuget-feed) to every project that will use the Telerikk Blazor components. When prompted, authenticate using `api-key` as the username and [your NuGet API key](#generate-nuget-api-key) as the password.

## Step 5: Enable the Blazor UI Components

Expand Down
Binary file removed getting-started/images/add-telerik-nuget-to-client-app.png
View file
Open in desktop
Binary file not shown.
Binary file removed getting-started/images/add-telerik-nuget-to-server-app.png
View file
Open in desktop
Binary file not shown.
Binary file removed getting-started/images/manage-nuget-packages-for-client-app.png
View file
Open in desktop
Binary file not shown.
Binary file removed getting-started/images/telerik-nuget-feed.png
View file
Open in desktop
Binary file not shown.
23 changes: 8 additions & 15 deletions getting-started/web-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,17 +36,16 @@ This article explains how to use the Telerik UI for Blazor components in a Blazo

## Step 2: Create a New Project

1. Open Visual Studio and select **Create a new project**.
To create a new Blazor app:

1. Select the [**Blazor Web App**](https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure?view=aspnetcore-8.0#blazor-web-app) project type, enter a name for your project, and then click **Next**.

1. Select the desired [Interactive render mode](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#render-modes) and **Global** Interactivity location. Global interactivity ensures easier setup and usage of the Telerik components.

1. Click **Create**.
1. Open your preferred IDE or [run the `dotnet new` .NET CLI command](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new).
1. Use the [**Blazor Web App**](https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure) project template.
1. Select the desired [interactive render mode](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes).
1. Enable **Global** Interactivity location.

### Interactive Render Mode

> Telerik UI for Blazor requires interactive render mode. Using [**Global** Interactivity location](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-9.0#apply-a-render-mode-to-the-entire-app) is highly recommended.
> Telerik UI for Blazor requires interactive render mode. Using [**Global** Interactivity location](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-9.0#apply-a-render-mode-to-the-entire-app) is highly recommended, as it ensures easier setup and usage of the Telerik components.
> The Telerik Blazor components will not respond to user actions and the Blazor framework will not refresh their UI in [Static server-side rendering mode (static SSR)](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-9.0#static-server-side-rendering-static-ssr). Telerik Blazor components with JavaScript rendering (Barcodes, Charts, Gauges, Maps, and QR Codes) will not render in static SSR at all.
>
> The `Account` section in the Blazor Web App template with identity is static by design. Most Telerik Blazor components cannot work in this section.
Expand All @@ -55,15 +54,9 @@ This article explains how to use the Telerik UI for Blazor components in a Blazo

## Step 4: Install the Telerik UI for Blazor Components

1. To include the Telerik component library, right-click each project that will use Telerik Blazor components, and select **Manage NuGet Packages**.

* Apps with interactive Server render mode need the Telerik Nuget package in the server project.
* Apps with global interactive Auto or WebAssembly render mode need the Telerik NuGet package in the client project.

1. Install the Telerik Blazor NuGet package:
Add the `Telerik.UI.for.Blazor` package from the NuGet source that you [added earlier](#step-3-add-the-telerik-nuget-feed) to every project that will use the Telerik Blazor components. Apps with global interactive **Auto** or **WebAssembly** render mode need the Telerik NuGet package in the `Client` project.

1. Select the `telerik.com` **Package source** that you [added earlier](#step-3-add-the-telerik-nuget-feed-to-visual-studio). As this is a private NuGet feed, you must authenticate using `api-key` as the username and [your NuGet API key](#step-3-add-the-telerik-nuget-feed-to-visual-studio) as the password.
1. Select the **Browse** tab, find the `Telerik.UI.for.Blazor` NuGet package, and click **Install**.
When prompted, authenticate using `api-key` as the username and [your NuGet API key](#generate-nuget-api-key) as the password.

## Step 5: Enable the Blazor UI Components

Expand Down