First Steps by Installing with the NuGet Package on Windows

NuGet is a popular .NET package manager. Progress maintains the Telerik NuGet Feed for registered users and you can include the Telerik UI for .NET MAUI suite in your project as well as update to the latest available version from there.

While installing Telerik UI for .NET MAUI with NuGet works both for Windows and MacOS machines, this tutorial describes how to get up and running with the library by downloading and installing the controls on Windows. Here is the step by step guide you have to follow:

The following video demonstrates how to register the feed on your system and add the product package you need by using Visual Studio for Windows.

The Telerik.UI.for.Maui NuGet package supports .NET 7.0, .NET 8.0, and .NET 9 Preview 6 or later projects, and automatically restores the required packages depending on the .NET version you are using in your project.

Step 1: Set Up Your .NET MAUI Project

Before you start with the installation of Telerik UI for .NET MAUI, make sure you have a running .NET MAUI application. For more information on the required steps and system requirements, refer to the Microsoft .NET MAUI official documentation.

Step 2: Download Telerik UI for .NET MAUI

Telerik UI for .NET MAUI enables you to download the suite either from the Telerik UI for .NET MAUI product page or through your Telerik account. For the purposes of this tutorial, let's download the batch from your Telerik account:

1. Log into your Telerik Account.

2. Click the Downloads tab.

   

3. Search for MAUI and select the Telerik UI for .NET MAUI product title.

   

4. On the next page, download the .nupkg or .zip files. The .zip file contains the Telerik .NET MAUI NuGet Package.

   

Step 3: Add the Telerik NuGet Package Source to Visual Studio

Now, let's add the Telerik UI for .NET MAUI package through the Telerik NuGet feed. To use the available packages, you need to have an active Telerik account and to authenticate.

1. In Visual Studio, select Tools > NuGet Package Manager > Package Manager Settings.

   

2. Select Package Sources.

   

3. In the Source field, add the Telerik server URL: https://nuget.telerik.com/v3/index.json. If you use a locally available NuGet package downloaded from your account, add the path to the local package instead of the URL. Finally, click Update.

   

The obsolete NuGet v2 server at https://nuget.telerik.com/nuget will be sunset in November 2024. To avoid any interruptions in your development process, change the NuGet server URL to https://nuget.telerik.com/v3/index.json.

The Telerik server is now ready to use. You can go to your solution and open the Solution Package Manager.

Step 4: Install the Telerik .NET MAUI NuGet Package

Now, you need to add the Telerik package to the .NET MAUI solution project that you created:

1. Select the Telerik NuGet server as a package source and enter your credentials when prompted.
2. Search for the Telerik.UI.for.Maui package and select it.
3. Choose the projects which require the package.
4. Select the desired version and click Install.

Step 5: Register the Required Handlers

To visualize the .NET MAUI controls, you have to register the required handlers by calling the Telerik.Maui.Controls.Compatibility.UseTelerik extension method inside the Configure method of the MauiProgram.cs file of your project.

1. Add the needed using settings inside the MauiProgram.cs file.

   using Telerik.Maui.Controls.Compatibility;
   

2. Call the UseTelerik() method inside the MauiProgram.cs file.

   public static class MauiProgram
   {
   public static MauiApp CreateMauiApp()
   {
       var builder = MauiApp.CreateBuilder();
       builder
           .UseTelerik()
           .UseMauiApp<App>()
           .ConfigureFonts(fonts =>
           {
               fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
           });
   
       return builder.Build();
   }
   }
   

   Next Steps

• Available Product Files and Assemblies
• Restoring NuGet Packages in Your CI Workflow
• Telerik UI for .NET MAUI Installation Approaches

Troubleshooting

This section lists some of the common problems that are observed during NuGet installation.

'401 Logon failed' error

If you're receiving this error when connecting to Telerik NuGet Server, you can try to update your NuGet credentials through the Windows Credential Manager. Please follow the steps below:

1. Close all open Visual Studio instances (this is so that all NuGet package manager tasks are stopped).
2. Open the "Credential Manager" app on your PC.
3. Scroll through all the entries until you find any that are for nuget.telerik.com.
4. Once you find that entry, expand it and select "edit".
5. Make sure the username and password are the same ones you use for your Telerik account and clisk
   1. Use the email address in the place of username
   2. Make sure any special characters are escaped (see Handling Special Characters in Password below)
   3. Click "Save"
6. Confirm the URL is correct:
   • The URL to the v3 server should be HTTPS and appear as https://nuget.telerik.com/v3/index.json
   • If you are still using the old v2 server, make sure the URL does not have a trailing slash. It must be only be https://nuget.telerik.com/nuget
7. Reopen Visual Studio and access the Telerik NuGet server.

Networking Problems

Another common problem is that your machine (PC or DevOps agent) is behind a proxy. To check if you're experiencing a networking issue, open the following URL in your web browser:

https://nuget.telerik.com/v3/search?q=maui

After you enter your telerik.com username and password, you should see a JSON search result containing a list of all the Telerik.UI.for.Maui packages available to the account you signed in with.

Unable to Load the Service Index for Source

The following error may occur if the nuget.telerik.com server is down.

Unable to load the service index for source https://nuget.telerik.com/v3/index.json

If you hit that error, make sure that the Telerik NuGet Feed is live at https://status.telerik.com/.

Handling Special Characters in Password

If your password contains a special character, those characters need to be escaped or it may fail authentication resulting in Error 401 login failure from the NuGet server. A common character that needs to be escaped is the ampersand &, but it can be as unique as the section character §. There are two ways to handle this.

1. Change the password so that it only includes characters that do not need to be escaped
2. HTML encode the password so the special characters are escaped (e.g. my§uper&P@§§word becomes my§uper&P@§§word).

We strongly discourage entering your password into an online encoder utility, use PowerShell instead. Here's one example:

    Add-Type -AssemblyName System.Web
    [System.Web.HttpUtility]::HtmlEncode('my§uper&P@§§word')

Result:

See Also

• System Requirements for Windows
• Telerik Toolbox for .NET MAUI on Windows
• Telerik Extensions and Project Templates for VS on Windows
• Telerik UI for .NET MAUI Product Page