Skip to content

Commit b35cc0d

Browse files
marin-bratanovmarin-bratanov
committed
docs(common): upgrade instructions, first pass
1 parent b89a462 commit b35cc0d

File tree

4 files changed

+112
-6
lines changed

4 files changed

+112
-6
lines changed

‎_contentTemplates/common/general-info.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
#event-callback-can-be-async
22
>tip The event is an `EventCallback` and its type can be `void`, or it can also be asynchronous and return `async Task`.
3+
#end
4+
5+
#ensure-nuget-packge-for-upgrade
6+
Make sure that you have a NuGet feed source with the version you want to upgrade to. This is usually the [Telerik NuGet Feed]({%slug installation/nuget%}), but you can also use a local feed from [our MSI installer]({%slug installation/msi%}) or [ZIP archive]({%slug installation/zip%}).
37
#end

knowledge-base/changes-in-2-0-0.md renamed to upgrade/breaking-changes/2-0-0.md

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,9 @@
11
---
22
title: Breaking Changes in 2.0.0
33
description: Handle the changes in the 2.0.0 major release of the Telerik UI for Blazor components.
4-
type: how-to
5-
page_title: Changes in 2.0.0
4+
page_title: Breaking Changes in 2.0.0
65
slug: changes-in-2-0-0
7-
position:
8-
tags:
9-
ticketid:
10-
res_type: kb
6+
position: 1
117
---
128

139
In the `2.0.0` release, there are some changes in the Telerik Blazor components that have been brewing for a while due to the evolution of the framework. This article explains what they are and what you need to change.

‎upgrade/breaking-changes/list.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: List of Versions with Breaking Changes
3+
description: See which versions have breaking changes so you can take them into account when upgrading.
4+
page_title: List of Telerik UI for Blazor Versions with Breaking Changes
5+
slug: versions-with-breaking-changes
6+
position: 0
7+
---
8+
9+
This article lists the releases of the Telerik UI for Blazor product that introduce breaking changes. You may want to go through it when [upgrading]({%slug upgrade-tutorial%}) to see whether you are affected.
10+
11+
* [2.0.0]({%slug changes-in-2-0-0%})
12+

‎upgrade/how-to-upgrade.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: How to Upgrade
3+
page_title: How to Upgrade the Telerik UI for Blazor Version
4+
description: How to Upgrade the version of the Telerik UI for Blazor package
5+
slug: upgrade-tutorial
6+
tags: upgrade,tutorial,changes,update
7+
published: True
8+
position: 0
9+
---
10+
11+
# How to Upgrade Telerik UI for Blazor
12+
13+
This article explains how to upgrade to a new version of Telerik UI for Blazor.
14+
15+
To upgrade the Telerik components, you need to update their NuGet package reference, and, if you use them, the CDN links.
16+
17+
>tip Before stating an upgrade of your project, you may find it useful to review the following information:
18+
>
19+
> Whether you are affected by a breaking change. The [List of Telerik UI for Blazor Versions with Breaking Changes]({%slug versions-with-breaking-changes%}) article shows which releases of our component suite have breaking changes. Review the information for the releases you go through so you can evaluate whether you will be affected by anything.
20+
> [UI for Blazor Release History](https://www.telerik.com/support/whats-new/blazor-ui/release-history) — reviewing the release notes for all releases you go through will let you see what has changed, what fixes, features and components have been implemented so you are better prepared to meet your project's challenges.
21+
22+
## Upgrade Process
23+
24+
To upgrade the Telerik UI for Blazor components used in your project, perform the following steps:
25+
26+
1. @[template](/_contentTemplates/common/general-info.md#ensure-nuget-packge-for-upgrade)
27+
28+
1. Update the version of the `Telerik.UI.for.Blazor` package your project references. If you are using a trial version, the package name is `Telerik.UI.for.Blazor.Trial`.
29+
30+
1. If you are using our CDN for the JS Interop file, update the version in its URL. It must match the version of the package itself. For example, if you are upgrading to the `2.0.0` version, the CDN link must be:
31+
32+
**HTML**
33+
34+
<script src="https://kendo.cdn.telerik.com/blazor/2.0.0/telerik-blazor.min.js" defer></script>
35+
36+
Generally, the URL has the following format:
37+
38+
**HTML**
39+
40+
<script src="https://kendo.cdn.telerik.com/blazor/<VERSION NUMBER>/telerik-blazor.min.js" defer></script>
41+
42+
## Upgrade from Trial to Commercial
43+
44+
If you have just purchased a license and you need to migrate from the trial packae to the licensed version, perform the following steps:
45+
46+
1. @[template](/_contentTemplates/common/general-info.md#ensure-nuget-packge-for-upgrade)
47+
48+
1. Replace the reference to the `Telerik.UI.for.Blazor.Trial` package in your project with a reference to the `Telerik.UI.for.Blazor` package.
49+
50+
1. If you are using static assets for our JS Interop file, update its path to match the package name:
51+
52+
**HTML**
53+
54+
<!-- FROM
55+
<script src="_content/telerik.ui.for.blazor.trial/js/telerik-blazor.js" defer></script>
56+
57+
TO
58+
-->
59+
<script src="_content/telerik.ui.for.blazor/js/telerik-blazor.js" defer></script>
60+
61+
## Troubleshooting
62+
63+
### Microsoft.JSInterop.JSException: Could not find
64+
65+
After upgrading you may get runtime error messages in the browser console similar to the following:
66+
67+
* `Error: Microsoft.JSInterop.JSException: Could not find 'initGrid' in 'window.TelerikBlazor'.`
68+
* `Error: Could not find 'TelerikBlazorPopup' in 'window'.`
69+
* Generally, errors referring to a Telerik component that cannot be found in the JS code.
70+
71+
If you get such errors, the reason is that the JS Interop file we need is missing, or it has an incorrect version.
72+
73+
#### Incorrect Version
74+
75+
The version may be wrong (and thus, not having all the needed features), if you use our CDN to fetch the file, and its path is not updated to match the package version. See the [Upgrade Process](#upgrade-process) section above to update the path.
76+
77+
#### Missing File
78+
79+
You can check if this is the case by inspecting the Network tab of your browser console to see if it is returning successfully. There are a few common causes for the JS Interop file to be missing:
80+
81+
* The application is missing references to the needed [assets]({%slug getting-started/what-you-need%}#client-assets).
82+
* Network setup blocks access to the cloud, and thus, to our CDN. If this is the case, you have two options:
83+
* Discuss the case with your network administrators to have our CDN allowed.
84+
* Use [static assets]({%slug getting-started/what-you-need%}#static-assets) from the app folder to avoid going to the cloud.
85+
* The application was upgraded from a trial to a commercial license, but the path to the file was not. See the [Upgrade from Trial to Commercial](#upgrade-from-trial-to-commercial) section for details.
86+
* Static assets are not enabled on the server project, or the hosting environment does not work well with them. You need to ensure that the static assets are available after the build and on the deployment server. It is also possible that the hosting server does not support static assets or has issues with them and you may need to confirm this with the hosting provider or by testing with a simple package having a static asset to see whether it gets returned.
87+
88+
89+
## See Also
90+
91+
* [What You Need to Use Telerik UI for Blazor]({%slug getting-started/what-you-need%})
92+
* [Get Started with Client-side Blazor]({%slug getting-started/client-side%})
93+
* [Get Started with Server-side Blazor]({%slug getting-started/server-side%})
94+

0 commit comments

Comments
 (0)