diff --git a/_contentTemplates/common/get-started.md b/_contentTemplates/common/get-started.md
index ff31fb5f8f..7d6f813128 100644
--- a/_contentTemplates/common/get-started.md
+++ b/_contentTemplates/common/get-started.md
@@ -130,6 +130,8 @@ To setup a local NuGet package source, so you can install the Telerik components
#root-component-telerik-layout
+To use popups (for example, dropdowns, menus, windows, grid filters, etc.), you must add the `TelerikRootComponent` component at the root level of the app:
+
Next to your main layout file (by default, the `~/Shared/MainLayout.razor` file in the Blazor project), add a Razor component called `TelerikLayout.razor` with the following content:
@inherits LayoutComponentBase
diff --git a/_contentTemplates/common/js-interop-file.md b/_contentTemplates/common/js-interop-file.md
index 13541a5051..d0459aa6ff 100644
--- a/_contentTemplates/common/js-interop-file.md
+++ b/_contentTemplates/common/js-interop-file.md
@@ -48,7 +48,7 @@
#end
#enable-static-assets
- To enable the use of static assets in your project, add the following line to the `Startup.cs` file in the **Server** project:
+ To enable the use of static assets in your project, add the following line to the `Program.cs` file in the **Server** project:
**C#**
@@ -71,28 +71,11 @@ app.UseStaticFiles();
app.Run();
````
-````Startup.cs
-namespace MyBlazorAppName
-{
- public class Startup
- {
- public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
- {
- // ...
-
- //To enable static files from a package, make sure this is present.
- app.UseStaticFiles();
-
- // ...
- }
- }
-}
-````
#end
#register-telerik-service-server
-````Program.cs
+````
// ...
var builder = WebApplication.CreateBuilder(args);
@@ -105,21 +88,6 @@ builder.Services.AddTelerikBlazor();
var app = builder.Build();
````
-````Startup.cs
-namespace MyBlazorAppName
-{
- public class Startup
- {
- public void ConfigureServices(IServiceCollection services)
- {
- // ...
- services.AddTelerikBlazor();
- }
-
- // ...
- }
-}
-````
#end
#register-telerik-service-client
diff --git a/getting-started/client-blazor.md b/getting-started/client-blazor.md
index ee8dc3c215..6353acc6a9 100644
--- a/getting-started/client-blazor.md
+++ b/getting-started/client-blazor.md
@@ -5,7 +5,7 @@ description: Make your first steps with Telerik UI for Blazor and build an app t
slug: getting-started/client-side
tags: get,started,first,steps,client
published: true
-position: 1
+position: 2
---
# First Steps with Client-Side UI for Blazor
@@ -39,17 +39,16 @@ This article explains how to get the .NET 8 Blazor Web App project template. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view.
+
+@[template](/_contentTemplates/common/get-started.md#prerequisites-download)
+
+## Step 1: Create a New Project
+
+1. Open Visual Studio and select **Create a new project**.
+
+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 .NET 8 framework, the desired [interactive render mode](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#render-modes) and interactivity location (per page or global).
+
+1. Click **Create**.
+
+@[template](/_contentTemplates/common/get-started.md#add-nuget-feed)
+
+## Step 3: Install the Telerik UI for Blazor Components
+
+1. Right-click the Blazor Server project in the solution and select **Manage NuGet Packages**.
+
+1. Install the Telerik Blazor NuGet package:
+
+ 1. Select the `telerik.com` **Package source** that you [added earlier](#step-2-add-the-telerik-nuget-feed-to-visual-studio). As this is a private NuGet feed, you must authenticate with your [Telerik account](https://www.telerik.com/account/) username and password.
+ 1. Select the **Browse** tab, find the NuGet package, and click **Install**. Commercial license holders must install `Telerik.UI.for.Blazor`. Trial users must install `Telerik.UI.for.Blazor.Trial`.
+
+## Step 4: Enable the Blazor UI Components
+
+To enable the Telerik UI for Blazor components, you must add several client-side dependencies to the application, include the required `@using` statements, add the `TelerikRootComponent` component, and register the Telerik Blazor service.
+
+### 4.1. Add the Telerik UI for Blazor Client Assets
+
+1\. Add the `telerik-blazor.js` file to your `App.razor` file as a [static asset]({%slug getting-started/what-you-need%}#using-static-assets) or from a [CDN]({%slug getting-started/what-you-need%}#using-cdn).
+
+**HTML**
+
+@[template](/_contentTemplates/common/js-interop-file.md#js-interop-file-snippet)
+
+2\. To select the appearance and color scheme for the Telerik Blazor components, add the [theme stylesheet]({%slug general-information/themes%}) in your `App.razor` file. Reference it as a [static asset]({%slug general-information/themes%}#static-assets) or from a [CDN]({%slug general-information/themes%}#cdn).
+
+3\. (Optional) To enable the use of static assets in your project, add the `app.UseStaticFiles();` line to the `Program.cs` of your Blazor Server project (by default, this line is already present). This step is required only if your application uses static assets.
+
+**C#**
+@[template](/_contentTemplates/common/js-interop-file.md#enable-static-assets-snippet)
+
+### 4.2. Include @using Statements
+
+In the `~/_Imports.razor` file, add the `@using` directives below. This configures the project to recognize the Telerik components in all files. You can register one or both icon namespaces, depending on the [icon type you use]({%slug general-information/font-icons%}).
+
+**_Imports.razor**
+
+ @using Telerik.Blazor
+ @using Telerik.Blazor.Components
+ @using Telerik.FontIcons
+ @using Telerik.SvgIcons
+
+### 4.3. Add the TelerikRootComponent
+
+Add a `TelerikRootComponent` component as a top-level component in the app and make sure it wraps all content. Add the component in the preferred layout file, for example, the `MainLayout.razor` or a custom layout file. The `TelerikRootComponent` must be placed in a layout page with enabled [interactive mode](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0), for example, `MainLayout.razor`.
+
+> .NET 8.0 introduces [new render modes for the Blazor components](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0). At the time of writing, the default render mode is static and not interactive, so you need to make this change explicitly in your app.
+
+How you add the `TelerikRootComponent` to the app depends on which of the following approaches for configuring the render mode you chose:
+
+* [Configure the Render Mode of the Entire App](#configure-the-render-mode-of-the-entire-app)
+* [Configure the Render Mode per Page](#configure-the-render-mode-per-page)
+
+
+#### Configure the Render Mode of the Entire App
+
+You can set the render mode for the entire app as suggested in the [Blazor documentation](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#set-the-render-mode-for-the-entire-app). This will spare the need to set the render mode in every page and component.
+
+
+````App.razor
+
+
+
+
+ @* ... *@
+
+
+
+
+
+
+ @* ... *@
+
+
+
+````
+````MainLayout.razor
+@inherits LayoutComponentBase
+
+
+
+
+ An unhandled error has occurred.
+ Reload
+ 🗙
+
+````
+````Home.razor
+@page "/"
+
+@rendermode RenderMode.InteractiveServer
+
+@* Telerik UI for Blazor components here *@
+
+````
+
+#### Configure the Render Mode per Page
+
+As an alternative to setting the render mode for the entire app, you can set it only for specific pages and components. This is useful if you want to have different render modes in the app. In this case, make sure that the `TelerikRootComponent` is part of a component hierarchy that has interactive render mode.
+
+See the example below - the `TelerikRootComponent` must wrap all the content in the viewport, so the whole `
` is moved from the `MainLayout.razor` to the `TelerikLayout.razor`.
+
+
+
+````MainLayout.razor
+@inherits LayoutComponentBase
+
+@implements IDisposable
+
+@Body
+
+@code {
+ protected override Task OnInitializedAsync()
+ {
+ return base.OnInitializedAsync();
+ }
+
+ public void Dispose()
+ {
+ }
+}
+````
+````TelerikLayout.razor
+@rendermode RenderMode.InteractiveServer
+
+
+
+
+ An unhandled error has occurred.
+ Reload
+ 🗙
+
+
+
+
+@code{
+ [Parameter]
+ public RenderFragment ChildContent {get;set;}
+}
+````
+````Home.razor
+@page "/"
+
+@rendermode RenderMode.InteractiveServer
+
+
+
+ @* Telerik UI for Blazor components here *@
+
+
+````
+
+### 4.4. Register the Telerik Blazor Service
+
+In a Blazor Web App project with interactive render mode Server, you register services in the `Program.cs` file of your project.
+
+For interactive render modes WebAssembly and Auto, register the service in the `Program.cs` file of both the server and client project.
+
+**C#**
+@[template](/_contentTemplates/common/js-interop-file.md#register-telerik-service-server)
+
+Now your Blazor Server project can use the Telerik UI for Blazor components.
+
+## Step 5: Add a Component to a View
+
+The final step in this tutorial is to use a Telerik UI for Blazor component in a view and run it in the browser.
+
+1. In the `~/Components/Pages/Home.razor` view, add a `TelerikButton` component.
+
+
+ **RAZOR**
+
+ Say Hello
+
+1. Optionally, hook up a click handler that will show a message. The resulting view will look like this:
+
+ **RAZOR**
+
+ @page "/"
+
+ Say Hello
+
+
+
+ @helloString
+
+ @code {
+ MarkupString helloString;
+
+ void SayHelloHandler()
+ {
+ string msg = string.Format("Hello from Telerik Blazor at {0}. Now you can use C# to write front-end!", DateTime.Now);
+ helloString = new MarkupString(msg);
+ }
+ }
+
+1. Run the app in the browser by pressing `F5`. You should see something like this:
+
+ 
+
+Well done! Now you have you first Telerik UI for Blazor component running in your Blazor Web App.
\ No newline at end of file
diff --git a/getting-started/what-you-need.md b/getting-started/what-you-need.md
index 0ed1a07443..8a3aeb3612 100644
--- a/getting-started/what-you-need.md
+++ b/getting-started/what-you-need.md
@@ -6,14 +6,14 @@ slug: getting-started/what-you-need
previous_url: /installation/what-you-need
tags: get,started,installation,what,need,list
published: True
-position: 4
+position: 1
---
# Typical Workflow for Using the UI for Blazor Components
This article describes the steps in the typical workflow for using the Telerik UI for Blazor components—getting the Telerik UI for Blazor components and configuring your project to use them.
->tip The information in this article is also available as step-by-step tutorials for Blazor [Server]({%slug getting-started/server-side%}) and [WebAssembly]({%slug getting-started/client-side%}) apps.
+>tip The information in this article is also available as step-by-step tutorials for Blazor [Server]({%slug getting-started/server-side%}), [WebAssembly]({%slug getting-started/client-side%}), [.NET 8 Blazor Web App]({%slug getting-started/web-app%}) and [Blazor Hybrid]({%slug getting-started/hybrid-blazor%}) apps.
To use the Telerik UI for Blazor, you need to:
@@ -72,8 +72,9 @@ The Telerik UI for Blazor components require a [Telerik stylesheet](#telerik-sty
* For Client-Side and Blazor Hybrid apps, use the `wwwroot/index.html` file.
* For Server-Side Blazor apps, use one of the following files:
- * `~/Pages/_Host.cshtml` for .NET 3.x
* `~/Pages/_Layout.cshtml` for .NET 6
+ * `~/Pages/_Host.cshtml` for .NET 7
+ * For Web App projects targeting .NET 8, use the `~/Components/App.razor`.
To add these client assets, use either the [static assets](#using-static-assets) or the [CDN](#using-cdn) method.
@@ -81,10 +82,7 @@ To add these client assets, use either the [static assets](#using-static-assets)
You can add the [Telerik JS Interop file](#telerik-js-interop-file) and the [Telerik Stylesheet](#telerik-stylesheet) as [static assets](https://docs.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-6.0&tabs=visual-studio#consume-content-from-a-referenced-rcl). Static assets (the `_content` folder) are automatically included in the solution from the NuGet package during build, so all you need is to enable static assets as shown in the snippet below. The `_content` folder is expanded by the framework into the local NuGet cache, and the project copies it from there.
-To enable the use of static assets in your project, add the `app.UseStaticFiles();` line to the startup file of your **Server** project (by default, this line is already present):
-
- * `Startup.cs` for .NET 3.x and .NET 5
- * `Program.cs` for .NET 6
+To enable the use of static assets in your project, add the `app.UseStaticFiles();` line to the `Program.cs` file of your **Server** project (by default, this line is already present).
**C#**
@[template](/_contentTemplates/common/js-interop-file.md#enable-static-assets-snippet)
@@ -110,7 +108,6 @@ The JS Interop file provides features that cannot be implemented with native Bla
>Telerik recommends using [static assets](#static-assets) instead of a CDN. This approach relies on the static assets feature from the framework and takes the correct file from the package so you don't have to remember to update the CDN path when [upgrading to a newer version]({%slug upgrade-tutorial%}).
-
## Configuring the Project
@@ -122,11 +119,16 @@ To use the Telerik components, you must add a few items to your projects. Some o
* [Client-side (WASM)](#client-side-project-specifics)
* [Server-side](#server-side-project-specifics)
+ * [Web App Template](#web-app-template)
* [Blazor Hybrid](#blazor-hybrid-project-specifics)
### Common Configuration
+To make sure that the application will recognize the UI for Blazor components and that they will function correctly, add the required `@using` statements and the `TelerikRootComponent`.
+
+#### Include @using Statements
+
You can set the project to recognize all Telerik components without explicit `@using` statements on every `.razor` file. To achieve this, add the following to your `~/_Imports.razor` file. You can register one or both icon namespaces, depending on the [icon type you will be using]({%slug general-information/font-icons%}).
>caption _Imports.razor
@@ -140,11 +142,17 @@ You can set the project to recognize all Telerik components without explicit `@u
@using Telerik.SvgIcons
````
-To enable the use of detached popups (for example, dropdown lists, menus, grid filters, etc.), you must add a `TelerikLayout.razor` component at the root level of the DOM:
+#### Add the TelerikRootComponent
+
+To use popups (for example, dropdowns, menus, windows, grid filters, etc.), you must add the `TelerikRootComponent` component at the root level of the app and configure the app layout to adopt that.
+
+The configuration varies depending on the application type:
-1\. @[template](/_contentTemplates/common/get-started.md#root-component-telerik-layout)
+* [Server]({%slug getting-started/server-side%}#43-add-the-telerikrootcomponent)
+* [WebAssembly]({%slug getting-started/client-side%}#43-add-the-telerikrootcomponent)
+* [Web App]({%slug getting-started/web-app%}#43-add-the-telerikrootcomponent)
+* [Blazor Hybrid]({%slug getting-started/hybrid-blazor%}#4-add-the-telerikrootcomponent)
-2\. @[template](/_contentTemplates/common/get-started.md#root-component-main-layout)
### Client-side Project Specifics
@@ -155,10 +163,16 @@ The final step is to register the Telerik services. In a client-side Blazor proj
### Server-side Project Specifics
-The final step is to register the Telerik services. In a server-side Blazor project, you register services in the startup file of your project which varies depending on the used .NET version:
+The final step is to register the Telerik services. In a server-side Blazor project, you register services in the `Program.cs` file of your project.
+
+**C#**
+@[template](/_contentTemplates/common/js-interop-file.md#register-telerik-service-server)
+
+### Web App Project Specifics
+
+The final step is to register the Telerik services. In a Blazor Web App project with interactive render mode Server, you register services in the `Program.cs` file of your project.
-* `Startup.cs` for .NET 3.x and .NET 5
-* `Program.cs` for .NET 6
+For interactive render modes WebAssembly and Auto, register the service in the `Program.cs` file of both the server and client project.
**C#**
@[template](/_contentTemplates/common/js-interop-file.md#register-telerik-service-server)
diff --git a/system-requirements.md b/system-requirements.md
index 8d548f663c..55fecc0978 100644
--- a/system-requirements.md
+++ b/system-requirements.md
@@ -16,16 +16,16 @@ Telerik UI for Blazor steps on Microsoft Blazor. You can host and run Telerik Bl
## .NET Versions Support
-Telerik UI for Blazor targets `netstandard2.1`. Thus, apps and libraries that reference our package must use one of the following target frameworks:
+The latest version of Telerik UI for Blazor (currently {{site.uiForBlazorLatestVersion}}) targets `net6.0`. Thus, apps and libraries that reference our package must use one of the following target frameworks:
-* `netstandard2.1`
-* `netcoreapp3.1`
-* `net5.0`
* `net6.0`
* `net7.0`
+* `net8.0`
Razor Class Libraries may target `netstandard2.0` by default, so you need to update that.
+>warning If your application targets an older framework version, the latest Telerik UI for Blazor you can use is `4.6.0`.
+
### Supported .NET Versions
A **supported .NET version** is one that is [officially supported by Microsoft](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core). It will successfully run our NuGet package and Telerik Blazor components. We don't expect any .NET-related issues, but if such issues occur, we will resolve them.
@@ -36,6 +36,7 @@ A **supported .NET version** is one that is [officially supported by Microsoft](
| .NET version | First UI for Blazor Version | Last UI for Blazor Version |
| --- | --- | --- |
+| .NET 8 | 5.0.0 | {{site.uiForBlazorLatestVersion}} (current official) |
| .NET 7 | 3.7.0 | {{site.uiForBlazorLatestVersion}} (current official) |
| .NET 6 | 2.29.0 | {{site.uiForBlazorLatestVersion}} (current official) |
@@ -43,13 +44,12 @@ A **supported .NET version** is one that is [officially supported by Microsoft](
A **compatible .NET version** is one that is *no longer* (or *not yet*) officially supported by Microsoft. The Telerik Blazor components should work in apps with that .NET version. We don't expect any .NET-related issues, but if such issues occur, we have no commitment to fix them.
->warning Telerik UI for Blazor version `4.6.0` will be the last version compatible with `.NET Core 3.1` and `.NET 5`.
+>warning Telerik UI for Blazor version `4.6.0` is the last version compatible with `.NET Core 3.1` and `.NET 5`.
>caption .NET versions that are compatible with Telerik UI for Blazor
| .NET version | First UI for Blazor Version | Last UI for Blazor Version |
| --- | --- | --- |
-| .NET 8 RC 2 ([see specifics]({%slug troubleshooting-general-issues%}#telerikrootcomponent-is-missing-in-net-80)) | 4.6.0 | {{site.uiForBlazorLatestVersion}} (current official) |
| .NET 5 | 2.19.0 | 4.6.0 |
| .NET Core 3.1 | 2.5.0 | 4.6.0 |
diff --git a/troubleshooting/general-issues.md b/troubleshooting/general-issues.md
index 22c7076d16..de35d8edc9 100644
--- a/troubleshooting/general-issues.md
+++ b/troubleshooting/general-issues.md
@@ -26,115 +26,15 @@ This page provides solutions for common issues you may encounter while working w
## TelerikRootComponent is missing in .NET 8.0
-The latest UI for Blazor (4.6.0) provides [compatibility with .NET 8.0 RC 2]({%slug system-requirements%}#compatible-net-versions). This framework version [is not yet supported]({%slug system-requirements%}#supported-net-versions) and we do not recommend using our components with it until officially supported.
-
-If you need to start testing with .NET 8.0 RC 2 at this stage, be aware of the following error you may hit when using the new [Blazor Web App template](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-rc-1/#blazor-web-app-template-updates)
+Using a [Blazor Web App template](https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure?view=aspnetcore-8.0#blazor-web-app), the following error occurs:
>warning Error: System.Exception: A Telerik component on the requested view requires a TelerikRootComponent to be added to the root of the MainLayout component of the app.
The root cause for this is a difference in the required configuration when using [interactive render modes](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#enable-support-for-interactive-render-modes).
-.NET 8.0 introduces [new render modes for the Blazor components](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0). The `TelerikRootComponent` must be placed in a layout page (e.g. `MainLayout.razor`) with enabled interactive mode. At the time of writing, the default render mode is `Static` and not interactive, so you need to make this change explicitly in your app.
-
-Here are two possible options to proceed:
-
-* Set the render mode for the whole app as suggested in the [Blazor documentation](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#set-the-render-mode-for-the-entire-app). This will spare the need to set the render mode in every page and component.
-
-* Set interactive render mode for specific pages and components. This is useful if you want to have different render modes in the app. In this case, make sure that the `TelerikRootComponent` is placed in a component hierarchy that has interactive render mode. See the example below:
-
-
-
-````MainLayout.razor
-@inherits LayoutComponentBase
-
-@implements IDisposable
-
-@Body
-
-@code {
- protected override Task OnInitializedAsync()
- {
- return base.OnInitializedAsync();
- }
-
- public void Dispose()
- {
- }
-}
-````
-````CustomLayout.razor
-@rendermode RenderMode.InteractiveServer
-
-
-
-
-````
-````Home.razor
-@page "/"
-
-@rendermode RenderMode.InteractiveServer
-
-
-
- @* Telerik UI for Blazor components here *@
-
-
-````
+This error will be thrown if the `TelerikRootComponent` is placed in a layout page that does not have interactive mode enabled.
->tip Consider and choose any configuration that best suits your application needs. The important part is to ensure that the layout component where the `TelerikRootComponent` is defined has interactive mode.
+The `TelerikRootComponent` must be placed in a layout page (e.g. `MainLayout.razor`) with enabled interactive mode. Read more in [Web App - Add TelerikRootComponent]({%slug getting-started/web-app%}#43-add-the-telerikrootcomponent).
## Popups Do Not Work