From 3bd779f719e13cfd4879c660fc311eb36804ee8b Mon Sep 17 00:00:00 2001 From: Prince Oliver <31838171+PrinceOliver@users.noreply.github.com> Date: Wed, 7 Oct 2026 01:01:40 +0530 Subject: [PATCH 01/27] Move Syncfusion Blazor Toolkit install into dotnet-blazor. Correct render-mode, registration, theme, and license guidance from review, and tag the eval stimuli so the quality gate can slice results. --- .../SKILL.md | 153 ++++++++ .../references/package-identity.md | 48 +++ .../references/render-modes.md | 161 ++++++++ .../references/split-webapp-registration.md | 126 ++++++ .../references/theme-and-host-files.md | 84 ++++ .../references/troubleshooting.md | 285 ++++++++++++++ .../eval.yaml | 364 ++++++++++++++++++ 7 files changed, 1221 insertions(+) create mode 100644 plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md create mode 100644 plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md create mode 100644 plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md create mode 100644 plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md create mode 100644 plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md create mode 100644 plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md create mode 100644 tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md new file mode 100644 index 0000000000..5979757c5c --- /dev/null +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md @@ -0,0 +1,153 @@ +--- +name: syncfusion-blazor-toolkit-install +description: > + Install and register the open-source Syncfusion Blazor Toolkit package, + configure AddSyncfusionBlazorToolkit(), link the Fluent theme, and apply + the correct interactive render mode for your app topology (Server / WASM / Auto). + + USE FOR: Toolkit setup, package verification, theme linking, split-app registration, render-mode troubleshooting. + DO NOT USE FOR: component API details (use author-component), Blazor project creation (use create-blazor-project), + commercial Syncfusion packages or license keys, Hybrid/MAUI. +license: MIT +compatibility: ".NET 8+, Blazor Server / WebAssembly / Auto / Static SSR" +metadata: + author: "Syncfusion Inc" + version: "1.0.2" +--- + +# Install Syncfusion Blazor Toolkit + +## Core Rules + +1. Use the exact package ID `Syncfusion.Blazor.Toolkit`. +2. Call `AddSyncfusionBlazorToolkit()` in `Program.cs` before `builder.Build()`. +3. Import `@using Syncfusion.Blazor.Toolkit` in `_Imports.razor`; add component namespaces such as `@using Syncfusion.Blazor.Toolkit.Buttons` only when a component needs them. +4. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` in the app host file. +5. Use `@rendermode` for interactive Toolkit components in .NET 8+ Blazor Web App; legacy Blazor Server templates are already interactive (no `@rendermode` needed). +6. In split Blazor Web Apps, register Toolkit in every project that uses Toolkit components. +7. Never use commercial `Syncfusion.Blazor*` packages or license-key APIs for Toolkit. +8. Toolkit JavaScript is embedded in the Syncfusion NuGet package; do not add commercial script tags or `AddSyncfusionLicense()` calls. +9. Keep this skill install-focused; use the references for details and troubleshooting. + +## Don'ts + +- Don't treat `Syncfusion.Blazor` or component-specific commercial packages as Toolkit dependencies. +- Don't add external script tags or commercial Syncfusion license scripts; Toolkit JS is bundled with the package. +- Don't rely on static SSR when the component must respond to clicks, binding, or dynamic updates. +- Don't use this skill as a component API reference; consult the official Syncfusion Blazor Toolkit demos or documentation for API details. + +## Quick Decision Table + +| Scenario | Package | Program.cs | Host file for CSS | Interactivity | +| --- | --- | --- | --- | --- | +| Blazor Server (legacy _Host.cshtml) | `Syncfusion.Blazor.Toolkit` | `builder.Services.AddSyncfusionBlazorToolkit()` | `_Host.cshtml` | Interactive by default (no `@rendermode` directive) | +| Blazor WebAssembly (standalone) | `Syncfusion.Blazor.Toolkit` | `builder.Services.AddSyncfusionBlazorToolkit()` | `wwwroot/index.html` | Interactive by default (no `@rendermode` directive) | +| Blazor Web App (Auto) | `Syncfusion.Blazor.Toolkit` | Register in Server and Client projects that use Toolkit | `App.razor` | `@rendermode InteractiveAuto` | +| Blazor Web App (Split Server/Client) | `Syncfusion.Blazor.Toolkit` | Register in Server and Client projects that use Toolkit | `App.razor` | `@rendermode InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto` | +| Static SSR only | `Syncfusion.Blazor.Toolkit` | Register services as needed | `App.razor` or `index.html` | None; read-only only | + +## Minimal Setup + +### Package + +```bash +dotnet add package Syncfusion.Blazor.Toolkit +``` + +### Program.cs + +Match the render modes from the Quick Decision Table above. Do not add unused render modes. + +**For Blazor Web App (Auto or Server+Client split)**: +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents() + .AddInteractiveWebAssemblyComponents(); + +builder.Services.AddSyncfusionBlazorToolkit(); + +var app = builder.Build(); + +app.MapRazorComponents() + .AddInteractiveServerRenderMode() + .AddInteractiveWebAssemblyRenderMode(); +``` + +**For .NET 8+ Blazor Web App (server-only mode)**: +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents(); + +builder.Services.AddSyncfusionBlazorToolkit(); + +var app = builder.Build(); + +app.MapRazorComponents() + .AddInteractiveServerRenderMode(); +``` + +**For Blazor WebAssembly**: +```csharp +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +builder.RootComponents.Add("#app"); + +builder.Services.AddSyncfusionBlazorToolkit(); + +await builder.Build().RunAsync(); +``` + +### _Imports.razor + +```razor +@using Syncfusion.Blazor.Toolkit + +@* Optional: Add component-specific namespaces only when using those components *@ +@* @using Syncfusion.Blazor.Toolkit.Buttons *@ +@* @using Syncfusion.Blazor.Toolkit.Calendars *@ +``` + +For component-specific features, uncomment and include the appropriate namespace in `_Imports.razor` as needed. + +### Host file CSS + +```html + +``` + +Always pick the host file from the Quick Decision Table above: `_Host.cshtml` for legacy Blazor Server, `App.razor` for Blazor Web App, or `wwwroot/index.html` for Blazor WebAssembly. + +## Common Mistakes + +| Mistake | Symptom | Fix | +| --- | --- | --- | +| CSS path uses `themes/` instead of `styles/` | Components are unstyled (404 in browser DevTools) | Change `_content/Syncfusion.Blazor.Toolkit/themes/fluent.css` to `.../styles/fluent.min.css` | +| CSS linked in a component file instead of host file | Styling doesn't apply consistently | Move `` tag to the host file's `` section | +| Using commercial `Syncfusion.Blazor` package | License key errors, missing components | Remove commercial package; use only `Syncfusion.Blazor.Toolkit` | +| Added external Syncfusion CDN script tag | JavaScript conflicts or duplicate library errors | Remove external CDN script; Toolkit JS is bundled in the NuGet package | +| Missing `@rendermode` on interactive components | Components don't respond to clicks/binding | Add `@rendermode InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto` | +| Static SSR with interactive components | Buttons and inputs don't work | Switch to an interactive render mode (see Quick Decision Table) | + +## Top Failure Symptoms + +- **Unstyled components**: the Fluent CSS link is missing, wrong, or placed in the wrong host file. See [Theme and host files](./references/theme-and-host-files.md). +- **Services not configured**: `AddSyncfusionBlazorToolkit()` is missing from `Program.cs`. See [Troubleshooting guide](./references/troubleshooting.md). +- **Clicks or inputs do nothing**: the page is using static SSR. Add `@rendermode InteractiveServer`, `@rendermode InteractiveWebAssembly`, or `@rendermode InteractiveAuto`. See [Render modes explained](./references/render-modes.md). +- **Only one half of a split app works**: register Toolkit in both Server and Client if both use Toolkit. See [Split Blazor Web App registration](./references/split-webapp-registration.md). +- **Wrong package or license guidance**: the project uses a commercial `Syncfusion.Blazor*` package instead of the Toolkit. See [Package identity and splits](./references/package-identity.md). + +## Next Steps + +After installation, use the component demos or component-specific guidance for API details; this skill only covers setup and configuration. + +## References + +- [Package identity and splits](./references/package-identity.md) +- [Split Blazor Web App registration](./references/split-webapp-registration.md) +- [Theme and host files](./references/theme-and-host-files.md) +- [Render modes explained](./references/render-modes.md) +- [Troubleshooting guide](./references/troubleshooting.md) \ No newline at end of file diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md new file mode 100644 index 0000000000..4f3a800c8d --- /dev/null +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md @@ -0,0 +1,48 @@ +# Install Syncfusion Blazor Toolkit + +## Package Identity Reference + +### Syncfusion.Blazor.Toolkit vs. Commercial Syncfusion.Blazor* + +### The Open-Source Toolkit: Syncfusion.Blazor.Toolkit + +- **NuGet package name**: `Syncfusion.Blazor.Toolkit` +- **License**: MIT +- **Scope**: Open-source Blazor toolkit for the current published component set +- **Repository**: Official Syncfusion GitHub repository +- **Components included**: Refer to the official Syncfusion Blazor Toolkit documentation for the authoritative and current component list. This skill is not a component reference. +- **No license key required**: Toolkit is free to use without registration + +### Commercial Syncfusion.Blazor* Packages + +- **Package name(s)**: `Syncfusion.Blazor`, `Syncfusion.Blazor.Core`, `Syncfusion.Blazor.Buttons`, `Syncfusion.Blazor.Calendars`, `Syncfusion.Blazor.Charts`, `Syncfusion.Blazor.Grids`, `Syncfusion.Blazor.Inputs`, etc. +- **License**: Commercial (requires valid license key for production) +- **Scope**: Full-featured Syncfusion component library +- **Requires**: License-key registration via `AddSyncfusionLicense()` (or similar) +- **Not the same as Toolkit**: Commercial packages are separate products with different APIs and licensing + +## Install the Toolkit (and ONLY the Toolkit for this skill) + +```bash +# Correct: Install Toolkit +dotnet add package Syncfusion.Blazor.Toolkit + +# Wrong: Do NOT install commercial packages for Toolkit tasks +dotnet add package Syncfusion.Blazor +dotnet add package Syncfusion.Blazor.Core +dotnet add package Syncfusion.Blazor.Buttons +``` + +## Verify Installation + +Check the `.csproj` file: + +```xml + + + + + + + +``` diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md new file mode 100644 index 0000000000..00bc2f9225 --- /dev/null +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md @@ -0,0 +1,161 @@ +# Render Modes Reference + +Blazor supports multiple render modes. Toolkit components need an interactive mode whenever they handle clicks, binding, or other live updates. + +## Static SSR (Server-Side Rendering) + +**When to use**: Read-only content where no user interaction or dynamic updates are needed. + +**Characteristic**: Components are rendered on the server and sent as HTML; no .NET code runs on the client. + +**Toolkit limitation**: **Static SSR is not sufficient for interactive Toolkit components** (buttons, forms, dropdowns, etc.). Event handlers and state changes will not work. + +**Example (read-only only)**: +```razor +@page "/counter" + +

This counter is stuck at: @count

+Click doesn't work in SSR + +@code { + private int count = 0; + // @onclick handlers don't fire in static SSR +} +``` + +## Interactive Server Rendering + +**When to use**: Interactive components hosted on a Blazor Server app or on the Server side of a Blazor Web App. + +**Characteristic**: User interactions are sent to the server, processed, and updates stream back to the client in real time. + +**Toolkit requirement**: Fully supported; all event handlers and state changes work. + +**Example**: +```razor +@page "/counter" +@rendermode InteractiveServer + +

Count: @count

+Increment + +@code { + private int count = 0; + private void IncrementCount() => count++; +} +``` + +**Current template setup**: +```csharp +// Program.cs +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents() + .AddInteractiveWebAssemblyComponents(); + +builder.Services.AddSyncfusionBlazorToolkit(); + +var app = builder.Build(); + +app.MapRazorComponents() + .AddInteractiveServerRenderMode() + .AddInteractiveWebAssemblyRenderMode(); +``` + +## Interactive WebAssembly Rendering + +**When to use**: Interactive components running as WebAssembly on the client (standalone Blazor WebAssembly or the Client project in a Blazor Web App). + +**Characteristic**: .NET runs in the browser; no server round-trip for user interactions after load. + +**Toolkit requirement**: Fully supported; all event handlers and state changes work. + +**Example**: +```razor +@page "/counter" +@rendermode InteractiveWebAssembly + +

Count: @count

+Increment + +@code { + private int count = 0; + private void IncrementCount() => count++; +} +``` + +**Setup**: +```csharp +// Program.cs (standalone WASM or .Client project) +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +builder.RootComponents.Add("#app"); + +builder.Services.AddSyncfusionBlazorToolkit(); + +await builder.Build().RunAsync(); +``` + +## Interactive Auto Rendering + +**When to use**: Blazor Web App projects that should start on the server and then continue running in the browser when available. + +**Characteristic**: The app can begin with server interactivity and transition to client-side WebAssembly for later interactions. + +**Toolkit requirement**: Fully supported; all event handlers and state changes work. + +**Example**: +```razor +@page "/counter" +@rendermode InteractiveAuto + +

Count: @count

+Increment + +@code { + private int count = 0; + private void IncrementCount() => count++; +} +``` + +**Setup**: +```csharp +// Program.cs +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents() + .AddInteractiveWebAssemblyComponents(); + +builder.Services.AddSyncfusionBlazorToolkit(); + +var app = builder.Build(); + +app.MapRazorComponents() + .AddInteractiveServerRenderMode() + .AddInteractiveWebAssemblyRenderMode(); +``` + +## Decision Tree + +1. **Does the component need to respond to user clicks or changes?** + - **No** → Static SSR is fine (no render mode needed) + - **Yes** → Go to question 2 + +2. **Should processing happen on the server, in the browser, or both?** + - **Server** → Use `@rendermode InteractiveServer` + - **Browser (WASM)** → Use `@rendermode InteractiveWebAssembly` + - **Start on server, continue in browser** → Use `@rendermode InteractiveAuto` + +3. **Toolkit component won't respond?** + - **Symptom**: Click or input events don't work + - **Solution**: Ensure the component or page has an interactive render mode applied + +## Common Mistakes + +1. **Forgetting `@rendermode`**: Interactive components in a static page won't respond to clicks. +2. **Using static SSR for interactive components**: Toolkit components require interactive mode for event handling. +3. **Mismatched render mode**: Trying to use `InteractiveServer` in a WebAssembly-only app won't work. +4. **Ignoring `InteractiveAuto`**: Auto is a first-class render mode for current Blazor Web App templates. +5. **Assuming automatic**: Render mode doesn't "just work"; it must be explicitly declared. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md new file mode 100644 index 0000000000..3fd08bcf3e --- /dev/null +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md @@ -0,0 +1,126 @@ +# Split Blazor Web App Service Registration + +When using a split Blazor Web App, register Toolkit services in every project that actually renders Toolkit components. + +## Current template note + +For `dotnet new blazor -int Auto` and `dotnet new blazor -int WebAssembly`, the generated Server project typically wires interactive server and WebAssembly support in `Program.cs`, while the `.Client` project is the browser-side app. Keep Toolkit registration in whichever project uses Toolkit components. + +## Scenario 1: Only Server uses Toolkit + +**Server/Program.cs**: +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents(); + +builder.Services.AddSyncfusionBlazorToolkit(); // Server-side registration + +var app = builder.Build(); + +app.MapRazorComponents() + .AddInteractiveServerRenderMode(); +``` + +**Client/Program.cs**: +```csharp +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +builder.RootComponents.Add("#app"); + +// No Toolkit registration needed if Client doesn't use Toolkit +await builder.Build().RunAsync(); +``` + +## Scenario 2: Only Client uses Toolkit + +**Server/Program.cs**: +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents(); +// No Toolkit registration; Server doesn't use it + +var app = builder.Build(); + +app.MapRazorComponents() + .AddInteractiveServerRenderMode(); +``` + +**Client/Program.cs**: +```csharp +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +builder.RootComponents.Add("#app"); + +builder.Services.AddSyncfusionBlazorToolkit(); // Client-side registration + +await builder.Build().RunAsync(); +``` + +## Scenario 3: Both Server and Client use Toolkit (MOST COMMON) + +**Server/Program.cs**: +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents() + .AddInteractiveWebAssemblyComponents(); + +builder.Services.AddSyncfusionBlazorToolkit(); // Register here + +var app = builder.Build(); + +app.MapRazorComponents() + .AddInteractiveServerRenderMode() + .AddInteractiveWebAssemblyRenderMode(); +``` + +**Client/Program.cs**: +```csharp +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +builder.RootComponents.Add("#app"); + +builder.Services.AddSyncfusionBlazorToolkit(); // Also register here + +await builder.Build().RunAsync(); +``` + +## Scenario 4: Auto render mode uses Toolkit on both sides + +If you use `@rendermode InteractiveAuto`, keep Toolkit registration in both Server and Client when both halves render Toolkit components. + +## Common Mistake: Forgetting Client Registration + +If Toolkit components are used in the Client project but `AddSyncfusionBlazorToolkit()` is only called in Server `Program.cs`, the Client will not have access to Toolkit services and components will fail. + +**Symptom**: Components work in Server-hosted components but fail in Client components. + +**Solution**: Ensure both projects have the registration call if both use Toolkit. + +## Theme CSS in Split Web App + +Theme CSS should be linked in the shared `App.razor` host file so both Server and Client components can use it: + +```razor + + + + + + + + + + + + + + +``` + +This ensures the theme is available to both Server and Client components. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md new file mode 100644 index 0000000000..96bc48a443 --- /dev/null +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md @@ -0,0 +1,84 @@ +# Theme and Host Files Reference + +Toolkit components require CSS theming. Use the host file for your app type and link the Fluent stylesheet there. + +## Blazor Web App / Modern Blazor Server + +**Host file**: `App.razor` + +**Theme**: Syncfusion Blazor Toolkit supports **Fluent theme only**. + +**Example**: +```razor + + + + + + + + + + + + + + +``` + +**Legacy Blazor Server note**: If you are on an older Server template, `_Host.cshtml` may still be the host file and `blazor.server.js` may still appear there. Prefer `App.razor` and `blazor.web.js` for current Blazor Web App templates. + +## Blazor WebAssembly + +**Host file**: `index.html` (in the `wwwroot` folder) + +**Theme**: Syncfusion Blazor Toolkit supports **Fluent theme only**. + +**Example**: +```html + + + + + + MyApp + + + + + +
+ + + +``` + +## Available Themes + +Syncfusion Blazor Toolkit supports **only the Fluent theme**: + +- `fluent.min.css` — Microsoft Fluent Design theme (the only supported theme) — use this for the common stylesheet +- Individual component stylesheets: `button.min.css`, `calendar.min.css`, `chart.min.css`, `checkbox.min.css`, `dialog.min.css`, `dropdown.min.css`, `input.min.css`, `spinner.min.css`, `textbox.min.css`, `tooltip.min.css`, etc. + +Do not attempt to use other theme CSS files (bootstrap5, tailwind, material, etc.) with the Toolkit; they are not supported and will not work correctly. + +## Local References + +Use the local reference: +```html + +``` + +Local references are preferred because they: +- Avoid external dependencies +- Work offline +- Are bundled with your application + +## Common Mistakes + +1. **Linking in the wrong file**: Link the theme in the app's host file (`App.razor` for Blazor Web App / modern Blazor Server; `wwwroot/index.html` for Blazor WebAssembly). +2. **Wrong path directory**: Ensure the path is `_content/Syncfusion.Blazor.Toolkit/styles/` exactly (note: `styles/`, not `themes/`). +3. **Wrong theme name**: Using `bootstrap5.min.css`, `tailwind.min.css`, `material.min.css`, or other non-Fluent themes won't work. Toolkit supports **only `fluent.min.css`**. +4. **Missing .min extension**: Ensure you use `.min.css` (not just `.css`). The correct filename is `fluent.min.css`. +5. **Missing link entirely**: Without the theme, components render unstyled and may be hard to see. +6. **Individual stylesheet only**: If you link only individual component stylesheets (e.g., just `button.min.css`), components not included will be unstyled. Use `fluent.min.css` for all components unless performance optimization is needed. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md new file mode 100644 index 0000000000..4666c71c23 --- /dev/null +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md @@ -0,0 +1,285 @@ +# Troubleshooting Toolkit Installation + +## Problem: Theme CSS not loading (404) or components unstyled + +**Symptoms**: +- Components appear in the page but have no colors, borders, or styling +- DevTools Network tab shows the CSS file returns 404 (not found) +- Or the file returns 200 but components still appear unstyled + +**Root cause**: Theme CSS link is missing, using the wrong path, wrong filename, wrong theme name, or linked in the wrong host file. + +**Diagnosis**: +1. Check the correct host file for your project type: + - Blazor Web App / modern Blazor Server: `App.razor` + - Legacy Blazor Server: `_Host.cshtml` + - Blazor WebAssembly: `wwwroot/index.html` +2. Look for the CSS link in the `` section: + ```html + + ``` +3. If found, verify: + - Path is **exactly** `_content/Syncfusion.Blazor.Toolkit/styles/` (not `themes/`) + - Filename is **exactly** `fluent.min.css` (Toolkit only supports Fluent; no Bootstrap, Tailwind, or Material) + - No typos; `.min` extension is required +4. If missing, add it to the `` section +5. Open browser DevTools (F12) Network tab and verify the CSS file loads with status 200 (not 404) + +**Common mistakes**: +- Wrong path: `_content/Syncfusion.Blazor.Toolkit/themes/fluent.min.css` (should be `styles/`) +- Wrong theme name: `bootstrap5.min.css`, `tailwind.min.css`, `material.min.css` (must be `fluent.min.css`) +- Missing `.min` extension: `fluent.css` (should be `.min.css`) +- Linked in wrong host file: use `App.razor` for Blazor Web App/Server or `wwwroot/index.html` for WebAssembly +- Linked in a component file instead of the host file (always place it in the host file's `` section for best results) + +**Fix**: +```html + + +``` + +--- + +## Problem: Services not configured + +**Symptoms**: +- Runtime error when component tries to use Toolkit services +- Error message mentions missing or null service + +**Root cause**: `AddSyncfusionBlazorToolkit()` is not called in `Program.cs`. + +**Diagnosis**: +1. Open `Program.cs` (or the Server/Client `Program.cs` in split Web Apps) +2. Look for: + ```csharp + builder.Services.AddSyncfusionBlazorToolkit(); + ``` +3. If missing, add it before `builder.Build()`. + +**Fix**: +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRazorComponents(); +builder.Services.AddSyncfusionBlazorToolkit(); // <-- Add this + +var app = builder.Build(); +``` + +--- + +## Problem: Click events or form inputs don't work + +**Symptoms**: +- Toolkit component is visible and styled correctly +- Clicking buttons or entering text in forms has no effect +- No errors in the browser console + +**Root cause**: Component is rendered in static SSR mode; interactive render mode is not applied. + +**Diagnosis**: +1. Check the component or page definition: + - Look for `@rendermode InteractiveServer` or `@rendermode InteractiveWebAssembly` + - If missing, the component is static +2. Confirm the interaction type (Server or WebAssembly) + +**Fix**: +```razor +@page "/mypage" +@* Add this line *@ +@rendermode InteractiveServer + +Click me + +@code { + private void OnClick() + { + Console.WriteLine("Clicked!"); + } +} +``` + +Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int WebAssembly`): +```razor +@page "/mypage" +@rendermode InteractiveWebAssembly + +Click me + +@code { + private void OnClick() + { + Console.WriteLine("Clicked!"); + } +} +``` + +--- + +## Problem: `Syncfusion.Blazor.Toolkit` namespace not found + +**Symptoms**: +- Compilation error: "The type or namespace name 'Syncfusion' could not be found" +- IntelliSense doesn't show Toolkit types + +**Root cause**: The NuGet package is not installed, or namespaces are not imported. + +**Diagnosis**: +1. Check the `.csproj` file for: + ```xml + + ``` +2. If missing, install the package. +3. Check `_Imports.razor` (or component file) for: + ```razor + @using Syncfusion.Blazor.Toolkit + ``` +4. If missing, add the namespace import. + +**Fix**: +1. Install the package: + ```bash + dotnet add package Syncfusion.Blazor.Toolkit + ``` +2. Add to `_Imports.razor`: + ```razor + @using Syncfusion.Blazor.Toolkit + ``` + +--- + +## Problem: Split Web App: components work in Server but not in Client + +**Symptoms**: +- Toolkit components work fine in Server-side pages +- Same components in Client pages fail or don't render + +**Root cause**: `AddSyncfusionBlazorToolkit()` is registered in Server `Program.cs` but not in Client `Program.cs`. + +**Diagnosis**: +1. Check both `Program.cs` files (Server and Client) +2. Look for `AddSyncfusionBlazorToolkit()` in each +3. If only one has it, the other is missing registration + +**Fix**: +- **Server/Program.cs**: + ```csharp + builder.Services.AddSyncfusionBlazorToolkit(); + ``` +- **Client/Program.cs**: + ```csharp + builder.Services.AddSyncfusionBlazorToolkit(); + ``` + +Also ensure both projects have the NuGet package reference in their `.csproj` files and both have namespace imports in their `_Imports.razor` files. + +--- + +## Problem: Wrong package installed (commercial Syncfusion instead of Toolkit) + +**Symptoms**: +- You see `Syncfusion.Blazor` or `Syncfusion.Blazor.Buttons` in the `.csproj` instead of `Syncfusion.Blazor.Toolkit` +- Code references license keys or methods like `AddSyncfusionLicense()` +- Components work but you're on a commercial license + +**Root cause**: The commercial Syncfusion.Blazor package was installed instead of the open-source Toolkit. + +**Diagnosis**: +1. Check the `.csproj` file: + ```xml + + + + + + ``` +2. Check `Program.cs` for license-key setup. + +**Fix**: +1. Uninstall the commercial package: + ```bash + dotnet remove package Syncfusion.Blazor + ``` +2. Install the Toolkit: + ```bash + dotnet add package Syncfusion.Blazor.Toolkit + ``` +3. Remove any license-key registration code. +4. Add `AddSyncfusionBlazorToolkit()` instead. + +--- + +## Problem: JavaScript errors in browser console + +**Symptoms**: +- Browser DevTools Console shows JavaScript errors related to Toolkit or Syncfusion +- Components may not respond or may crash +- Errors mention "script", "undefined", or Syncfusion library functions + +**Root cause**: Toolkit JavaScript is not loading correctly, or there's a conflict with browser scripts. + +**Diagnosis**: +1. Open browser DevTools (F12) and check the Console tab +2. Look for errors that mention Syncfusion, Toolkit, or JS loading +3. Check the Network tab to verify JavaScript files are loading (look for `_content/` files) +4. If 404 errors appear, the package may not be installed correctly +5. If "undefined" errors appear, services may not be registered or JS is loading before services + +**Fix**: +1. Ensure `AddSyncfusionBlazorToolkit()` is called in `Program.cs` before any components render +2. Verify the package is installed: `dotnet list package` and check if `Syncfusion.Blazor.Toolkit` is listed +3. Clear browser cache (Ctrl+Shift+Delete) and reload +4. Rebuild and republish: `dotnet build` and `dotnet publish` +5. Check that no other scripts are conflicting (disable extensions, try incognito mode) + +--- + +## Problem: Script fails to load during component initialization + +**Symptoms**: +- Console shows errors like "Uncaught ReferenceError" or "undefined" when component renders +- Components appear briefly then disappear or show errors +- Toolkit JavaScript functions are not available + +**Root cause**: Toolkit script files are not loading correctly, or services are not registered before components attempt to use them. + +**Diagnosis**: +1. Open browser DevTools (F12) Network tab +2. Look for files in `_content/Syncfusion.Blazor.Toolkit/` directory +3. Check if any show 404 status (not found) +4. Verify `AddSyncfusionBlazorToolkit()` is registered **before** `builder.Build()` in `Program.cs` +5. Check if any page/component is rendering before services are initialized + +**Fix**: +1. Ensure service registration is early in `Program.cs`: + ```csharp + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddRazorComponents() + .AddInteractiveServerComponents(); + builder.Services.AddSyncfusionBlazorToolkit(); // <-- Must be before Build() + var app = builder.Build(); + ``` +2. Rebuild and clear cache: + ```bash + dotnet clean + dotnet build + ``` +3. Clear browser cache (Ctrl+Shift+Delete) and reload (Ctrl+F5) +4. For split Web App, ensure **both** Server and Client `Program.cs` files have the registration +5. Verify the package is installed: `dotnet list package` and check if `Syncfusion.Blazor.Toolkit` is listed + +--- + +## General Checklist + +Before troubleshooting further, verify: + +1. ✓ Package name is `Syncfusion.Blazor.Toolkit` (not commercial packages) +2. ✓ `AddSyncfusionBlazorToolkit()` is in `Program.cs` (both in split Web Apps) +3. ✓ `@using Syncfusion.Blazor.Toolkit` is in `_Imports.razor` (both in split Web Apps) +4. ✓ Theme CSS link is `fluent.min.css` in the correct host file (`App.razor` for Blazor Server/Web App or `wwwroot/index.html` for Blazor WebAssembly) +5. ✓ Theme filename is exactly `fluent.min.css` (not other theme names) +6. ✓ Interactive components have `@rendermode InteractiveServer`, `@rendermode InteractiveWebAssembly`, or `@rendermode InteractiveAuto` +7. ✓ No license-key registration code is present +8. ✓ Build completes without errors: `dotnet build` +9. ✓ Browser console shows no 404 or JavaScript errors diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml new file mode 100644 index 0000000000..2ba4e4be35 --- /dev/null +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -0,0 +1,364 @@ +name: syncfusion-blazor-toolkit-install +description: Evaluates the Syncfusion Blazor Toolkit installation and configuration skill. +type: capability +defaults: + timeout: 20m + +stimuli: + - name: server-install-success + prompt: | + I'm setting up a new Blazor Server project. I want to install the Syncfusion Blazor Toolkit. + What are the steps I need to follow to get it working? + graders: + - type: output-matches + config: + pattern: (?i)Syncfusion\.Blazor\.Toolkit + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)_Imports\.razor + - type: output-matches + config: + pattern: (?i)fluent\.min\.css|_content/Syncfusion\.Blazor\.Toolkit/styles/ + - type: output-matches + config: + pattern: (?i)(App\.razor|_Host\.cshtml) + - type: output-not-contains + config: + substring: Syncfusion.Blazor.Buttons + - type: output-not-matches + config: + pattern: (?i)(enter|add|register|provide)[\s\S]*(license key) + - type: output-not-contains + config: + substring: AddSyncfusionLicense + rubric: + - Recommends the exact Toolkit package name and not commercial component packages. + - Documents service registration, namespace imports, and theme CSS linking. + - Uses the correct Fluent stylesheet path and avoids license-key guidance. + + - name: webassembly-install-success + prompt: | + I'm building a Blazor WebAssembly application and want to add the Syncfusion Blazor Toolkit. + Can you guide me through installation and setup? + graders: + - type: output-matches + config: + pattern: (?i)Syncfusion\.Blazor\.Toolkit + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)(wwwroot/)?index\.html + - type: output-matches + config: + pattern: (?i)@using\s+Syncfusion\.Blazor\.Toolkit + - type: output-not-matches + config: + pattern: (?i)(enter|add|register|provide)[\s\S]*(license key) + rubric: + - Explains that WebAssembly uses index.html as the host file for the theme link. + - Includes the Toolkit package, service registration, and namespace imports. + - Avoids suggesting App.razor as the WASM host file. + + - name: split-webapp-registration + prompt: | + We have a split Blazor Web App with Server and Client projects. Both Server and Client + components need to use the Syncfusion Blazor Toolkit. What configuration is required? + graders: + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)Server + - type: output-matches + config: + pattern: (?i)Client + - type: output-matches + config: + pattern: (?i)both + rubric: + - States that both Server and Client Program.cs files need registration when both halves use Toolkit. + - Distinguishes split Web App registration from single-project setups. + + - name: missing-theme-css-failure + prompt: | + I've installed the Syncfusion Blazor Toolkit and added AddSyncfusionBlazorToolkit() + to Program.cs, but my components render without any styling—they look plain and basic. + The components are there, but no colors or borders. What's wrong? + graders: + - type: output-matches + config: + pattern: (?i)theme CSS|theme css + - type: output-matches + config: + pattern: (?i)link + - type: output-matches + config: + pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/ + - type: output-matches + config: + pattern: (?i)App\.razor|index\.html|wwwroot/index\.html + - type: output-not-contains + config: + substring: install a different package + - type: output-not-contains + config: + substring: buy a commercial license + rubric: + - Diagnoses missing or incorrect theme CSS as the cause of unstyled components. + - Points to the correct Fluent stylesheet path and host file for the project type. + + - name: static-ssr-insufficient + prompt: | + I have a Blazor Web App with a SfButton component from the Syncfusion Blazor Toolkit. + When I click the button, nothing happens. The component is visible and styled correctly, + but events don't fire. What's the issue? + graders: + - type: output-matches + config: + pattern: (?i)@rendermode + - type: output-matches + config: + pattern: (?i)InteractiveServer + - type: output-matches + config: + pattern: (?i)InteractiveWebAssembly + - type: output-matches + config: + pattern: (?i)static + - type: output-not-contains + config: + substring: static SSR is sufficient + - type: output-not-contains + config: + substring: downgrade the package + rubric: + - Explains that static SSR alone is insufficient for interactive Toolkit components. + - Recommends an interactive render mode such as InteractiveServer or InteractiveWebAssembly. + + - name: interactive-auto-success + prompt: | + I created the app with dotnet new blazor -int Auto. I want Toolkit components to start on + the server and continue working in the browser when available. What render mode should I use, + and what setup does the current template need? + graders: + - type: output-matches + config: + pattern: (?i)InteractiveAuto + - type: output-matches + config: + pattern: (?i)AddInteractiveServerComponents + - type: output-matches + config: + pattern: (?i)AddInteractiveWebAssemblyComponents + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)App\.razor + - type: output-not-contains + config: + substring: static SSR is enough + rubric: + - Recommends InteractiveAuto for the current Blazor Web App template. + - Mentions the server-side interactive setup used by the current template. + - Keeps Toolkit registration aligned with the projects that render Toolkit components. + + - name: wrong-commercial-package + prompt: | + I ran `dotnet add package Syncfusion.Blazor` and now I'm seeing references to AddSyncfusionLicense() + and license keys. I need to use the open-source Toolkit for a hobby project. Did I install the + wrong package? + graders: + - type: output-matches + config: + pattern: (?i)Syncfusion\.Blazor\.Toolkit + - type: output-matches + config: + pattern: (?i)Syncfusion\.Blazor + - type: output-matches + config: + pattern: (?i)remove + - type: output-matches + config: + pattern: (?i)dotnet remove package + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-not-matches + config: + pattern: (?i)(enter|add|register|provide)[\s\S]*(license key) + rubric: + - Identifies the commercial package as wrong for Toolkit scenarios and recommends removing it. + - Replaces licensing guidance with the Toolkit service registration method. + + - name: split-app-partial-registration-failure + prompt: | + I have a split Blazor Web App. I added the Syncfusion Blazor Toolkit package and registered + it with AddSyncfusionBlazorToolkit() in the Server Program.cs. My Server components work fine, + but Client components throw errors. Both halves need Toolkit. What's missing? + graders: + - type: output-matches + config: + pattern: (?i)Client Program\.cs|Client.*Program\.cs + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)both + - type: output-not-contains + config: + substring: only Server needs registration + rubric: + - Explains that Client registration is also needed when the Client project uses Toolkit components. + - Mentions registering Toolkit in both Server and Client Program.cs files. + + - name: script-failure-or-js-error + prompt: | + I installed Syncfusion Blazor Toolkit and configured everything, but now the browser console + shows JavaScript errors like "undefined is not a function" related to Syncfusion. The components + are on the page but they don't respond to clicks. What's wrong? + graders: + - type: output-matches + config: + pattern: (?i)JavaScript + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)Program\.cs + - type: output-matches + config: + pattern: (?i)browser console + - type: output-matches + config: + pattern: (?i)clear cache + - type: output-not-contains + config: + substring: different package + - type: output-not-contains + config: + substring: downgrade + rubric: + - Diagnoses a JavaScript loading or service-registration issue rather than a package-version issue. + - Advises checking the browser console, Program.cs, and clearing cache or rebuilding. + + - name: wrong-theme-name-failure + prompt: | + I linked the Syncfusion Blazor Toolkit theme CSS in my App.razor like this: + + + The components render but they're completely unstyled. Browser DevTools shows no 404 errors on the CSS. + What's the issue? + graders: + - type: output-matches + config: + pattern: (?i)fluent + - type: output-matches + config: + pattern: (?i)fluent\.min\.css + rubric: + - Identifies Fluent as the only supported theme and points to fluent.min.css. + + - name: wrong-stylesheet-path-failure + prompt: | + I'm getting 404 errors for the Toolkit theme CSS file. I'm using this path: + + + The browser DevTools Network tab shows a 404. What's the correct path? + graders: + - type: output-matches + config: + pattern: (?i)styles + - type: output-matches + config: + pattern: (?i)fluent\.min\.css + - type: output-matches + config: + pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/ + rubric: + - Gives the exact correct path under the styles directory. + + - name: script-file-loading-failure + prompt: | + I've installed the Syncfusion Blazor Toolkit and added all the configuration. The browser + DevTools shows JavaScript errors like "Cannot read property of undefined" when I interact + with components. I can see 404 errors in the Network tab for files in _content/Syncfusion.Blazor.Toolkit/. + What's the issue? + graders: + - type: output-matches + config: + pattern: (?i)script + - type: output-matches + config: + pattern: _content + - type: output-matches + config: + pattern: (?i)AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)Program\.cs + - type: output-matches + config: + pattern: (?i)clean + - type: output-matches + config: + pattern: (?i)package + - type: output-not-contains + config: + substring: wrong package + - type: output-not-contains + config: + substring: material.css + - type: output-matches + config: + pattern: (?i)(fluent\s+theme\s+only|only\s+(the\s+)?fluent) + rubric: + - Treats the issue as a script-loading/configuration problem with static asset 404s. + - Reinforces that Toolkit supports only the Fluent theme and that the package should be verified. + + - name: commercial-script-tags-wrong + prompt: | + I'm setting up the Syncfusion Blazor Toolkit. I added the NuGet package, registered it in Program.cs, + but then I also added the commercial Syncfusion script tag from the CDN. Now I'm getting errors about + conflicts or duplicate library loading. Should I be using external script tags? + graders: + - type: output-matches + config: + pattern: (?i)Syncfusion\.Blazor\.Toolkit + - type: output-matches + config: + pattern: (?i)(embedded|bundled|included|do not add|no external|no CDN) + rubric: + - Identifies that the Toolkit package includes all necessary JavaScript; external script tags are not needed. + - Explains that Toolkit JS is embedded in the NuGet package and requires no external CDN or license scripts. + - Recommends removing external Syncfusion script tags added to the host file. + + - name: out-of-scope-component-api + prompt: | + I'm building a chart dashboard with the Syncfusion Blazor Toolkit. How do I configure + the series collection for a line chart? What are the available series types? + expect_activation: false + graders: + - type: prompt + config: + prompt: | + Did the skill correctly decline this component API question and redirect to installation/configuration scope? + The model should not answer chart-series API or series-collection details. + Accept if the model declines, explains the skill scope, or redirects to official component docs. + Reject if it answers the API question directly or provides series configuration code. + - type: output-matches + config: + pattern: (?i)(out of scope|not cover|component API|installation) + rubric: + - Declines or redirects because the question is about component API rather than installation/configuration. + - Anti-hijack: do not answer the chart-series API question; keep the response on installation/configuration only. + - Stays dormant on chart-series API details and does not answer the out-of-scope request. \ No newline at end of file From f0216b2056932a8d6e5ebc03966d90f9c948f79f Mon Sep 17 00:00:00 2001 From: Prince Oliver <31838171+PrinceOliver@users.noreply.github.com> Date: Wed, 7 Oct 2026 01:01:45 +0530 Subject: [PATCH 02/27] Correct Toolkit install guidance and eval graders. Distinguish standalone WASM from a Web App Client project, keep prerendered registration on the server, and stop graders from rejecting valid negated answers. --- .agents/plugins/marketplace.json | 2 +- .claude-plugin/marketplace.json | 2 +- .cursor-plugin/marketplace.json | 2 +- .github/CODEOWNERS | 4 + .github/plugin/marketplace.json | 2 +- README.md | 2 +- .../SKILL.md | 111 ++++--- .../references/package-identity.md | 3 +- .../references/render-modes.md | 88 +++-- .../references/split-webapp-registration.md | 96 ++---- .../references/theme-and-host-files.md | 31 +- .../references/troubleshooting.md | 62 ++-- .../eval.yaml | 302 +++++++++--------- 13 files changed, 354 insertions(+), 353 deletions(-) diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index e38732b689..cd87107df9 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -75,7 +75,7 @@ { "name": "dotnet-blazor", "source": "./plugins/dotnet-blazor", - "description": "Skills for Blazor development: component authoring, interactivity, and web application patterns." + "description": "Skills for Blazor development: component authoring, interactivity, web application patterns, and Syncfusion Blazor Toolkit installation." }, { "name": "dotnet-winforms", diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 898e7608b9..b2de5a8e53 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -85,7 +85,7 @@ { "name": "dotnet-blazor", "source": "./plugins/dotnet-blazor", - "description": "Skills for Blazor development: component authoring, interactivity, and web application patterns." + "description": "Skills for Blazor development: component authoring, interactivity, web application patterns, and Syncfusion Blazor Toolkit installation." }, { "name": "dotnet-winforms", diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 121ae385c6..394aacd744 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -75,7 +75,7 @@ { "name": "dotnet-blazor", "source": "./plugins/dotnet-blazor", - "description": "Skills for Blazor development: component authoring, interactivity, and web application patterns." + "description": "Skills for Blazor development: component authoring, interactivity, web application patterns, and Syncfusion Blazor Toolkit installation." }, { "name": "dotnet-winforms", diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index fbcdf04999..dc1cb7ccc4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -87,6 +87,10 @@ /plugins/dotnet-blazor/ @dotnet/aspnet /tests/dotnet-blazor/ @dotnet/aspnet +# Syncfusion Blazor Toolkit install skill +/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/ @dotnet/aspnetcore-syncfusion-vendors @sheiksyedm @Indhumathy-Loganathan @rajendranr-5483 +/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/ @dotnet/aspnetcore-syncfusion-vendors @sheiksyedm @Indhumathy-Loganathan @rajendranr-5483 + # dotnet-winforms (Windows Forms development) /plugins/dotnet-winforms/ @KlausLoeffelmann @AbhitejJohn /tests/dotnet-winforms/ @KlausLoeffelmann @AbhitejJohn diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 8f6a538ea7..7974ab7c22 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -72,7 +72,7 @@ { "name": "dotnet-blazor", "source": "./plugins/dotnet-blazor", - "description": "Skills for Blazor development: component authoring, interactivity, and web application patterns." + "description": "Skills for Blazor development: component authoring, interactivity, web application patterns, and Syncfusion Blazor Toolkit installation." }, { "name": "dotnet-winforms", diff --git a/README.md b/README.md index 78c47fd0f3..9460d6d027 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Plugin support is component-specific: | [dotnet-test](plugins/dotnet-test/) | Skills for running, generating, analyzing, and improving .NET tests: test execution, filtering, platform detection, coverage, testability, and MSTest workflows. | | [dotnet-test-migration](plugins/dotnet-test-migration/) | Skills and a GitHub Copilot orchestrator agent for migrating .NET test frameworks and platforms: MSTest and xUnit version upgrades, xUnit-to-MSTest conversion, and VSTest to Microsoft.Testing.Platform. | | [dotnet-aspnetcore](plugins/dotnet-aspnetcore/) | ASP.NET Core web development skills including middleware, endpoints, real-time communication, and API patterns. | -| [dotnet-blazor](plugins/dotnet-blazor/) | Skills for Blazor development: component authoring, interactivity, and web application patterns. | +| [dotnet-blazor](plugins/dotnet-blazor/) | Skills for Blazor development: component authoring, interactivity, web application patterns, and Syncfusion Blazor Toolkit installation. | | [dotnet-winforms](plugins/dotnet-winforms/) | Skills for Windows Forms development: project setup, UI design, data binding, accessibility, and modern .NET practices. | | [dotnet11](plugins/dotnet11/) | Skills for new .NET 11 APIs and language features. | diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md index 5979757c5c..cbb7e36f0e 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md @@ -2,17 +2,17 @@ name: syncfusion-blazor-toolkit-install description: > Install and register the open-source Syncfusion Blazor Toolkit package, - configure AddSyncfusionBlazorToolkit(), link the Fluent theme, and apply - the correct interactive render mode for your app topology (Server / WASM / Auto). - - USE FOR: Toolkit setup, package verification, theme linking, split-app registration, render-mode troubleshooting. - DO NOT USE FOR: component API details (use author-component), Blazor project creation (use create-blazor-project), - commercial Syncfusion packages or license keys, Hybrid/MAUI. -license: MIT -compatibility: ".NET 8+, Blazor Server / WebAssembly / Auto / Static SSR" -metadata: - author: "Syncfusion Inc" - version: "1.0.2" + configure AddSyncfusionBlazorToolkit(), link the Fluent or High Contrast + stylesheet, and apply the interactive render mode that matches the app + topology (legacy Server, standalone WASM, or a Blazor Web App). + + USE FOR: Toolkit setup, package verification, stylesheet linking, split-app + registration, render-mode troubleshooting, and diagnosing an accidental + commercial Syncfusion.Blazor install or license-key prompt when the user + wanted the open-source Toolkit. + DO NOT USE FOR: component API details (use author-component), Blazor project + creation (use create-blazor-project), configuring commercial Syncfusion + components that the app actually uses, Hybrid/MAUI. --- # Install Syncfusion Blazor Toolkit @@ -20,13 +20,13 @@ metadata: ## Core Rules 1. Use the exact package ID `Syncfusion.Blazor.Toolkit`. -2. Call `AddSyncfusionBlazorToolkit()` in `Program.cs` before `builder.Build()`. -3. Import `@using Syncfusion.Blazor.Toolkit` in `_Imports.razor`; add component namespaces such as `@using Syncfusion.Blazor.Toolkit.Buttons` only when a component needs them. -4. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` in the app host file. -5. Use `@rendermode` for interactive Toolkit components in .NET 8+ Blazor Web App; legacy Blazor Server templates are already interactive (no `@rendermode` needed). -6. In split Blazor Web Apps, register Toolkit in every project that uses Toolkit components. -7. Never use commercial `Syncfusion.Blazor*` packages or license-key APIs for Toolkit. -8. Toolkit JavaScript is embedded in the Syncfusion NuGet package; do not add commercial script tags or `AddSyncfusionLicense()` calls. +2. In every `Program.cs` that calls `AddSyncfusionBlazorToolkit()`, add `using Syncfusion.Blazor.Toolkit;` so the extension method is in scope. Call it before `builder.Build()`. +3. Import `@using Syncfusion.Blazor.Toolkit` in `_Imports.razor`; add component namespaces such as `@using Syncfusion.Blazor.Toolkit.Buttons` only when a component needs them. `_Imports.razor` does not affect `Program.cs`. +4. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` (or `highcontrast.min.css`) in the app host file. Fluent is the default. +5. Use `@rendermode` only in a Blazor Web App. Legacy Blazor Server and standalone WebAssembly are already interactive and do not use render modes. +6. In a split Blazor Web App, the `.Client` project is not a standalone WASM app. Do not call `RootComponents.Add("#app")` there. Register Toolkit on every host that renders Toolkit components, including the server when prerendering is left on. +7. Do not add a commercial `Syncfusion.Blazor*` package to satisfy a Toolkit request. If the app already uses commercial components, leave those packages and `Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(...)` in place. +8. Toolkit JavaScript is embedded in the NuGet package; do not add commercial script tags. 9. Keep this skill install-focused; use the references for details and troubleshooting. ## Don'ts @@ -40,11 +40,12 @@ metadata: | Scenario | Package | Program.cs | Host file for CSS | Interactivity | | --- | --- | --- | --- | --- | -| Blazor Server (legacy _Host.cshtml) | `Syncfusion.Blazor.Toolkit` | `builder.Services.AddSyncfusionBlazorToolkit()` | `_Host.cshtml` | Interactive by default (no `@rendermode` directive) | -| Blazor WebAssembly (standalone) | `Syncfusion.Blazor.Toolkit` | `builder.Services.AddSyncfusionBlazorToolkit()` | `wwwroot/index.html` | Interactive by default (no `@rendermode` directive) | -| Blazor Web App (Auto) | `Syncfusion.Blazor.Toolkit` | Register in Server and Client projects that use Toolkit | `App.razor` | `@rendermode InteractiveAuto` | -| Blazor Web App (Split Server/Client) | `Syncfusion.Blazor.Toolkit` | Register in Server and Client projects that use Toolkit | `App.razor` | `@rendermode InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto` | -| Static SSR only | `Syncfusion.Blazor.Toolkit` | Register services as needed | `App.razor` or `index.html` | None; read-only only | +| Blazor Server (legacy `_Host.cshtml`) | `Syncfusion.Blazor.Toolkit` | `using Syncfusion.Blazor.Toolkit;` then `builder.Services.AddSyncfusionBlazorToolkit()` | `_Host.cshtml` | Already interactive (no `@rendermode`) | +| Blazor WebAssembly (standalone) | `Syncfusion.Blazor.Toolkit` | `using Syncfusion.Blazor.Toolkit;` then `builder.Services.AddSyncfusionBlazorToolkit()` | `wwwroot/index.html` | Already interactive (no `@rendermode`; not static SSR) | +| Blazor Web App, global Interactive Server | `Syncfusion.Blazor.Toolkit` | Server `Program.cs` only, with the using above | `Components/App.razor` | Inherited from `Routes`; do not add a different child mode | +| Blazor Web App, per-page or per-component | `Syncfusion.Blazor.Toolkit` | Every host that renders the component, including the server while prerendering is on | `Components/App.razor` | One interactive mode: `InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto` | +| Blazor Web App (split Server/Client) | `Syncfusion.Blazor.Toolkit` | Server and `.Client` when both render Toolkit. No `RootComponents.Add` in `.Client` | `Components/App.razor` | Same mode as the parent page; a child cannot switch interactive modes | +| Static SSR only (Blazor Web App) | `Syncfusion.Blazor.Toolkit` | Server `Program.cs` if any Toolkit markup is rendered | `Components/App.razor` | None; read-only only. Standalone WASM is not this row | ## Minimal Setup @@ -58,8 +59,13 @@ dotnet add package Syncfusion.Blazor.Toolkit Match the render modes from the Quick Decision Table above. Do not add unused render modes. -**For Blazor Web App (Auto or Server+Client split)**: +**Blazor Web App server `Program.cs` (Auto, WebAssembly, or split)**: + +Keep the interactive services the template already generated. Register Toolkit here even when the component lives in `.Client`, because default prerendering runs it on the server. + ```csharp +using Syncfusion.Blazor.Toolkit; + var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents() @@ -75,8 +81,13 @@ app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode(); ``` -**For .NET 8+ Blazor Web App (server-only mode)**: +**Blazor Web App server `Program.cs` (Interactive Server only)**: + +Do not add WebAssembly services unless the project already references `Microsoft.AspNetCore.Components.WebAssembly.Server`. + ```csharp +using Syncfusion.Blazor.Toolkit; + var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents() @@ -90,11 +101,29 @@ app.MapRazorComponents() .AddInteractiveServerRenderMode(); ``` -**For Blazor WebAssembly**: +**Blazor Web App `.Client/Program.cs`**: + +This project is not a standalone WASM app. The server owns `App.razor`, and the host page has no `#app` element, so do not register a root component here. + ```csharp +using Syncfusion.Blazor.Toolkit; + +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +builder.Services.AddSyncfusionBlazorToolkit(); + +await builder.Build().RunAsync(); +``` + +**Standalone Blazor WebAssembly `Program.cs`**: + +```csharp +using Syncfusion.Blazor.Toolkit; + var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.RootComponents.Add("#app"); +builder.RootComponents.Add("head::after"); builder.Services.AddSyncfusionBlazorToolkit(); @@ -106,12 +135,12 @@ await builder.Build().RunAsync(); ```razor @using Syncfusion.Blazor.Toolkit -@* Optional: Add component-specific namespaces only when using those components *@ +@* Optional: add component-specific namespaces only when using those components *@ @* @using Syncfusion.Blazor.Toolkit.Buttons *@ @* @using Syncfusion.Blazor.Toolkit.Calendars *@ ``` -For component-specific features, uncomment and include the appropriate namespace in `_Imports.razor` as needed. +`_Imports.razor` does not put the namespace in scope for `Program.cs`. ### Host file CSS @@ -119,26 +148,28 @@ For component-specific features, uncomment and include the appropriate namespace ``` -Always pick the host file from the Quick Decision Table above: `_Host.cshtml` for legacy Blazor Server, `App.razor` for Blazor Web App, or `wwwroot/index.html` for Blazor WebAssembly. +Pick the host file from the Quick Decision Table: `_Host.cshtml` for legacy Blazor Server, `Components/App.razor` for a Blazor Web App, or `wwwroot/index.html` for standalone WebAssembly. Use `highcontrast.min.css` only when the user asks for high contrast. ## Common Mistakes | Mistake | Symptom | Fix | | --- | --- | --- | -| CSS path uses `themes/` instead of `styles/` | Components are unstyled (404 in browser DevTools) | Change `_content/Syncfusion.Blazor.Toolkit/themes/fluent.css` to `.../styles/fluent.min.css` | -| CSS linked in a component file instead of host file | Styling doesn't apply consistently | Move `` tag to the host file's `` section | -| Using commercial `Syncfusion.Blazor` package | License key errors, missing components | Remove commercial package; use only `Syncfusion.Blazor.Toolkit` | -| Added external Syncfusion CDN script tag | JavaScript conflicts or duplicate library errors | Remove external CDN script; Toolkit JS is bundled in the NuGet package | -| Missing `@rendermode` on interactive components | Components don't respond to clicks/binding | Add `@rendermode InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto` | -| Static SSR with interactive components | Buttons and inputs don't work | Switch to an interactive render mode (see Quick Decision Table) | +| CSS path uses `themes/` or omits `.min` | Components are unstyled (404 in browser DevTools) | Use `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` | +| CSS linked in a component file instead of the host file | Styling doesn't apply consistently | Move the `` to the host file `` from the Quick Decision Table | +| Commercial package added for a Toolkit-only app | License prompt, missing Toolkit components | Replace that package with `Syncfusion.Blazor.Toolkit`. If other pages still use commercial components, keep those packages and `SyncfusionLicenseProvider.RegisterLicense(...)` | +| Added an external Syncfusion CDN script tag | JavaScript conflicts or duplicate library errors | Remove the CDN script; Toolkit JS ships in the NuGet package | +| `@rendermode` missing, and no interactive mode is inherited | Clicks and binding do nothing on a Blazor Web App page | Apply one interactive mode, or inherit the mode already on `Routes` | +| `@rendermode` added to standalone WASM or legacy Server | No effect, and it can look like a fix | Remove it; those apps are already interactive | +| Child `@rendermode` differs from the parent interactive mode | Runtime error; a child cannot switch interactive modes | Match the inherited mode, or move the component to a page with the intended mode | +| `RootComponents.Add("#app")` added to `.Client` | The Client host has no `#app` element | Remove it. That call belongs only in standalone WebAssembly | ## Top Failure Symptoms -- **Unstyled components**: the Fluent CSS link is missing, wrong, or placed in the wrong host file. See [Theme and host files](./references/theme-and-host-files.md). -- **Services not configured**: `AddSyncfusionBlazorToolkit()` is missing from `Program.cs`. See [Troubleshooting guide](./references/troubleshooting.md). -- **Clicks or inputs do nothing**: the page is using static SSR. Add `@rendermode InteractiveServer`, `@rendermode InteractiveWebAssembly`, or `@rendermode InteractiveAuto`. See [Render modes explained](./references/render-modes.md). -- **Only one half of a split app works**: register Toolkit in both Server and Client if both use Toolkit. See [Split Blazor Web App registration](./references/split-webapp-registration.md). -- **Wrong package or license guidance**: the project uses a commercial `Syncfusion.Blazor*` package instead of the Toolkit. See [Package identity and splits](./references/package-identity.md). +- **Unstyled components**: the stylesheet link is missing, wrong, or placed in the wrong host file. See [Theme and host files](./references/theme-and-host-files.md). +- **Services not configured**: `AddSyncfusionBlazorToolkit()` or its `using Syncfusion.Blazor.Toolkit;` is missing from a `Program.cs` that renders Toolkit. See [Troubleshooting guide](./references/troubleshooting.md). +- **Clicks or inputs do nothing**: check for an inherited render mode before editing the page. If none exists, the page is static SSR. See [Render modes explained](./references/render-modes.md). +- **Only one half of a split app works**: register Toolkit on every host that renders it, including the server while prerendering is on. See [Split Blazor Web App registration](./references/split-webapp-registration.md). +- **License prompt after installing `Syncfusion.Blazor`**: that is the commercial package. See [Package identity and splits](./references/package-identity.md) before removing anything the app still uses. ## Next Steps diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md index 4f3a800c8d..8f66059170 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md @@ -18,8 +18,9 @@ - **Package name(s)**: `Syncfusion.Blazor`, `Syncfusion.Blazor.Core`, `Syncfusion.Blazor.Buttons`, `Syncfusion.Blazor.Calendars`, `Syncfusion.Blazor.Charts`, `Syncfusion.Blazor.Grids`, `Syncfusion.Blazor.Inputs`, etc. - **License**: Commercial (requires valid license key for production) - **Scope**: Full-featured Syncfusion component library -- **Requires**: License-key registration via `AddSyncfusionLicense()` (or similar) +- **Requires**: License registration through `Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(...)`. There is no `AddSyncfusionLicense()` API. - **Not the same as Toolkit**: Commercial packages are separate products with different APIs and licensing +- **Do not remove them blindly**: If any page still uses a commercial component, keep that package and its `RegisterLicense` call. Remove them only when Toolkit is replacing every commercial component in the app. ## Install the Toolkit (and ONLY the Toolkit for this skill) diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md index 00bc2f9225..178a473e64 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md @@ -25,13 +25,13 @@ Blazor supports multiple render modes. Toolkit components need an interactive mo ## Interactive Server Rendering -**When to use**: Interactive components hosted on a Blazor Server app or on the Server side of a Blazor Web App. +**When to use**: Interactive components on a Blazor Web App configured for Interactive Server, or a page that opts into `@rendermode InteractiveServer`. -**Characteristic**: User interactions are sent to the server, processed, and updates stream back to the client in real time. +**Characteristic**: User interactions are sent to the server, processed, and updates stream back to the client. -**Toolkit requirement**: Fully supported; all event handlers and state changes work. +**Toolkit requirement**: Fully supported. Register Toolkit in the server `Program.cs`. -**Example**: +**Example** (only when the page does not already inherit an interactive mode): ```razor @page "/counter" @rendermode InteractiveServer @@ -45,33 +45,33 @@ Blazor supports multiple render modes. Toolkit components need an interactive mo } ``` -**Current template setup**: +**Server-only template setup**. Do not add WebAssembly services here; a server-only project may not reference `Microsoft.AspNetCore.Components.WebAssembly.Server`. + ```csharp -// Program.cs +using Syncfusion.Blazor.Toolkit; + var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents() - .AddInteractiveServerComponents() - .AddInteractiveWebAssemblyComponents(); + .AddInteractiveServerComponents(); builder.Services.AddSyncfusionBlazorToolkit(); var app = builder.Build(); app.MapRazorComponents() - .AddInteractiveServerRenderMode() - .AddInteractiveWebAssemblyRenderMode(); + .AddInteractiveServerRenderMode(); ``` ## Interactive WebAssembly Rendering -**When to use**: Interactive components running as WebAssembly on the client (standalone Blazor WebAssembly or the Client project in a Blazor Web App). +**When to use**: A Blazor Web App page or component that should run in the browser after download (`dotnet new blazor -int WebAssembly`, or a component in the `.Client` project). -**Characteristic**: .NET runs in the browser; no server round-trip for user interactions after load. +**Characteristic**: .NET runs in the browser; no server round-trip for user interactions after load. Default prerendering still executes the component on the server first, so the server also needs Toolkit services. -**Toolkit requirement**: Fully supported; all event handlers and state changes work. +**Do not use `@rendermode` in a standalone Blazor WebAssembly app.** That app is already interactive. The directive has no effect there and can look like a fix for a different problem. -**Example**: +**Blazor Web App example** (only when the page does not already inherit an interactive mode): ```razor @page "/counter" @rendermode InteractiveWebAssembly @@ -85,12 +85,25 @@ app.MapRazorComponents() } ``` -**Setup**: +**`.Client/Program.cs`** (not a standalone app; no root component): +```csharp +using Syncfusion.Blazor.Toolkit; + +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +builder.Services.AddSyncfusionBlazorToolkit(); + +await builder.Build().RunAsync(); +``` + +**Standalone WebAssembly `Program.cs`**: ```csharp -// Program.cs (standalone WASM or .Client project) +using Syncfusion.Blazor.Toolkit; + var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.RootComponents.Add("#app"); +builder.RootComponents.Add("head::after"); builder.Services.AddSyncfusionBlazorToolkit(); @@ -99,11 +112,11 @@ await builder.Build().RunAsync(); ## Interactive Auto Rendering -**When to use**: Blazor Web App projects that should start on the server and then continue running in the browser when available. +**When to use**: A Blazor Web App that should use server interactivity on the first visit, then WebAssembly on later visits once the runtime bundle is downloaded and cached. -**Characteristic**: The app can begin with server interactivity and transition to client-side WebAssembly for later interactions. +**Characteristic**: Auto chooses the runtime per visit. A component that is already running does not switch from server to WebAssembly mid-circuit. See the render-mode documentation: https://learn.microsoft.com/aspnet/core/blazor/components/render-modes -**Toolkit requirement**: Fully supported; all event handlers and state changes work. +**Toolkit requirement**: Fully supported. Register Toolkit in both the server and `.Client` projects, because the first visit renders on the server and later visits render in WebAssembly. **Example**: ```razor @@ -119,9 +132,10 @@ await builder.Build().RunAsync(); } ``` -**Setup**: +**Server setup** (keep both interactive endpoints; this is the combined hosting case, not the server-only case): ```csharp -// Program.cs +using Syncfusion.Blazor.Toolkit; + var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents() @@ -137,25 +151,29 @@ app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode(); ``` +Also call `AddSyncfusionBlazorToolkit()` in `.Client/Program.cs`. Do not add `RootComponents.Add("#app")` there. + ## Decision Tree 1. **Does the component need to respond to user clicks or changes?** - - **No** → Static SSR is fine (no render mode needed) - - **Yes** → Go to question 2 + - **No** → Static rendering is enough. Stop. + - **Yes** → Go to question 2. -2. **Should processing happen on the server, in the browser, or both?** - - **Server** → Use `@rendermode InteractiveServer` - - **Browser (WASM)** → Use `@rendermode InteractiveWebAssembly` - - **Start on server, continue in browser** → Use `@rendermode InteractiveAuto` +2. **Which app is this?** + - **Legacy Blazor Server or standalone WebAssembly** → Already interactive. Do not add `@rendermode`. + - **Blazor Web App** → Go to question 3. -3. **Toolkit component won't respond?** - - **Symptom**: Click or input events don't work - - **Solution**: Ensure the component or page has an interactive render mode applied +3. **Does `Routes` in `App.razor` already apply an interactive mode?** + - **Yes** → Inherit it. A child cannot switch to a different interactive mode. + - **No** → Apply one mode on the page or component: + - Server processing → `@rendermode InteractiveServer` + - Browser processing → `@rendermode InteractiveWebAssembly` + - Server on the first visit, WebAssembly on later cached visits → `@rendermode InteractiveAuto` ## Common Mistakes -1. **Forgetting `@rendermode`**: Interactive components in a static page won't respond to clicks. -2. **Using static SSR for interactive components**: Toolkit components require interactive mode for event handling. -3. **Mismatched render mode**: Trying to use `InteractiveServer` in a WebAssembly-only app won't work. -4. **Ignoring `InteractiveAuto`**: Auto is a first-class render mode for current Blazor Web App templates. -5. **Assuming automatic**: Render mode doesn't "just work"; it must be explicitly declared. +1. **Adding `@rendermode` under an inherited mode**: If `Routes` already has an interactive mode, a child that names a different one fails. Match the parent or move the component. +2. **Treating standalone WebAssembly as static SSR**: It has no static SSR and no render-mode directive. +3. **Adding WebAssembly endpoints to a server-only project**: That project may not reference the WebAssembly server package. +4. **Describing Auto as a live runtime switch**: The first visit uses the server; later visits use the cached WebAssembly bundle. A running component does not migrate. +5. **Assuming a missing directive means the component is static**: Check the inherited mode first. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md index 3fd08bcf3e..a40a7f97a2 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md @@ -1,21 +1,25 @@ # Split Blazor Web App Service Registration -When using a split Blazor Web App, register Toolkit services in every project that actually renders Toolkit components. +A generated `.Client` project is not a standalone WebAssembly app. The server owns `App.razor`, and the host markup has no `#app` element. Never call `RootComponents.Add("#app")` in `.Client/Program.cs`. -## Current template note +Default prerendering renders Interactive WebAssembly and Interactive Auto components on the server first. If the server does not have Toolkit services, that first render fails even when `.Client` is registered correctly. Disable prerendering only when the user explicitly asks; otherwise register Toolkit on both hosts. -For `dotnet new blazor -int Auto` and `dotnet new blazor -int WebAssembly`, the generated Server project typically wires interactive server and WebAssembly support in `Program.cs`, while the `.Client` project is the browser-side app. Keep Toolkit registration in whichever project uses Toolkit components. +`dotnet new blazor -int Auto` and `dotnet new blazor -int WebAssembly` already add interactive server and WebAssembly endpoints on the server. Keep those endpoints. A server-only Interactive Server app should not gain WebAssembly endpoints just to host Toolkit. -## Scenario 1: Only Server uses Toolkit +## Scenario 1: Interactive Server only + +The server does not host Client components, so leave WebAssembly endpoints off. Do not add a `.Client` registration for components that project never renders, and do not add `RootComponents.Add("#app")`. **Server/Program.cs**: ```csharp +using Syncfusion.Blazor.Toolkit; + var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents() .AddInteractiveServerComponents(); -builder.Services.AddSyncfusionBlazorToolkit(); // Server-side registration +builder.Services.AddSyncfusionBlazorToolkit(); var app = builder.Build(); @@ -23,54 +27,21 @@ app.MapRazorComponents() .AddInteractiveServerRenderMode(); ``` -**Client/Program.cs**: -```csharp -var builder = WebAssemblyHostBuilder.CreateDefault(args); - -builder.RootComponents.Add("#app"); - -// No Toolkit registration needed if Client doesn't use Toolkit -await builder.Build().RunAsync(); -``` +## Scenario 2: Client components use Toolkit -## Scenario 2: Only Client uses Toolkit +This is not "Client only" while prerendering is on. Keep the generated WebAssembly endpoints, and register Toolkit on the server as well. **Server/Program.cs**: ```csharp -var builder = WebApplication.CreateBuilder(args); - -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents(); -// No Toolkit registration; Server doesn't use it - -var app = builder.Build(); - -app.MapRazorComponents() - .AddInteractiveServerRenderMode(); -``` - -**Client/Program.cs**: -```csharp -var builder = WebAssemblyHostBuilder.CreateDefault(args); - -builder.RootComponents.Add("#app"); - -builder.Services.AddSyncfusionBlazorToolkit(); // Client-side registration - -await builder.Build().RunAsync(); -``` +using Syncfusion.Blazor.Toolkit; -## Scenario 3: Both Server and Client use Toolkit (MOST COMMON) - -**Server/Program.cs**: -```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents() .AddInteractiveServerComponents() .AddInteractiveWebAssemblyComponents(); -builder.Services.AddSyncfusionBlazorToolkit(); // Register here +builder.Services.AddSyncfusionBlazorToolkit(); var app = builder.Build(); @@ -79,48 +50,33 @@ app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode(); ``` -**Client/Program.cs**: +**.Client/Program.cs**: ```csharp -var builder = WebAssemblyHostBuilder.CreateDefault(args); +using Syncfusion.Blazor.Toolkit; -builder.RootComponents.Add("#app"); +var builder = WebAssemblyHostBuilder.CreateDefault(args); -builder.Services.AddSyncfusionBlazorToolkit(); // Also register here +builder.Services.AddSyncfusionBlazorToolkit(); await builder.Build().RunAsync(); ``` -## Scenario 4: Auto render mode uses Toolkit on both sides +## Scenario 3: Interactive Auto -If you use `@rendermode InteractiveAuto`, keep Toolkit registration in both Server and Client when both halves render Toolkit components. +Use the same server and client registration as Scenario 2. Interactive Auto needs both, because the first visit renders on the server and later cached visits render in WebAssembly. Do not add `RootComponents.Add("#app")` to `.Client`. -## Common Mistake: Forgetting Client Registration +## Common Mistake: Registering only one host -If Toolkit components are used in the Client project but `AddSyncfusionBlazorToolkit()` is only called in Server `Program.cs`, the Client will not have access to Toolkit services and components will fail. +Calling `AddSyncfusionBlazorToolkit()` only in the server `Program.cs` does not register it for `.Client`. The reverse is also wrong while prerendering is on. -**Symptom**: Components work in Server-hosted components but fail in Client components. +**Symptom**: Server-hosted components work, but Client components fail on first load or after the WASM runtime takes over. -**Solution**: Ensure both projects have the registration call if both use Toolkit. +**Fix**: Register Toolkit in every host that renders it, keep the template's WebAssembly endpoints, and never add `RootComponents.Add("#app")` to `.Client`. -## Theme CSS in Split Web App +## Theme CSS in a Split Web App -Theme CSS should be linked in the shared `App.razor` host file so both Server and Client components can use it: +Link the stylesheet in `Components/App.razor` so both Server and Client components can use it. Fluent is the default; `highcontrast.min.css` is also valid. ```razor - - - - - - - - - - - - - - + ``` - -This ensures the theme is available to both Server and Client components. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md index 96bc48a443..e797622361 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md @@ -2,11 +2,11 @@ Toolkit components require CSS theming. Use the host file for your app type and link the Fluent stylesheet there. -## Blazor Web App / Modern Blazor Server +## Blazor Web App -**Host file**: `App.razor` +**Host file**: `Components/App.razor` -**Theme**: Syncfusion Blazor Toolkit supports **Fluent theme only**. +**Theme**: Fluent is the default Toolkit stylesheet. The package also includes `highcontrast.min.css`. Do not link commercial theme files such as Bootstrap, Tailwind, or Material. **Example**: ```razor @@ -28,11 +28,11 @@ Toolkit components require CSS theming. Use the host file for your app type and **Legacy Blazor Server note**: If you are on an older Server template, `_Host.cshtml` may still be the host file and `blazor.server.js` may still appear there. Prefer `App.razor` and `blazor.web.js` for current Blazor Web App templates. -## Blazor WebAssembly +## Standalone Blazor WebAssembly -**Host file**: `index.html` (in the `wwwroot` folder) +**Host file**: `wwwroot/index.html` -**Theme**: Syncfusion Blazor Toolkit supports **Fluent theme only**. +**Theme**: Same stylesheets as the Web App host. Link `fluent.min.css` unless the user asks for high contrast. **Example**: ```html @@ -53,14 +53,13 @@ Toolkit components require CSS theming. Use the host file for your app type and ``` -## Available Themes +## Available stylesheets -Syncfusion Blazor Toolkit supports **only the Fluent theme**: +- `fluent.min.css` — default Fluent stylesheet. Use this unless the user asks for something else. +- `highcontrast.min.css` — high-contrast stylesheet shipped with the Toolkit package. +- Individual component stylesheets: `button.min.css`, `calendar.min.css`, `chart.min.css`, `checkbox.min.css`, `dialog.min.css`, `dropdown.min.css`, `input.min.css`, `spinner.min.css`, `textbox.min.css`, `tooltip.min.css`, and others. -- `fluent.min.css` — Microsoft Fluent Design theme (the only supported theme) — use this for the common stylesheet -- Individual component stylesheets: `button.min.css`, `calendar.min.css`, `chart.min.css`, `checkbox.min.css`, `dialog.min.css`, `dropdown.min.css`, `input.min.css`, `spinner.min.css`, `textbox.min.css`, `tooltip.min.css`, etc. - -Do not attempt to use other theme CSS files (bootstrap5, tailwind, material, etc.) with the Toolkit; they are not supported and will not work correctly. +Do not link commercial theme files (`bootstrap5`, `tailwind`, `material`, and similar). They are not part of this package and will not style Toolkit components. ## Local References @@ -76,9 +75,9 @@ Local references are preferred because they: ## Common Mistakes -1. **Linking in the wrong file**: Link the theme in the app's host file (`App.razor` for Blazor Web App / modern Blazor Server; `wwwroot/index.html` for Blazor WebAssembly). -2. **Wrong path directory**: Ensure the path is `_content/Syncfusion.Blazor.Toolkit/styles/` exactly (note: `styles/`, not `themes/`). -3. **Wrong theme name**: Using `bootstrap5.min.css`, `tailwind.min.css`, `material.min.css`, or other non-Fluent themes won't work. Toolkit supports **only `fluent.min.css`**. -4. **Missing .min extension**: Ensure you use `.min.css` (not just `.css`). The correct filename is `fluent.min.css`. +1. **Linking in the wrong file**: Use `_Host.cshtml` for legacy Blazor Server, `Components/App.razor` for a Blazor Web App, or `wwwroot/index.html` for standalone WebAssembly. +2. **Wrong path directory**: The path is `_content/Syncfusion.Blazor.Toolkit/styles/` (`styles/`, not `themes/`). +3. **Wrong stylesheet name**: `bootstrap5`, `tailwind`, and `material` files are not in this package. Use `fluent.min.css` or `highcontrast.min.css`. +4. **Missing `.min` extension**: The filenames are `fluent.min.css` and `highcontrast.min.css`, not `fluent.css`. 5. **Missing link entirely**: Without the theme, components render unstyled and may be hard to see. 6. **Individual stylesheet only**: If you link only individual component stylesheets (e.g., just `button.min.css`), components not included will be unstyled. Use `fluent.min.css` for all components unless performance optimization is needed. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md index 4666c71c23..cc866e8cff 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md @@ -20,14 +20,14 @@ ``` 3. If found, verify: - Path is **exactly** `_content/Syncfusion.Blazor.Toolkit/styles/` (not `themes/`) - - Filename is **exactly** `fluent.min.css` (Toolkit only supports Fluent; no Bootstrap, Tailwind, or Material) + - Filename is `fluent.min.css` or `highcontrast.min.css`. Bootstrap, Tailwind, and Material files are not in this package. - No typos; `.min` extension is required 4. If missing, add it to the `` section 5. Open browser DevTools (F12) Network tab and verify the CSS file loads with status 200 (not 404) **Common mistakes**: - Wrong path: `_content/Syncfusion.Blazor.Toolkit/themes/fluent.min.css` (should be `styles/`) -- Wrong theme name: `bootstrap5.min.css`, `tailwind.min.css`, `material.min.css` (must be `fluent.min.css`) +- Wrong stylesheet name: `bootstrap5.min.css`, `tailwind.min.css`, `material.min.css` (use `fluent.min.css` or `highcontrast.min.css`) - Missing `.min` extension: `fluent.css` (should be `.min.css`) - Linked in wrong host file: use `App.razor` for Blazor Web App/Server or `wwwroot/index.html` for WebAssembly - Linked in a component file instead of the host file (always place it in the host file's `` section for best results) @@ -58,10 +58,12 @@ **Fix**: ```csharp +using Syncfusion.Blazor.Toolkit; + var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorComponents(); -builder.Services.AddSyncfusionBlazorToolkit(); // <-- Add this +builder.Services.AddSyncfusionBlazorToolkit(); var app = builder.Build(); ``` @@ -75,18 +77,18 @@ var app = builder.Build(); - Clicking buttons or entering text in forms has no effect - No errors in the browser console -**Root cause**: Component is rendered in static SSR mode; interactive render mode is not applied. +**Root cause**: The component is static, or an interactive child is trying to switch modes. A missing `@rendermode` does not by itself mean the component is static. **Diagnosis**: -1. Check the component or page definition: - - Look for `@rendermode InteractiveServer` or `@rendermode InteractiveWebAssembly` - - If missing, the component is static -2. Confirm the interaction type (Server or WebAssembly) +1. Identify the app. Legacy Blazor Server and standalone WebAssembly are already interactive; do not add `@rendermode`. +2. In a Blazor Web App, open `Components/App.razor` and check `Routes`. If `Routes` already has an interactive mode, the page inherits it. A child cannot switch to a different interactive mode. +3. If neither the page nor `Routes` has an interactive mode, the page is static SSR. +4. If a mode is already present and clicks still do nothing, check the circuit, the browser console, and failed `_content` script requests before editing the page. -**Fix**: +**Fix** (only when no interactive mode is inherited): ```razor @page "/mypage" -@* Add this line *@ +@* Add one mode that matches the app's configured interactivity *@ @rendermode InteractiveServer Click me @@ -162,14 +164,8 @@ Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int 3. If only one has it, the other is missing registration **Fix**: -- **Server/Program.cs**: - ```csharp - builder.Services.AddSyncfusionBlazorToolkit(); - ``` -- **Client/Program.cs**: - ```csharp - builder.Services.AddSyncfusionBlazorToolkit(); - ``` +- Add `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` to `.Client/Program.cs`. Do not add `RootComponents.Add("#app")`. +- Also register Toolkit in the server `Program.cs` while prerendering is enabled. Keep the generated `AddInteractiveWebAssemblyComponents()` and `AddInteractiveWebAssemblyRenderMode()` calls. Also ensure both projects have the NuGet package reference in their `.csproj` files and both have namespace imports in their `_Imports.razor` files. @@ -182,30 +178,16 @@ Also ensure both projects have the NuGet package reference in their `.csproj` fi - Code references license keys or methods like `AddSyncfusionLicense()` - Components work but you're on a commercial license -**Root cause**: The commercial Syncfusion.Blazor package was installed instead of the open-source Toolkit. +**Root cause**: The commercial package was installed for a request that asked for the open-source Toolkit. Confirm that before deleting anything. **Diagnosis**: -1. Check the `.csproj` file: - ```xml - - - - - - ``` -2. Check `Program.cs` for license-key setup. +1. Check the `.csproj` and search the app for `Syncfusion.Blazor` component usage. +2. License registration, when present, uses `Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(...)`. There is no `AddSyncfusionLicense()` API. **Fix**: -1. Uninstall the commercial package: - ```bash - dotnet remove package Syncfusion.Blazor - ``` -2. Install the Toolkit: - ```bash - dotnet add package Syncfusion.Blazor.Toolkit - ``` -3. Remove any license-key registration code. -4. Add `AddSyncfusionBlazorToolkit()` instead. +1. If Toolkit is replacing every commercial component, remove the unused commercial package and its `RegisterLicense` call, then add `Syncfusion.Blazor.Toolkit`. +2. If any page still uses a commercial component, leave that package and its license registration alone. Add `Syncfusion.Blazor.Toolkit` beside it. +3. Do not invent a license key for the Toolkit package. Toolkit does not require one. --- @@ -283,3 +265,7 @@ Before troubleshooting further, verify: 7. ✓ No license-key registration code is present 8. ✓ Build completes without errors: `dotnet build` 9. ✓ Browser console shows no 404 or JavaScript errors +Stylesheet link is `fluent.min.css` or `highcontrast.min.css` in the host file (`Components/App.razor`, `_Host.cshtml`, or `wwwroot/index.html`) +5. ✓ Path uses `styles/`, not `themes/`, and keeps the `.min` extension +6. ✓ Blazor Web App interactivity is inherited from `Routes` or declared once. Do not add `@rendermode` to legacy Server or standalone WebAssembly +7. ✓ Commercial packages and `SyncfusionLicenseProvider.RegisterLicense(...)` remain only where commercial components are still used \ No newline at end of file diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml index 2ba4e4be35..72cbb37434 100644 --- a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -1,13 +1,18 @@ name: syncfusion-blazor-toolkit-install -description: Evaluates the Syncfusion Blazor Toolkit installation and configuration skill. +description: Evaluates the dotnet-blazor/syncfusion-blazor-toolkit-install skill type: capability defaults: timeout: 20m stimuli: - name: server-install-success + tags: + capability: toolkit-install + risk: wrong-package-or-host + journey: install-legacy-server prompt: | - I'm setting up a new Blazor Server project. I want to install the Syncfusion Blazor Toolkit. + I'm setting up a new legacy Blazor Server project that uses _Host.cshtml. + I want to install the open-source Syncfusion Blazor Toolkit. What are the steps I need to follow to get it working? graders: - type: output-matches @@ -15,33 +20,34 @@ stimuli: pattern: (?i)Syncfusion\.Blazor\.Toolkit - type: output-matches config: - pattern: (?i)AddSyncfusionBlazorToolkit + pattern: (?i)using\s+Syncfusion\.Blazor\.Toolkit - type: output-matches config: - pattern: (?i)_Imports\.razor + pattern: (?i)AddSyncfusionBlazorToolkit - type: output-matches config: - pattern: (?i)fluent\.min\.css|_content/Syncfusion\.Blazor\.Toolkit/styles/ + pattern: (?i)_Host\.cshtml - type: output-matches config: - pattern: (?i)(App\.razor|_Host\.cshtml) - - type: output-not-contains - config: - substring: Syncfusion.Blazor.Buttons + pattern: (?i)_content/Syncfusion\.Blazor\.Toolkit/styles/fluent\.min\.css - type: output-not-matches config: - pattern: (?i)(enter|add|register|provide)[\s\S]*(license key) - - type: output-not-contains + pattern: (?i)Syncfusion\.Blazor(?!\.Toolkit)\b + - type: output-not-matches config: - substring: AddSyncfusionLicense + pattern: (?i)(RegisterLicense\s*\(|AddSyncfusionLicense\s*\(|enter (your|a) license key|provide (your|a) license key) rubric: - - Recommends the exact Toolkit package name and not commercial component packages. - - Documents service registration, namespace imports, and theme CSS linking. - - Uses the correct Fluent stylesheet path and avoids license-key guidance. + - Installs the open-source Toolkit package and registers its extension method with the namespace in scope. + - Links the Fluent stylesheet from the package's styles directory in the legacy Server host file. + - Does not ask the user to enter or register a license key. - name: webassembly-install-success + tags: + capability: toolkit-install + risk: wrong-wasm-host + journey: install-standalone-wasm prompt: | - I'm building a Blazor WebAssembly application and want to add the Syncfusion Blazor Toolkit. + I'm building a standalone Blazor WebAssembly application and want to add the Syncfusion Blazor Toolkit. Can you guide me through installation and setup? graders: - type: output-matches @@ -55,16 +61,23 @@ stimuli: pattern: (?i)(wwwroot/)?index\.html - type: output-matches config: - pattern: (?i)@using\s+Syncfusion\.Blazor\.Toolkit + pattern: (?i)RootComponents\.Add\("#app"\) + - type: output-not-matches + config: + pattern: (?i)@rendermode - type: output-not-matches config: - pattern: (?i)(enter|add|register|provide)[\s\S]*(license key) + pattern: (?i)(put|place|link|add)[\s\S]{0,80}(stylesheet|link|css)[\s\S]{0,40}App\.razor rubric: - - Explains that WebAssembly uses index.html as the host file for the theme link. - - Includes the Toolkit package, service registration, and namespace imports. - - Avoids suggesting App.razor as the WASM host file. + - Uses index.html as the stylesheet host for a standalone WebAssembly app. + - Registers the root component only because this is a standalone app, not a Web App Client project. + - Does not add a render-mode directive to an app that is already interactive. - name: split-webapp-registration + tags: + capability: split-registration + risk: server-only-registration + journey: configure-split-web-app prompt: | We have a split Blazor Web App with Server and Client projects. Both Server and Client components need to use the Syncfusion Blazor Toolkit. What configuration is required? @@ -74,18 +87,26 @@ stimuli: pattern: (?i)AddSyncfusionBlazorToolkit - type: output-matches config: - pattern: (?i)Server + pattern: (?i)(both|server and client|client and server) - type: output-matches config: - pattern: (?i)Client - - type: output-matches + pattern: (?i)prerender + - type: output-not-matches config: - pattern: (?i)both + pattern: (?i)(only (in|on) (the )?server|client inherits|register only in server) + - type: output-not-matches + config: + pattern: (?i)RootComponents\.Add\("#app"\) rubric: - - States that both Server and Client Program.cs files need registration when both halves use Toolkit. - - Distinguishes split Web App registration from single-project setups. + - Registers Toolkit in both the server and Client hosts when both render Toolkit components. + - Keeps server registration because prerendering executes Client components on the server. + - Does not treat the Client project as a standalone WebAssembly app with its own root component. - name: missing-theme-css-failure + tags: + capability: theme-linking + risk: unstyled-components + journey: fix-missing-stylesheet prompt: | I've installed the Syncfusion Blazor Toolkit and added AddSyncfusionBlazorToolkit() to Program.cs, but my components render without any styling—they look plain and basic. @@ -93,27 +114,25 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)theme CSS|theme css + pattern: (?i)(stylesheet|css) - type: output-matches config: - pattern: (?i)link + pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/(fluent|highcontrast)\.min\.css - type: output-matches config: - pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/ - - type: output-matches - config: - pattern: (?i)App\.razor|index\.html|wwwroot/index\.html + pattern: (?i)Components/App\.razor|_Host\.cshtml|index\.html - type: output-not-contains config: substring: install a different package - - type: output-not-contains - config: - substring: buy a commercial license rubric: - - Diagnoses missing or incorrect theme CSS as the cause of unstyled components. - - Points to the correct Fluent stylesheet path and host file for the project type. + - Diagnoses a missing or misplaced stylesheet rather than a package problem. + - Gives a package stylesheet path and a host file that matches the app type. - name: static-ssr-insufficient + tags: + capability: render-mode + risk: static-ssr + journey: enable-interactivity prompt: | I have a Blazor Web App with a SfButton component from the Syncfusion Blazor Toolkit. When I click the button, nothing happens. The component is visible and styled correctly, @@ -121,31 +140,26 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)@rendermode + pattern: (?i)Interactive(Server|WebAssembly|Auto) - type: output-matches config: - pattern: (?i)InteractiveServer - - type: output-matches - config: - pattern: (?i)InteractiveWebAssembly - - type: output-matches - config: - pattern: (?i)static + pattern: (?i)(static|inherited|Routes) - type: output-not-contains config: substring: static SSR is sufficient - - type: output-not-contains - config: - substring: downgrade the package rubric: - - Explains that static SSR alone is insufficient for interactive Toolkit components. - - Recommends an interactive render mode such as InteractiveServer or InteractiveWebAssembly. + - Checks whether the page already inherits an interactive mode before treating it as static. + - Recommends one interactive mode when none is inherited, without requiring every mode to be named. - name: interactive-auto-success + tags: + capability: render-mode + risk: auto-misdescribed + journey: configure-auto prompt: | - I created the app with dotnet new blazor -int Auto. I want Toolkit components to start on - the server and continue working in the browser when available. What render mode should I use, - and what setup does the current template need? + I created the app with dotnet new blazor -int Auto. I want the first visit to stay interactive + on the server, and later visits to use WebAssembly after the runtime is downloaded. What setup + does the current template need for the Syncfusion Blazor Toolkit? graders: - type: output-matches config: @@ -159,46 +173,46 @@ stimuli: - type: output-matches config: pattern: (?i)AddSyncfusionBlazorToolkit - - type: output-matches - config: - pattern: (?i)App\.razor - - type: output-not-contains + - type: output-not-matches config: - substring: static SSR is enough + pattern: (?i)(switch|transition|continue)[\s\S]{0,60}(mid-|while running|same component) rubric: - - Recommends InteractiveAuto for the current Blazor Web App template. - - Mentions the server-side interactive setup used by the current template. - - Keeps Toolkit registration aligned with the projects that render Toolkit components. + - Describes Auto as server interactivity on the first visit and WebAssembly on later cached visits. + - Does not describe a running component switching runtimes. + - Keeps both interactive endpoints and registers Toolkit on the hosts that render it. - name: wrong-commercial-package + tags: + capability: package-identity + risk: commercial-package + journey: replace-wrong-package prompt: | I ran `dotnet add package Syncfusion.Blazor` and now I'm seeing references to AddSyncfusionLicense() - and license keys. I need to use the open-source Toolkit for a hobby project. Did I install the - wrong package? + and license keys. I need to use the open-source Toolkit for a hobby project that has no other + Syncfusion components. Did I install the wrong package? graders: - type: output-matches config: pattern: (?i)Syncfusion\.Blazor\.Toolkit - type: output-matches config: - pattern: (?i)Syncfusion\.Blazor - - type: output-matches - config: - pattern: (?i)remove - - type: output-matches - config: - pattern: (?i)dotnet remove package + pattern: (?i)SyncfusionLicenseProvider\.RegisterLicense|RegisterLicense - type: output-matches config: - pattern: (?i)AddSyncfusionBlazorToolkit + pattern: (?i)(no|not|does not|doesn't)[\s\S]{0,40}license key - type: output-not-matches config: - pattern: (?i)(enter|add|register|provide)[\s\S]*(license key) + pattern: (?i)AddSyncfusionLicense\s*\( rubric: - - Identifies the commercial package as wrong for Toolkit scenarios and recommends removing it. - - Replaces licensing guidance with the Toolkit service registration method. + - Identifies the installed package as the commercial package and replaces it for this Toolkit-only app. + - Names the real commercial license API and states that Toolkit does not need a license key. + - Does not tell the user to call a nonexistent license extension method. - name: split-app-partial-registration-failure + tags: + capability: split-registration + risk: client-unregistered + journey: fix-split-registration prompt: | I have a split Blazor Web App. I added the Syncfusion Blazor Toolkit package and registered it with AddSyncfusionBlazorToolkit() in the Server Program.cs. My Server components work fine, @@ -206,21 +220,25 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)Client Program\.cs|Client.*Program\.cs + pattern: (?i)Client[\s\S]{0,40}Program\.cs - type: output-matches config: pattern: (?i)AddSyncfusionBlazorToolkit - - type: output-matches + - type: output-not-matches config: - pattern: (?i)both - - type: output-not-contains + pattern: (?i)only (the )?server needs + - type: output-not-matches config: - substring: only Server needs registration + pattern: (?i)RootComponents\.Add\("#app"\) rubric: - - Explains that Client registration is also needed when the Client project uses Toolkit components. - - Mentions registering Toolkit in both Server and Client Program.cs files. + - Adds the missing Client registration without removing the server registration. + - Does not add a standalone WebAssembly root component to the Client project. - name: script-failure-or-js-error + tags: + capability: script-loading + risk: js-error + journey: diagnose-js-error prompt: | I installed Syncfusion Blazor Toolkit and configured everything, but now the browser console shows JavaScript errors like "undefined is not a function" related to Syncfusion. The components @@ -228,32 +246,27 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)JavaScript + pattern: (?i)(JavaScript|script) - type: output-matches config: pattern: (?i)AddSyncfusionBlazorToolkit - type: output-matches config: - pattern: (?i)Program\.cs - - type: output-matches - config: - pattern: (?i)browser console - - type: output-matches - config: - pattern: (?i)clear cache - - type: output-not-contains - config: - substring: different package + pattern: (?i)(console|network|404|_content) - type: output-not-contains config: substring: downgrade rubric: - - Diagnoses a JavaScript loading or service-registration issue rather than a package-version issue. - - Advises checking the browser console, Program.cs, and clearing cache or rebuilding. + - Diagnoses script loading or service registration before changing packages. + - Points at console, network, or static-asset evidence rather than a version rollback. - name: wrong-theme-name-failure + tags: + capability: theme-linking + risk: unsupported-theme + journey: fix-stylesheet-name prompt: | - I linked the Syncfusion Blazor Toolkit theme CSS in my App.razor like this: + I linked this stylesheet in Components/App.razor: The components render but they're completely unstyled. Browser DevTools shows no 404 errors on the CSS. @@ -261,33 +274,42 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)fluent + pattern: (?i)styles/fluent\.min\.css - type: output-matches config: - pattern: (?i)fluent\.min\.css + pattern: (?i)highcontrast\.min\.css + - type: output-not-matches + config: + pattern: (?i)href="_content/Syncfusion\.Blazor\.Toolkit/[^"]*bootstrap5 rubric: - - Identifies Fluent as the only supported theme and points to fluent.min.css. + - Replaces the unsupported stylesheet with the default Fluent file or the high-contrast file. + - Does not recommend the bootstrap5 path as the fix. - name: wrong-stylesheet-path-failure + tags: + capability: theme-linking + risk: stylesheet-404 + journey: fix-stylesheet-path prompt: | - I'm getting 404 errors for the Toolkit theme CSS file. I'm using this path: + I'm getting 404 errors for the Toolkit stylesheet. I'm using this path: The browser DevTools Network tab shows a 404. What's the correct path? graders: - type: output-matches config: - pattern: (?i)styles - - type: output-matches - config: - pattern: (?i)fluent\.min\.css - - type: output-matches + pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/fluent\.min\.css + - type: output-not-matches config: - pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/ + pattern: (?i)/themes/fluent\.css rubric: - - Gives the exact correct path under the styles directory. + - Corrects both the directory and the filename, including the minified extension. - name: script-file-loading-failure + tags: + capability: static-web-assets + risk: content-404 + journey: diagnose-script-404 prompt: | I've installed the Syncfusion Blazor Toolkit and added all the configuration. The browser DevTools shows JavaScript errors like "Cannot read property of undefined" when I interact @@ -296,36 +318,22 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)script + pattern: (?i)(_content|static web asset|package) - type: output-matches config: - pattern: _content - - type: output-matches - config: - pattern: (?i)AddSyncfusionBlazorToolkit - - type: output-matches - config: - pattern: (?i)Program\.cs - - type: output-matches - config: - pattern: (?i)clean - - type: output-matches - config: - pattern: (?i)package - - type: output-not-contains - config: - substring: wrong package - - type: output-not-contains - config: - substring: material.css - - type: output-matches + pattern: (?i)(AddSyncfusionBlazorToolkit|rebuild|clean) + - type: output-not-matches config: - pattern: (?i)(fluent\s+theme\s+only|only\s+(the\s+)?fluent) + pattern: (?i)(fluent theme only|only the fluent theme) rubric: - - Treats the issue as a script-loading/configuration problem with static asset 404s. - - Reinforces that Toolkit supports only the Fluent theme and that the package should be verified. + - Treats the 404s as missing package assets or registration, not as a theme-choice problem. + - Recommends verifying the package, registration, and a clean rebuild. - name: commercial-script-tags-wrong + tags: + capability: script-loading + risk: cdn-conflict + journey: remove-external-script prompt: | I'm setting up the Syncfusion Blazor Toolkit. I added the NuGet package, registered it in Program.cs, but then I also added the commercial Syncfusion script tag from the CDN. Now I'm getting errors about @@ -333,32 +341,30 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)Syncfusion\.Blazor\.Toolkit + pattern: (?i)(remove|delete)[\s\S]{0,80}(script|cdn) - type: output-matches config: - pattern: (?i)(embedded|bundled|included|do not add|no external|no CDN) + pattern: (?i)(embedded|bundled|included in the (nuget )?package|ships with the package) + - type: output-not-matches + config: + pattern: (?i)keep the cdn script rubric: - - Identifies that the Toolkit package includes all necessary JavaScript; external script tags are not needed. - - Explains that Toolkit JS is embedded in the NuGet package and requires no external CDN or license scripts. - - Recommends removing external Syncfusion script tags added to the host file. + - Removes the external script tag and explains that the package loads its own JavaScript. + - Does not accept leaving the CDN script in place. - name: out-of-scope-component-api + tags: + capability: dormancy + risk: install-skill-hijack + journey: answer-component-api prompt: | I'm building a chart dashboard with the Syncfusion Blazor Toolkit. How do I configure the series collection for a line chart? What are the available series types? expect_activation: false graders: - - type: prompt - config: - prompt: | - Did the skill correctly decline this component API question and redirect to installation/configuration scope? - The model should not answer chart-series API or series-collection details. - Accept if the model declines, explains the skill scope, or redirects to official component docs. - Reject if it answers the API question directly or provides series configuration code. - - type: output-matches + - type: output-not-matches config: - pattern: (?i)(out of scope|not cover|component API|installation) + pattern: (?i)(first|before answering|instead)[\s\S]{0,80}(install the package|AddSyncfusionBlazorToolkit|follow these installation steps) rubric: - - Declines or redirects because the question is about component API rather than installation/configuration. - - Anti-hijack: do not answer the chart-series API question; keep the response on installation/configuration only. - - Stays dormant on chart-series API details and does not answer the out-of-scope request. \ No newline at end of file + - The install skill stayed dormant: answer the chart API question or point to component documentation. + - Does not hijack the question with package installation, Program.cs registration, or theme setup. From bd0e815988abb18ddfcfef1c8d569303e3d21c41 Mon Sep 17 00:00:00 2001 From: Prince Oliver <31838171+PrinceOliver@users.noreply.github.com> Date: Wed, 7 Oct 2026 11:06:13 +0530 Subject: [PATCH 03/27] Add PrinceOliver as Toolkit install skill code owner. --- .github/CODEOWNERS | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index dc1cb7ccc4..6e2b356120 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -88,8 +88,8 @@ /tests/dotnet-blazor/ @dotnet/aspnet # Syncfusion Blazor Toolkit install skill -/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/ @dotnet/aspnetcore-syncfusion-vendors @sheiksyedm @Indhumathy-Loganathan @rajendranr-5483 -/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/ @dotnet/aspnetcore-syncfusion-vendors @sheiksyedm @Indhumathy-Loganathan @rajendranr-5483 +/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/ @dotnet/aspnetcore-syncfusion-vendors @sheiksyedm @Indhumathy-Loganathan @rajendranr-5483 @PrinceOliver +/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/ @dotnet/aspnetcore-syncfusion-vendors @sheiksyedm @Indhumathy-Loganathan @rajendranr-5483 @PrinceOliver # dotnet-winforms (Windows Forms development) /plugins/dotnet-winforms/ @KlausLoeffelmann @AbhitejJohn From 34be5517afa9f37039441f2c9b3d14078ba83f3e Mon Sep 17 00:00:00 2001 From: Prince Oliver <31838171+PrinceOliver@users.noreply.github.com> Date: Wed, 7 Oct 2026 12:13:47 +0530 Subject: [PATCH 04/27] Address review: fix troubleshooting checklist, host files, license metadata, add prompt graders --- .../SKILL.md | 3 ++- .../references/troubleshooting.md | 22 ++++++++----------- .../eval.yaml | 14 ++++++++++++ 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md index cbb7e36f0e..a80c0b280d 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md @@ -1,4 +1,5 @@ --- +license: MIT name: syncfusion-blazor-toolkit-install description: > Install and register the open-source Syncfusion Blazor Toolkit package, @@ -181,4 +182,4 @@ After installation, use the component demos or component-specific guidance for A - [Split Blazor Web App registration](./references/split-webapp-registration.md) - [Theme and host files](./references/theme-and-host-files.md) - [Render modes explained](./references/render-modes.md) -- [Troubleshooting guide](./references/troubleshooting.md) \ No newline at end of file +- [Troubleshooting guide](./references/troubleshooting.md) diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md index cc866e8cff..7bfc5c318d 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md @@ -11,7 +11,7 @@ **Diagnosis**: 1. Check the correct host file for your project type: - - Blazor Web App / modern Blazor Server: `App.razor` + - Blazor Web App: `Components/App.razor` - Legacy Blazor Server: `_Host.cshtml` - Blazor WebAssembly: `wwwroot/index.html` 2. Look for the CSS link in the `` section: @@ -29,7 +29,7 @@ - Wrong path: `_content/Syncfusion.Blazor.Toolkit/themes/fluent.min.css` (should be `styles/`) - Wrong stylesheet name: `bootstrap5.min.css`, `tailwind.min.css`, `material.min.css` (use `fluent.min.css` or `highcontrast.min.css`) - Missing `.min` extension: `fluent.css` (should be `.min.css`) -- Linked in wrong host file: use `App.razor` for Blazor Web App/Server or `wwwroot/index.html` for WebAssembly +- Linked in wrong host file: use `Components/App.razor` for a Blazor Web App, `_Host.cshtml` for legacy Blazor Server, or `wwwroot/index.html` for standalone WebAssembly - Linked in a component file instead of the host file (always place it in the host file's `` section for best results) **Fix**: @@ -256,16 +256,12 @@ Also ensure both projects have the NuGet package reference in their `.csproj` fi Before troubleshooting further, verify: -1. ✓ Package name is `Syncfusion.Blazor.Toolkit` (not commercial packages) -2. ✓ `AddSyncfusionBlazorToolkit()` is in `Program.cs` (both in split Web Apps) -3. ✓ `@using Syncfusion.Blazor.Toolkit` is in `_Imports.razor` (both in split Web Apps) -4. ✓ Theme CSS link is `fluent.min.css` in the correct host file (`App.razor` for Blazor Server/Web App or `wwwroot/index.html` for Blazor WebAssembly) -5. ✓ Theme filename is exactly `fluent.min.css` (not other theme names) -6. ✓ Interactive components have `@rendermode InteractiveServer`, `@rendermode InteractiveWebAssembly`, or `@rendermode InteractiveAuto` -7. ✓ No license-key registration code is present -8. ✓ Build completes without errors: `dotnet build` -9. ✓ Browser console shows no 404 or JavaScript errors -Stylesheet link is `fluent.min.css` or `highcontrast.min.css` in the host file (`Components/App.razor`, `_Host.cshtml`, or `wwwroot/index.html`) +1. ✓ Package name is `Syncfusion.Blazor.Toolkit` (not a commercial `Syncfusion.Blazor.*` package) +2. ✓ `using Syncfusion.Blazor.Toolkit;` and `AddSyncfusionBlazorToolkit()` are in `Program.cs` (in both Server and Client projects of a split Web App) +3. ✓ `@using Syncfusion.Blazor.Toolkit` is in `_Imports.razor` (in both projects of a split Web App) +4. ✓ Stylesheet link is `fluent.min.css` or `highcontrast.min.css` in the host file (`Components/App.razor` for a Blazor Web App, `Pages/_Host.cshtml` for legacy Blazor Server, `wwwroot/index.html` for standalone WebAssembly) 5. ✓ Path uses `styles/`, not `themes/`, and keeps the `.min` extension 6. ✓ Blazor Web App interactivity is inherited from `Routes` or declared once. Do not add `@rendermode` to legacy Server or standalone WebAssembly -7. ✓ Commercial packages and `SyncfusionLicenseProvider.RegisterLicense(...)` remain only where commercial components are still used \ No newline at end of file +7. ✓ Commercial packages and `SyncfusionLicenseProvider.RegisterLicense(...)` remain only where commercial components are still used +8. ✓ Build completes without errors: `dotnet build` +9. ✓ Browser console shows no 404 or JavaScript errors diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml index 72cbb37434..1707a609c8 100644 --- a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -36,6 +36,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)(RegisterLicense\s*\(|AddSyncfusionLicense\s*\(|enter (your|a) license key|provide (your|a) license key) + - type: prompt rubric: - Installs the open-source Toolkit package and registers its extension method with the namespace in scope. - Links the Fluent stylesheet from the package's styles directory in the legacy Server host file. @@ -68,6 +69,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)(put|place|link|add)[\s\S]{0,80}(stylesheet|link|css)[\s\S]{0,40}App\.razor + - type: prompt rubric: - Uses index.html as the stylesheet host for a standalone WebAssembly app. - Registers the root component only because this is a standalone app, not a Web App Client project. @@ -97,6 +99,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)RootComponents\.Add\("#app"\) + - type: prompt rubric: - Registers Toolkit in both the server and Client hosts when both render Toolkit components. - Keeps server registration because prerendering executes Client components on the server. @@ -124,6 +127,7 @@ stimuli: - type: output-not-contains config: substring: install a different package + - type: prompt rubric: - Diagnoses a missing or misplaced stylesheet rather than a package problem. - Gives a package stylesheet path and a host file that matches the app type. @@ -147,6 +151,7 @@ stimuli: - type: output-not-contains config: substring: static SSR is sufficient + - type: prompt rubric: - Checks whether the page already inherits an interactive mode before treating it as static. - Recommends one interactive mode when none is inherited, without requiring every mode to be named. @@ -176,6 +181,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)(switch|transition|continue)[\s\S]{0,60}(mid-|while running|same component) + - type: prompt rubric: - Describes Auto as server interactivity on the first visit and WebAssembly on later cached visits. - Does not describe a running component switching runtimes. @@ -203,6 +209,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)AddSyncfusionLicense\s*\( + - type: prompt rubric: - Identifies the installed package as the commercial package and replaces it for this Toolkit-only app. - Names the real commercial license API and states that Toolkit does not need a license key. @@ -230,6 +237,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)RootComponents\.Add\("#app"\) + - type: prompt rubric: - Adds the missing Client registration without removing the server registration. - Does not add a standalone WebAssembly root component to the Client project. @@ -256,6 +264,7 @@ stimuli: - type: output-not-contains config: substring: downgrade + - type: prompt rubric: - Diagnoses script loading or service registration before changing packages. - Points at console, network, or static-asset evidence rather than a version rollback. @@ -281,6 +290,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)href="_content/Syncfusion\.Blazor\.Toolkit/[^"]*bootstrap5 + - type: prompt rubric: - Replaces the unsupported stylesheet with the default Fluent file or the high-contrast file. - Does not recommend the bootstrap5 path as the fix. @@ -302,6 +312,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)/themes/fluent\.css + - type: prompt rubric: - Corrects both the directory and the filename, including the minified extension. @@ -325,6 +336,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)(fluent theme only|only the fluent theme) + - type: prompt rubric: - Treats the 404s as missing package assets or registration, not as a theme-choice problem. - Recommends verifying the package, registration, and a clean rebuild. @@ -348,6 +360,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)keep the cdn script + - type: prompt rubric: - Removes the external script tag and explains that the package loads its own JavaScript. - Does not accept leaving the CDN script in place. @@ -365,6 +378,7 @@ stimuli: - type: output-not-matches config: pattern: (?i)(first|before answering|instead)[\s\S]{0,80}(install the package|AddSyncfusionBlazorToolkit|follow these installation steps) + - type: prompt rubric: - The install skill stayed dormant: answer the chart API question or point to component documentation. - Does not hijack the question with package installation, Program.cs registration, or theme setup. From a553038b0c1e309cbbb90449fbcea246ef8b7531 Mon Sep 17 00:00:00 2001 From: Prince Oliver <31838171+PrinceOliver@users.noreply.github.com> Date: Wed, 7 Oct 2026 12:53:30 +0530 Subject: [PATCH 05/27] Make Toolkit install eval graders negation-safe per Copilot review --- .../eval.yaml | 34 +++---------------- 1 file changed, 5 insertions(+), 29 deletions(-) diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml index 1707a609c8..2384694f70 100644 --- a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -32,10 +32,10 @@ stimuli: pattern: (?i)_content/Syncfusion\.Blazor\.Toolkit/styles/fluent\.min\.css - type: output-not-matches config: - pattern: (?i)Syncfusion\.Blazor(?!\.Toolkit)\b + pattern: (?i)(dotnet add package|PackageReference Include=\"?)\s*Syncfusion\.Blazor(?!\.Toolkit)\b - type: output-not-matches config: - pattern: (?i)(RegisterLicense\s*\(|AddSyncfusionLicense\s*\(|enter (your|a) license key|provide (your|a) license key) + pattern: (?i)\b(enter|provide|paste|add|register) (your|a) (syncfusion )?license key - type: prompt rubric: - Installs the open-source Toolkit package and registers its extension method with the namespace in scope. @@ -65,10 +65,7 @@ stimuli: pattern: (?i)RootComponents\.Add\("#app"\) - type: output-not-matches config: - pattern: (?i)@rendermode - - type: output-not-matches - config: - pattern: (?i)(put|place|link|add)[\s\S]{0,80}(stylesheet|link|css)[\s\S]{0,40}App\.razor + pattern: (?im)^\s*@rendermode\s+Interactive - type: prompt rubric: - Uses index.html as the stylesheet host for a standalone WebAssembly app. @@ -96,9 +93,6 @@ stimuli: - type: output-not-matches config: pattern: (?i)(only (in|on) (the )?server|client inherits|register only in server) - - type: output-not-matches - config: - pattern: (?i)RootComponents\.Add\("#app"\) - type: prompt rubric: - Registers Toolkit in both the server and Client hosts when both render Toolkit components. @@ -180,7 +174,7 @@ stimuli: pattern: (?i)AddSyncfusionBlazorToolkit - type: output-not-matches config: - pattern: (?i)(switch|transition|continue)[\s\S]{0,60}(mid-|while running|same component) + pattern: (?i)\b(does|will|can|would)\s+(switch|transition)\b[\s\S]{0,60}(mid-|while running|same component) - type: prompt rubric: - Describes Auto as server interactivity on the first visit and WebAssembly on later cached visits. @@ -206,9 +200,6 @@ stimuli: - type: output-matches config: pattern: (?i)(no|not|does not|doesn't)[\s\S]{0,40}license key - - type: output-not-matches - config: - pattern: (?i)AddSyncfusionLicense\s*\( - type: prompt rubric: - Identifies the installed package as the commercial package and replaces it for this Toolkit-only app. @@ -234,9 +225,6 @@ stimuli: - type: output-not-matches config: pattern: (?i)only (the )?server needs - - type: output-not-matches - config: - pattern: (?i)RootComponents\.Add\("#app"\) - type: prompt rubric: - Adds the missing Client registration without removing the server registration. @@ -283,13 +271,7 @@ stimuli: graders: - type: output-matches config: - pattern: (?i)styles/fluent\.min\.css - - type: output-matches - config: - pattern: (?i)highcontrast\.min\.css - - type: output-not-matches - config: - pattern: (?i)href="_content/Syncfusion\.Blazor\.Toolkit/[^"]*bootstrap5 + pattern: (?i)styles/(fluent|highcontrast)\.min\.css - type: prompt rubric: - Replaces the unsupported stylesheet with the default Fluent file or the high-contrast file. @@ -309,9 +291,6 @@ stimuli: - type: output-matches config: pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/fluent\.min\.css - - type: output-not-matches - config: - pattern: (?i)/themes/fluent\.css - type: prompt rubric: - Corrects both the directory and the filename, including the minified extension. @@ -357,9 +336,6 @@ stimuli: - type: output-matches config: pattern: (?i)(embedded|bundled|included in the (nuget )?package|ships with the package) - - type: output-not-matches - config: - pattern: (?i)keep the cdn script - type: prompt rubric: - Removes the external script tag and explains that the package loads its own JavaScript. From fb1f9829621020246fce5aecd0733bc22143e8b1 Mon Sep 17 00:00:00 2001 From: Prince Oliver <31838171+PrinceOliver@users.noreply.github.com> Date: Wed, 7 Oct 2026 13:02:48 +0530 Subject: [PATCH 06/27] Add Hybrid and project-creation dormancy cases; drop remaining substring negatives --- .../eval.yaml | 46 +++++++++++++++---- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml index 2384694f70..721bbb1080 100644 --- a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -118,9 +118,6 @@ stimuli: - type: output-matches config: pattern: (?i)Components/App\.razor|_Host\.cshtml|index\.html - - type: output-not-contains - config: - substring: install a different package - type: prompt rubric: - Diagnoses a missing or misplaced stylesheet rather than a package problem. @@ -142,9 +139,6 @@ stimuli: - type: output-matches config: pattern: (?i)(static|inherited|Routes) - - type: output-not-contains - config: - substring: static SSR is sufficient - type: prompt rubric: - Checks whether the page already inherits an interactive mode before treating it as static. @@ -249,9 +243,6 @@ stimuli: - type: output-matches config: pattern: (?i)(console|network|404|_content) - - type: output-not-contains - config: - substring: downgrade - type: prompt rubric: - Diagnoses script loading or service registration before changing packages. @@ -358,3 +349,40 @@ stimuli: rubric: - The install skill stayed dormant: answer the chart API question or point to component documentation. - Does not hijack the question with package installation, Program.cs registration, or theme setup. + + - name: out-of-scope-project-creation + tags: + capability: dormancy + risk: install-skill-hijack + journey: create-project + prompt: | + Scaffold a new Blazor Web App for an internal equipment-checkout tracker. It needs + per-page server interactivity and a simple list page. Walk me through creating the + project and what the solution layout should look like. + expect_activation: false + graders: + - type: output-not-matches + config: + pattern: (?i)(dotnet add package|PackageReference)[\s\S]{0,40}Syncfusion + - type: prompt + rubric: + - The install skill stayed dormant: the request is about creating a project, not installing a UI package. + - Answers with project creation and layout guidance without adding Syncfusion packages, registration, or theme links. + - Redirects package or component choices to a later step instead of assuming a UI library. + + - name: out-of-scope-hybrid-maui + tags: + capability: dormancy + risk: install-skill-hijack + journey: hybrid-boundary + prompt: | + I have a .NET MAUI Blazor Hybrid app that hosts its UI in a BlazorWebView. I'd like to use + the open-source Syncfusion Blazor Toolkit buttons in it. Where do I put the stylesheet + and how do I wire it up? + expect_activation: false + graders: + - type: prompt + rubric: + - The install skill stayed dormant: the app is a MAUI Blazor Hybrid app, which is outside this skill's scope. + - Recognizes the Hybrid boundary and does not apply the Web App, legacy Server, or standalone WebAssembly host-file steps. + - Redirects to the Hybrid or MAUI host page (such as wwwroot/index.html in the BlazorWebView) or to Hybrid-specific documentation. From 09d5823d9fd52a658ec2e725b60a2ac2616efaf2 Mon Sep 17 00:00:00 2001 From: Indhumathy-Loganathan Date: Wed, 7 Oct 2026 13:55:53 +0530 Subject: [PATCH 07/27] Added a deterministic grader. --- .../dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml index 721bbb1080..3d7084235b 100644 --- a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -381,6 +381,9 @@ stimuli: and how do I wire it up? expect_activation: false graders: + - type: output-not-matches + config: + pattern: (?i)(Components/App\.razor|_Host\.cshtml|@rendermode|RootComponents\.Add\("#app"\)|AddInteractive(Server|WebAssembly)|AddSyncfusionBlazorToolkit) - type: prompt rubric: - The install skill stayed dormant: the app is a MAUI Blazor Hybrid app, which is outside this skill's scope. From 65a085dda5b4acd5ed2e4bbab4fd72cc049e32b9 Mon Sep 17 00:00:00 2001 From: Indhumathy-Loganathan Date: Wed, 7 Oct 2026 19:20:04 +0530 Subject: [PATCH 08/27] Eval and Skill related review changes included. --- .../SKILL.md | 155 +++++++++--------- .../references/package-identity.md | 13 +- .../references/render-modes.md | 105 ++++-------- .../references/split-webapp-registration.md | 82 +++++---- .../references/theme-and-host-files.md | 65 +++----- .../references/troubleshooting.md | 105 +++++++----- .../eval.yaml | 135 +++++++++++++-- 7 files changed, 360 insertions(+), 300 deletions(-) diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md index a80c0b280d..876e2da24a 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md @@ -1,4 +1,4 @@ ---- +--- license: MIT name: syncfusion-blazor-toolkit-install description: > @@ -20,33 +20,41 @@ description: > ## Core Rules -1. Use the exact package ID `Syncfusion.Blazor.Toolkit`. -2. In every `Program.cs` that calls `AddSyncfusionBlazorToolkit()`, add `using Syncfusion.Blazor.Toolkit;` so the extension method is in scope. Call it before `builder.Build()`. -3. Import `@using Syncfusion.Blazor.Toolkit` in `_Imports.razor`; add component namespaces such as `@using Syncfusion.Blazor.Toolkit.Buttons` only when a component needs them. `_Imports.razor` does not affect `Program.cs`. -4. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` (or `highcontrast.min.css`) in the app host file. Fluent is the default. -5. Use `@rendermode` only in a Blazor Web App. Legacy Blazor Server and standalone WebAssembly are already interactive and do not use render modes. -6. In a split Blazor Web App, the `.Client` project is not a standalone WASM app. Do not call `RootComponents.Add("#app")` there. Register Toolkit on every host that renders Toolkit components, including the server when prerendering is left on. -7. Do not add a commercial `Syncfusion.Blazor*` package to satisfy a Toolkit request. If the app already uses commercial components, leave those packages and `Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(...)` in place. -8. Toolkit JavaScript is embedded in the NuGet package; do not add commercial script tags. -9. Keep this skill install-focused; use the references for details and troubleshooting. +1. **Verify the target framework first.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0` only. Read `` in the app's `.csproj` before installing. On `net6.0`, `net7.0`, or older, NuGet restore still succeeds but supplies no assemblies, so the build later fails with `CS0246` on `Syncfusion`. Do not install; recommend upgrading to .NET 8 or later first (for example with the `dotnet-upgrade` plugin) and resume afterward. Never edit the TFM just to make the package install. +2. Use the exact package ID `Syncfusion.Blazor.Toolkit`. +3. In every `Program.cs` that calls `AddSyncfusionBlazorToolkit()`, add `using Syncfusion.Blazor.Toolkit;` so the extension method is in scope. Call it before `builder.Build()`. +4. Component types live in child namespaces, not the root. Add the namespace for each component to `_Imports.razor` (for example `@using Syncfusion.Blazor.Toolkit.Buttons` for `SfButton`). A missing namespace does not fail the build: Razor warns `RZ10012` and renders the tag as an unknown HTML element. The root `@using Syncfusion.Blazor.Toolkit` is optional and only needed to name its enums. `_Imports.razor` does not affect `Program.cs`. +5. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` (or `highcontrast.min.css`) in the app host file. Fluent is the default. Add the link to the host file's ``; do not replace the whole host file. +6. Use `@rendermode` only in a Blazor Web App. Legacy Blazor Server and standalone WebAssembly are already interactive and do not use render modes. +7. Toolkit components need `AddSyncfusionBlazorToolkit()` on **every host that renders them, including static SSR**. Without it the page returns HTTP 500 with `There is no registered service of type 'Syncfusion.Blazor.Toolkit.SyncfusionBlazorToolkitService'`. In a split Blazor Web App, register on the server and in `.Client`: prerendering runs `.Client` components on the server, so client-only registration still returns 500. +8. In a split Blazor Web App, the `.Client` project is not a standalone WASM app. Do not call `RootComponents.Add("#app")` there. Keep the `.AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` call the template puts on `MapRazorComponents()`; the server needs it to see `.Client` pages. It is unrelated to Toolkit, so never add, remove, or move it. +9. Do not add a commercial `Syncfusion.Blazor*` package to satisfy a Toolkit request. If the app already uses commercial components, leave those packages and `Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(...)` in place. +10. Toolkit JavaScript is embedded in the NuGet package; do not add commercial script tags. +11. Keep this skill install-focused; use the references for details and troubleshooting. ## Don'ts +- Don't install the Toolkit on a .NET 6 or .NET 7 project. Recommend upgrading first. - Don't treat `Syncfusion.Blazor` or component-specific commercial packages as Toolkit dependencies. - Don't add external script tags or commercial Syncfusion license scripts; Toolkit JS is bundled with the package. - Don't rely on static SSR when the component must respond to clicks, binding, or dynamic updates. - Don't use this skill as a component API reference; consult the official Syncfusion Blazor Toolkit demos or documentation for API details. +- Don't replace or retype `Program.cs`, `App.razor`, `_Host.cshtml`, or `wwwroot/index.html`. Make only the additions shown below and leave every other template line (`UseExceptionHandler`, `UseHsts`, `MapStaticAssets`, `HeadOutlet`, `Routes`, render-mode directives, script tags) untouched. ## Quick Decision Table -| Scenario | Package | Program.cs | Host file for CSS | Interactivity | +Pick the **single** row that matches the app the user is on. The "Program.cs" columns say where `AddSyncfusionBlazorToolkit()` goes; the template's own endpoint calls stay as generated. + +| Scenario | Register in server `Program.cs` | Register in `.Client/Program.cs` | Host file for CSS | Interactivity | | --- | --- | --- | --- | --- | -| Blazor Server (legacy `_Host.cshtml`) | `Syncfusion.Blazor.Toolkit` | `using Syncfusion.Blazor.Toolkit;` then `builder.Services.AddSyncfusionBlazorToolkit()` | `_Host.cshtml` | Already interactive (no `@rendermode`) | -| Blazor WebAssembly (standalone) | `Syncfusion.Blazor.Toolkit` | `using Syncfusion.Blazor.Toolkit;` then `builder.Services.AddSyncfusionBlazorToolkit()` | `wwwroot/index.html` | Already interactive (no `@rendermode`; not static SSR) | -| Blazor Web App, global Interactive Server | `Syncfusion.Blazor.Toolkit` | Server `Program.cs` only, with the using above | `Components/App.razor` | Inherited from `Routes`; do not add a different child mode | -| Blazor Web App, per-page or per-component | `Syncfusion.Blazor.Toolkit` | Every host that renders the component, including the server while prerendering is on | `Components/App.razor` | One interactive mode: `InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto` | -| Blazor Web App (split Server/Client) | `Syncfusion.Blazor.Toolkit` | Server and `.Client` when both render Toolkit. No `RootComponents.Add` in `.Client` | `Components/App.razor` | Same mode as the parent page; a child cannot switch interactive modes | -| Static SSR only (Blazor Web App) | `Syncfusion.Blazor.Toolkit` | Server `Program.cs` if any Toolkit markup is rendered | `Components/App.razor` | None; read-only only. Standalone WASM is not this row | +| Legacy Blazor Server (`_Host.cshtml`, .NET 8+ only for Toolkit) | Yes | n/a | `_Host.cshtml` | Already interactive (no `@rendermode`) | +| Standalone Blazor WebAssembly | n/a | Yes, in the standalone `Program.cs`; it keeps its own `RootComponents.Add("#app")` | `wwwroot/index.html` | Already interactive (no `@rendermode`; not static SSR) | +| Blazor Web App, `-int Server` | Yes | n/a (no `.Client` project) | `Components/App.razor` | Inherited from `Routes`; do not add a different child mode | +| Blazor Web App, `-int WebAssembly` | Yes | Yes; **no** `RootComponents.Add` | `Components/App.razor` | WebAssembly; prerendered on the server first | +| Blazor Web App, `-int Auto` | Yes | Yes; **no** `RootComponents.Add` | `Components/App.razor` | First visit server, later visits cached WebAssembly; a running component does not switch | +| Blazor Web App, per-page modes | Yes (prerendering runs there) | Yes, if `.Client` renders the component | `Components/App.razor` | One mode per component; a child cannot switch interactive modes | +| Static SSR only (Blazor Web App) | Yes, if any Toolkit markup is rendered | n/a | `Components/App.razor` | None; read-only only. Standalone WASM is not this row | +| .NET MAUI Blazor Hybrid | **Out of scope** (see below) | n/a | n/a | n/a | ## Minimal Setup @@ -56,121 +64,112 @@ description: > dotnet add package Syncfusion.Blazor.Toolkit ``` -### Program.cs +### Program.cs: make only these additions -Match the render modes from the Quick Decision Table above. Do not add unused render modes. +Every template (`-int Server`, `-int WebAssembly`, `-int Auto`) already generates its own `AddRazorComponents()`, `Map*` and `AddAdditionalAssemblies(...)` calls. **Do not retype or replace them.** Pasting a trimmed `Program.cs` drops `using .Components;` (so `App` stops resolving, `CS0246`) and removes `UseExceptionHandler`, `UseHsts`, `UseHttpsRedirection`, the static-asset mapping (`MapStaticAssets` on .NET 9+, `UseStaticFiles` on .NET 8) and `app.Run()`. -**Blazor Web App server `Program.cs` (Auto, WebAssembly, or split)**: - -Keep the interactive services the template already generated. Register Toolkit here even when the component lives in `.Client`, because default prerendering runs it on the server. +**Server `Program.cs`** (all three Web App templates and legacy Server). Add one `using` at the top and one line before `var app = builder.Build();`: ```csharp -using Syncfusion.Blazor.Toolkit; - -var builder = WebApplication.CreateBuilder(args); +using Syncfusion.Blazor.Toolkit; // add at the top, with the other usings -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents() - .AddInteractiveWebAssemblyComponents(); +// ...the template's builder.Services.AddRazorComponents()... stays exactly as generated... -builder.Services.AddSyncfusionBlazorToolkit(); +builder.Services.AddSyncfusionBlazorToolkit(); // add just before builder.Build() var app = builder.Build(); - -app.MapRazorComponents() - .AddInteractiveServerRenderMode() - .AddInteractiveWebAssemblyRenderMode(); ``` -**Blazor Web App server `Program.cs` (Interactive Server only)**: - -Do not add WebAssembly services unless the project already references `Microsoft.AspNetCore.Components.WebAssembly.Server`. - -```csharp -using Syncfusion.Blazor.Toolkit; - -var builder = WebApplication.CreateBuilder(args); - -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents(); - -builder.Services.AddSyncfusionBlazorToolkit(); +What the template already contains (leave it alone): -var app = builder.Build(); - -app.MapRazorComponents() - .AddInteractiveServerRenderMode(); -``` +| Template | `AddRazorComponents()` chain | `MapRazorComponents()` chain | +| --- | --- | --- | +| `-int Server` | `.AddInteractiveServerComponents()` | `.AddInteractiveServerRenderMode()` | +| `-int WebAssembly` | `.AddInteractiveWebAssemblyComponents()` | `.AddInteractiveWebAssemblyRenderMode()` and `.AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` | +| `-int Auto` | `.AddInteractiveServerComponents()` and `.AddInteractiveWebAssemblyComponents()` | `.AddInteractiveServerRenderMode()`, `.AddInteractiveWebAssemblyRenderMode()` and `.AddAdditionalAssemblies(...)` | -**Blazor Web App `.Client/Program.cs`**: +Never mix these shapes. Do not add `AddInteractiveServerComponents()` to a WebAssembly template, or remove it from an Auto template; Toolkit does not need either change. -This project is not a standalone WASM app. The server owns `App.razor`, and the host page has no `#app` element, so do not register a root component here. +**Blazor Web App `.Client/Program.cs`** (`-int WebAssembly`, `-int Auto`). The template already has `using Microsoft.AspNetCore.Components.WebAssembly.Hosting;`. Add the Toolkit using and one line before `await builder.Build().RunAsync();`: ```csharp -using Syncfusion.Blazor.Toolkit; +using Microsoft.AspNetCore.Components.WebAssembly.Hosting; // already generated; keep it +using Syncfusion.Blazor.Toolkit; // add var builder = WebAssemblyHostBuilder.CreateDefault(args); -builder.Services.AddSyncfusionBlazorToolkit(); +builder.Services.AddSyncfusionBlazorToolkit(); // add await builder.Build().RunAsync(); ``` -**Standalone Blazor WebAssembly `Program.cs`**: - -```csharp -using Syncfusion.Blazor.Toolkit; +This project is not a standalone WASM app. The server owns `App.razor` and the host page has no `#app` element, so do not register a root component here. -var builder = WebAssemblyHostBuilder.CreateDefault(args); +**Standalone Blazor WebAssembly `Program.cs`**. The template already contains the usings and both `RootComponents.Add` lines. Add only the Toolkit using and the registration: -builder.RootComponents.Add("#app"); -builder.RootComponents.Add("head::after"); +```csharp +using Syncfusion.Blazor.Toolkit; // add -builder.Services.AddSyncfusionBlazorToolkit(); +// ...template: builder.RootComponents.Add("#app"); builder.RootComponents.Add("head::after");... -await builder.Build().RunAsync(); +builder.Services.AddSyncfusionBlazorToolkit(); // add, before Build() ``` ### _Imports.razor -```razor -@using Syncfusion.Blazor.Toolkit +Add one `@using` per component family you render. In a split Web App add it to the `_Imports.razor` of **every project that renders the component** (server `Components/_Imports.razor` and `.Client/_Imports.razor`). -@* Optional: add component-specific namespaces only when using those components *@ -@* @using Syncfusion.Blazor.Toolkit.Buttons *@ -@* @using Syncfusion.Blazor.Toolkit.Calendars *@ +```razor +@using Syncfusion.Blazor.Toolkit.Buttons +@* Other families in 1.0.2: Calendars, Charts, Inputs, Popups (SfDialog, SfTooltip), Spinner *@ ``` -`_Imports.razor` does not put the namespace in scope for `Program.cs`. - ### Host file CSS +Add this single line to the `` of the existing host file. **Do not replace the rest of the file**: keep `HeadOutlet`, `Routes` and its render-mode directive, and the existing script tag (`_framework/blazor.web.js`, `_framework/blazor.webassembly.js`, or `blazor.server.js`) exactly as the template generated them. + ```html ``` -Pick the host file from the Quick Decision Table: `_Host.cshtml` for legacy Blazor Server, `Components/App.razor` for a Blazor Web App, or `wwwroot/index.html` for standalone WebAssembly. Use `highcontrast.min.css` only when the user asks for high contrast. +Pick the host file from the Quick Decision Table. Use `highcontrast.min.css` only when the user asks for high contrast. `SfNumericTextBox` additionally needs `numerictextbox.min.css`, because its selectors are not in the Fluent or High Contrast bundle. See [Theme and host files](./references/theme-and-host-files.md). + +## Hybrid / MAUI boundary + +This skill does not cover .NET MAUI Blazor Hybrid. When a user asks, explain the boundary instead of applying Web App steps. Verified against the `maui-blazor` template: + +- There is no `App.razor`, `_Host.cshtml`, `HeadOutlet`, or render mode. The UI runs in a `BlazorWebView` declared in `MainPage.xaml`. +- The host page is `wwwroot/index.html`, with a `
` root wired through ``. It loads `_framework/blazor.webview.js`. +- Services are registered in `MauiProgram.cs`, after `builder.Services.AddMauiBlazorWebView();`. +- The Toolkit's `net10.0` assets resolve for a platform TFM such as `net10.0-windows10.0.19041.0`. Android, iOS and Mac Catalyst were not verified, so point the user to Hybrid-specific documentation rather than promising support. ## Common Mistakes | Mistake | Symptom | Fix | | --- | --- | --- | +| Toolkit installed on .NET 6 or .NET 7 | Restore succeeds, then the build fails with `CS0246` on `Syncfusion` (no assemblies are supplied) | Upgrade the app to .NET 8 or later first. Never change the TFM just to make the package install | +| `AddSyncfusionBlazorToolkit()` missing on a host that renders Toolkit | HTTP 500: `no registered service of type ...SyncfusionBlazorToolkitService` | Register on every rendering host, including the server for `.Client` components and for static SSR | | CSS path uses `themes/` or omits `.min` | Components are unstyled (404 in browser DevTools) | Use `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` | -| CSS linked in a component file instead of the host file | Styling doesn't apply consistently | Move the `` to the host file `` from the Quick Decision Table | +| CSS linked in a component file instead of the host file | Styling doesn't apply consistently | Move the `` to the host file `` | +| Host file replaced wholesale instead of adding the link | `HeadOutlet`, `Routes`, or the render-mode directive is lost; events stop firing | Restore the template-generated file, then add only the `` line | +| `Program.cs` retyped from a trimmed sample | `CS0246` on `App`, and `UseExceptionHandler`, `UseHsts`, `MapStaticAssets` and `app.Run()` are lost | Restore the template file, then add only the `using` and the registration line | +| Template's `AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` deleted from `MapRazorComponents()` | Routable pages in `.Client` return 404 | Restore the call exactly as the template generated it | | Commercial package added for a Toolkit-only app | License prompt, missing Toolkit components | Replace that package with `Syncfusion.Blazor.Toolkit`. If other pages still use commercial components, keep those packages and `SyncfusionLicenseProvider.RegisterLicense(...)` | +| Component namespace missing | Razor warning `RZ10012`; `` renders as an unstyled unknown element that ignores events | Add the child namespace, for example `@using Syncfusion.Blazor.Toolkit.Buttons`, to `_Imports.razor` of the project that renders it | | Added an external Syncfusion CDN script tag | JavaScript conflicts or duplicate library errors | Remove the CDN script; Toolkit JS ships in the NuGet package | | `@rendermode` missing, and no interactive mode is inherited | Clicks and binding do nothing on a Blazor Web App page | Apply one interactive mode, or inherit the mode already on `Routes` | | `@rendermode` added to standalone WASM or legacy Server | No effect, and it can look like a fix | Remove it; those apps are already interactive | | Child `@rendermode` differs from the parent interactive mode | Runtime error; a child cannot switch interactive modes | Match the inherited mode, or move the component to a page with the intended mode | +| Auto or WebAssembly endpoint removed from a split Web App | Client components never load, or load only after a server round-trip | Keep the endpoints the template generated | | `RootComponents.Add("#app")` added to `.Client` | The Client host has no `#app` element | Remove it. That call belongs only in standalone WebAssembly | ## Top Failure Symptoms -- **Unstyled components**: the stylesheet link is missing, wrong, or placed in the wrong host file. See [Theme and host files](./references/theme-and-host-files.md). -- **Services not configured**: `AddSyncfusionBlazorToolkit()` or its `using Syncfusion.Blazor.Toolkit;` is missing from a `Program.cs` that renders Toolkit. See [Troubleshooting guide](./references/troubleshooting.md). +- **Unstyled components**: the stylesheet link is missing, wrong, or in the wrong host file; or a component namespace is missing (`RZ10012`). See [Theme and host files](./references/theme-and-host-files.md). +- **HTTP 500 mentioning `SyncfusionBlazorToolkitService`**: `AddSyncfusionBlazorToolkit()` is missing on a host that renders Toolkit. See [Troubleshooting guide](./references/troubleshooting.md). - **Clicks or inputs do nothing**: check for an inherited render mode before editing the page. If none exists, the page is static SSR. See [Render modes explained](./references/render-modes.md). -- **Only one half of a split app works**: register Toolkit on every host that renders it, including the server while prerendering is on. See [Split Blazor Web App registration](./references/split-webapp-registration.md). -- **License prompt after installing `Syncfusion.Blazor`**: that is the commercial package. See [Package identity and splits](./references/package-identity.md) before removing anything the app still uses. +- **Only one half of a split app works**: register Toolkit on both hosts. See [Split Blazor Web App registration](./references/split-webapp-registration.md). +- **License prompt after installing `Syncfusion.Blazor`**: that is the commercial package. See [Package identity](./references/package-identity.md) before removing anything the app still uses. ## Next Steps @@ -178,7 +177,7 @@ After installation, use the component demos or component-specific guidance for A ## References -- [Package identity and splits](./references/package-identity.md) +- [Package identity](./references/package-identity.md) - [Split Blazor Web App registration](./references/split-webapp-registration.md) - [Theme and host files](./references/theme-and-host-files.md) - [Render modes explained](./references/render-modes.md) diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md index 8f66059170..64279e5306 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md @@ -1,15 +1,14 @@ -# Install Syncfusion Blazor Toolkit +# Package Identity Reference -## Package Identity Reference +## Syncfusion.Blazor.Toolkit vs. commercial Syncfusion.Blazor* -### Syncfusion.Blazor.Toolkit vs. Commercial Syncfusion.Blazor* +### The open-source Toolkit: Syncfusion.Blazor.Toolkit -### The Open-Source Toolkit: Syncfusion.Blazor.Toolkit - -- **NuGet package name**: `Syncfusion.Blazor.Toolkit` +- **NuGet package name**: `Syncfusion.Blazor.Toolkit` (verified at version 1.0.2) - **License**: MIT +- **Target frameworks**: `net8.0`, `net9.0`, `net10.0` - **Scope**: Open-source Blazor toolkit for the current published component set -- **Repository**: Official Syncfusion GitHub repository +- **Repository**: https://github.com/syncfusion/blazor-toolkit - **Components included**: Refer to the official Syncfusion Blazor Toolkit documentation for the authoritative and current component list. This skill is not a component reference. - **No license key required**: Toolkit is free to use without registration diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md index 178a473e64..7aa5bcb987 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md @@ -1,26 +1,27 @@ -# Render Modes Reference +# Render Modes Reference Blazor supports multiple render modes. Toolkit components need an interactive mode whenever they handle clicks, binding, or other live updates. +> **Framework support.** The Toolkit targets `net8.0`, `net9.0`, and `net10.0`. If `` is older, recommend upgrading first: restore succeeds on `net7.0` and earlier but supplies no assemblies, so the build fails with `CS0246`. + +> **Namespaces.** `SfButton` lives in `Syncfusion.Blazor.Toolkit.Buttons`, so each sample below includes `@using Syncfusion.Blazor.Toolkit.Buttons`. If it is already in `_Imports.razor`, the per-page line can be dropped. + +Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInteractive*` and `AddAdditionalAssemblies(...)` call exactly as the project template generated it; do not add or remove them for Toolkit. + ## Static SSR (Server-Side Rendering) **When to use**: Read-only content where no user interaction or dynamic updates are needed. **Characteristic**: Components are rendered on the server and sent as HTML; no .NET code runs on the client. -**Toolkit limitation**: **Static SSR is not sufficient for interactive Toolkit components** (buttons, forms, dropdowns, etc.). Event handlers and state changes will not work. +**Toolkit limitation**: Static SSR is not sufficient for interactive Toolkit components (buttons, forms, inputs, etc.). Event handlers and state changes will not work. Toolkit services are still required: a static page that renders `SfButton` returns HTTP 500 without `AddSyncfusionBlazorToolkit()`. **Example (read-only only)**: ```razor -@page "/counter" +@page "/status" +@using Syncfusion.Blazor.Toolkit.Buttons -

This counter is stuck at: @count

-Click doesn't work in SSR - -@code { - private int count = 0; - // @onclick handlers don't fire in static SSR -} +Read-only button ``` ## Interactive Server Rendering @@ -35,9 +36,10 @@ Blazor supports multiple render modes. Toolkit components need an interactive mo ```razor @page "/counter" @rendermode InteractiveServer +@using Syncfusion.Blazor.Toolkit.Buttons

Count: @count

-Increment +Increment @code { private int count = 0; @@ -45,23 +47,7 @@ Blazor supports multiple render modes. Toolkit components need an interactive mo } ``` -**Server-only template setup**. Do not add WebAssembly services here; a server-only project may not reference `Microsoft.AspNetCore.Components.WebAssembly.Server`. - -```csharp -using Syncfusion.Blazor.Toolkit; - -var builder = WebApplication.CreateBuilder(args); - -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents(); - -builder.Services.AddSyncfusionBlazorToolkit(); - -var app = builder.Build(); - -app.MapRazorComponents() - .AddInteractiveServerRenderMode(); -``` +**Server `Program.cs`** (`dotnet new blazor -int Server`): leave the template's `AddInteractiveServerComponents()` and `AddInteractiveServerRenderMode()` as generated, and add only `using Syncfusion.Blazor.Toolkit;` plus `builder.Services.AddSyncfusionBlazorToolkit();` before `builder.Build()`. Do not add WebAssembly services to this template. ## Interactive WebAssembly Rendering @@ -75,9 +61,10 @@ app.MapRazorComponents() ```razor @page "/counter" @rendermode InteractiveWebAssembly +@using Syncfusion.Blazor.Toolkit.Buttons

Count: @count

-Increment +Increment @code { private int count = 0; @@ -85,46 +72,26 @@ app.MapRazorComponents() } ``` -**`.Client/Program.cs`** (not a standalone app; no root component): -```csharp -using Syncfusion.Blazor.Toolkit; - -var builder = WebAssemblyHostBuilder.CreateDefault(args); - -builder.Services.AddSyncfusionBlazorToolkit(); - -await builder.Build().RunAsync(); -``` - -**Standalone WebAssembly `Program.cs`**: -```csharp -using Syncfusion.Blazor.Toolkit; +**Server and `.Client` `Program.cs`** (`dotnet new blazor -int WebAssembly`): the template registers WebAssembly endpoints only. Keep them, and keep `AddAdditionalAssemblies(...)` on `MapRazorComponents()`. Add `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` to **both** the server and `.Client/Program.cs` (prerendering runs the component on the server). Do not add `RootComponents.Add("#app")` to `.Client`. See [Split Blazor Web App registration](./split-webapp-registration.md). -var builder = WebAssemblyHostBuilder.CreateDefault(args); - -builder.RootComponents.Add("#app"); -builder.RootComponents.Add("head::after"); - -builder.Services.AddSyncfusionBlazorToolkit(); - -await builder.Build().RunAsync(); -``` +**Standalone WebAssembly `Program.cs`** (no Web App, no `.Client` project): the template already has `RootComponents.Add("#app")` and `RootComponents.Add("head::after")`. Add only `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` before `Build()`. ## Interactive Auto Rendering **When to use**: A Blazor Web App that should use server interactivity on the first visit, then WebAssembly on later visits once the runtime bundle is downloaded and cached. -**Characteristic**: Auto chooses the runtime per visit. A component that is already running does not switch from server to WebAssembly mid-circuit. See the render-mode documentation: https://learn.microsoft.com/aspnet/core/blazor/components/render-modes +**Characteristic**: Auto chooses the runtime per visit. A component that is already running does not switch from server to WebAssembly mid-circuit. See https://learn.microsoft.com/aspnet/core/blazor/components/render-modes **Toolkit requirement**: Fully supported. Register Toolkit in both the server and `.Client` projects, because the first visit renders on the server and later visits render in WebAssembly. -**Example**: +**Example** (page-level `@rendermode InteractiveAuto`): ```razor @page "/counter" @rendermode InteractiveAuto +@using Syncfusion.Blazor.Toolkit.Buttons

Count: @count

-Increment +Increment @code { private int count = 0; @@ -132,26 +99,7 @@ await builder.Build().RunAsync(); } ``` -**Server setup** (keep both interactive endpoints; this is the combined hosting case, not the server-only case): -```csharp -using Syncfusion.Blazor.Toolkit; - -var builder = WebApplication.CreateBuilder(args); - -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents() - .AddInteractiveWebAssemblyComponents(); - -builder.Services.AddSyncfusionBlazorToolkit(); - -var app = builder.Build(); - -app.MapRazorComponents() - .AddInteractiveServerRenderMode() - .AddInteractiveWebAssemblyRenderMode(); -``` - -Also call `AddSyncfusionBlazorToolkit()` in `.Client/Program.cs`. Do not add `RootComponents.Add("#app")` there. +**Server and `.Client` `Program.cs`** (`dotnet new blazor -int Auto`): the template registers both Interactive Server and Interactive WebAssembly, and `AddAdditionalAssemblies(...)` on `MapRazorComponents()`. Keep all of it. Add `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` to **both** the server and `.Client/Program.cs`. Do not add `RootComponents.Add("#app")` to `.Client`. ## Decision Tree @@ -175,5 +123,8 @@ Also call `AddSyncfusionBlazorToolkit()` in `.Client/Program.cs`. Do not add `Ro 1. **Adding `@rendermode` under an inherited mode**: If `Routes` already has an interactive mode, a child that names a different one fails. Match the parent or move the component. 2. **Treating standalone WebAssembly as static SSR**: It has no static SSR and no render-mode directive. 3. **Adding WebAssembly endpoints to a server-only project**: That project may not reference the WebAssembly server package. -4. **Describing Auto as a live runtime switch**: The first visit uses the server; later visits use the cached WebAssembly bundle. A running component does not migrate. -5. **Assuming a missing directive means the component is static**: Check the inherited mode first. +4. **Mixing the WebAssembly and Auto templates**: `-int WebAssembly` registers WebAssembly endpoints only; `-int Auto` registers both Server and WebAssembly. Keep the shape the template generated. +5. **Editing endpoints to "fit" Toolkit**: Toolkit needs only `AddSyncfusionBlazorToolkit()`. Do not add or remove `AddInteractive*` or `AddAdditionalAssemblies(...)` calls for it. +6. **Describing Auto as a live runtime switch**: The first visit uses the server; later visits use the cached WebAssembly bundle. A running component does not migrate. +7. **Assuming a missing directive means the component is static**: Check the inherited mode first. + diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md index a40a7f97a2..b9641ac52a 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md @@ -1,82 +1,80 @@ -# Split Blazor Web App Service Registration +# Split Blazor Web App Service Registration -A generated `.Client` project is not a standalone WebAssembly app. The server owns `App.razor`, and the host markup has no `#app` element. Never call `RootComponents.Add("#app")` in `.Client/Program.cs`. - -Default prerendering renders Interactive WebAssembly and Interactive Auto components on the server first. If the server does not have Toolkit services, that first render fails even when `.Client` is registered correctly. Disable prerendering only when the user explicitly asks; otherwise register Toolkit on both hosts. +`Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Check `` in **both** projects first; if either is older, upgrade before installing. -`dotnet new blazor -int Auto` and `dotnet new blazor -int WebAssembly` already add interactive server and WebAssembly endpoints on the server. Keep those endpoints. A server-only Interactive Server app should not gain WebAssembly endpoints just to host Toolkit. +A generated `.Client` project is not a standalone WebAssembly app. The server owns `App.razor`, and the host markup has no `#app` element. Never call `RootComponents.Add("#app")` in `.Client/Program.cs`. -## Scenario 1: Interactive Server only +## Both hosts must register Toolkit -The server does not host Client components, so leave WebAssembly endpoints off. Do not add a `.Client` registration for components that project never renders, and do not add `RootComponents.Add("#app")`. +Default prerendering runs WebAssembly and Auto components on the server first. Verified: with `-int WebAssembly`, registering Toolkit **only** in `.Client` makes a `.Client` page return HTTP 500; adding the server registration returns 200. -**Server/Program.cs**: -```csharp -using Syncfusion.Blazor.Toolkit; +```text +System.InvalidOperationException: Cannot provide a value for property 'SyncfusionService' on type +'Syncfusion.Blazor.Toolkit.Buttons.SfButton'. There is no registered service of type +'Syncfusion.Blazor.Toolkit.SyncfusionBlazorToolkitService'. +``` -var builder = WebApplication.CreateBuilder(args); +The error is the same for any host that renders a Toolkit component without the registration, including static SSR pages. Disable prerendering only if the user asks; otherwise register on both hosts. -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents(); +## Make only the additions; keep the template -builder.Services.AddSyncfusionBlazorToolkit(); +Each template generates its own endpoint calls. **Do not retype `Program.cs`.** A trimmed copy drops `using .Components;` (`CS0246` on `App`) and loses `UseExceptionHandler`, `UseHsts`, `UseHttpsRedirection`, the static-asset mapping (`MapStaticAssets` on .NET 9+, `UseStaticFiles` on .NET 8) and `app.Run()`. -var app = builder.Build(); +| Template | Already generated on the server (leave alone) | +| --- | --- | +| `-int Server` (no `.Client` project) | `AddRazorComponents().AddInteractiveServerComponents()`; `MapRazorComponents().AddInteractiveServerRenderMode()` | +| `-int WebAssembly` | `AddRazorComponents().AddInteractiveWebAssemblyComponents()`; `MapRazorComponents().AddInteractiveWebAssemblyRenderMode().AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` | +| `-int Auto` | `AddRazorComponents().AddInteractiveServerComponents().AddInteractiveWebAssemblyComponents()`; `MapRazorComponents().AddInteractiveServerRenderMode().AddInteractiveWebAssemblyRenderMode().AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` | -app.MapRazorComponents() - .AddInteractiveServerRenderMode(); -``` +`AddAdditionalAssemblies(...)` sits on `MapRazorComponents()`, not on `AddRazorComponents()`, and it is not a Toolkit setting. Never add, remove, or move it for Toolkit. The three setups are different templates; do not mix them. Adding `AddInteractiveServerComponents()` to a WebAssembly template, or removing it from an Auto template, changes the app's render-mode support and is not needed for Toolkit. -## Scenario 2: Client components use Toolkit +## Server `Program.cs` (all three templates) -This is not "Client only" while prerendering is on. Keep the generated WebAssembly endpoints, and register Toolkit on the server as well. +Two additions: -**Server/Program.cs**: ```csharp -using Syncfusion.Blazor.Toolkit; - -var builder = WebApplication.CreateBuilder(args); +using Syncfusion.Blazor.Toolkit; // add at the top -builder.Services.AddRazorComponents() - .AddInteractiveServerComponents() - .AddInteractiveWebAssemblyComponents(); +// ...template code unchanged... -builder.Services.AddSyncfusionBlazorToolkit(); +builder.Services.AddSyncfusionBlazorToolkit(); // add before builder.Build() var app = builder.Build(); - -app.MapRazorComponents() - .AddInteractiveServerRenderMode() - .AddInteractiveWebAssemblyRenderMode(); ``` -**.Client/Program.cs**: +## `.Client/Program.cs` (`-int WebAssembly` and `-int Auto` only) + +The template already has `using Microsoft.AspNetCore.Components.WebAssembly.Hosting;`. Two additions: + ```csharp -using Syncfusion.Blazor.Toolkit; +using Microsoft.AspNetCore.Components.WebAssembly.Hosting; // already generated +using Syncfusion.Blazor.Toolkit; // add var builder = WebAssemblyHostBuilder.CreateDefault(args); -builder.Services.AddSyncfusionBlazorToolkit(); +builder.Services.AddSyncfusionBlazorToolkit(); // add await builder.Build().RunAsync(); ``` -## Scenario 3: Interactive Auto +## Interactive Auto behavior -Use the same server and client registration as Scenario 2. Interactive Auto needs both, because the first visit renders on the server and later cached visits render in WebAssembly. Do not add `RootComponents.Add("#app")` to `.Client`. +The first visit runs on the server; later visits use the cached WebAssembly bundle. A running component does not switch runtimes. Both hosts therefore need the registration. ## Common Mistake: Registering only one host -Calling `AddSyncfusionBlazorToolkit()` only in the server `Program.cs` does not register it for `.Client`. The reverse is also wrong while prerendering is on. +**Symptom**: HTTP 500 with the `SyncfusionBlazorToolkitService` error above, either on first load (server missing) or when a `.Client` component runs in the browser (client missing). + +**Fix**: Register on every host that renders it, keep the template's endpoints, and never add `RootComponents.Add("#app")` to `.Client`. -**Symptom**: Server-hosted components work, but Client components fail on first load or after the WASM runtime takes over. +## Component namespaces in both projects -**Fix**: Register Toolkit in every host that renders it, keep the template's WebAssembly endpoints, and never add `RootComponents.Add("#app")` to `.Client`. +Add the child namespace (for example `@using Syncfusion.Blazor.Toolkit.Buttons`) to the `_Imports.razor` of every project that renders that component. A missing namespace only warns (`RZ10012`) and renders an unstyled unknown element. ## Theme CSS in a Split Web App -Link the stylesheet in `Components/App.razor` so both Server and Client components can use it. Fluent is the default; `highcontrast.min.css` is also valid. +Add the stylesheet link to the existing `` in `Components/App.razor`; do not replace the file. Both Server and Client components use it. Fluent is the default; `highcontrast.min.css` is also valid. -```razor +```html ``` diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md index e797622361..3f407d634f 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md @@ -1,32 +1,23 @@ -# Theme and Host Files Reference +# Theme and Host Files Reference Toolkit components require CSS theming. Use the host file for your app type and link the Fluent stylesheet there. +> **Framework support.** The Toolkit targets `net8.0`, `net9.0`, and `net10.0`. If `` is older, recommend upgrading before installing: restore succeeds on `net7.0` and earlier but supplies no assemblies, so the build fails with `CS0246`. + +> **Never replace the whole host file.** The examples below show only the lines to add to the template-generated host file. Keep `HeadOutlet`, `Routes`, the render-mode directive on `Routes`, and the existing script tags (`_framework/blazor.web.js`, `_framework/blazor.webassembly.js`, or `blazor.server.js`) exactly as the template generated them. + ## Blazor Web App **Host file**: `Components/App.razor` **Theme**: Fluent is the default Toolkit stylesheet. The package also includes `highcontrast.min.css`. Do not link commercial theme files such as Bootstrap, Tailwind, or Material. -**Example**: +**Add this line to the existing ``** in `Components/App.razor` (do not replace the file): ```razor - - - - - - - - - - - - - - + ``` -**Legacy Blazor Server note**: If you are on an older Server template, `_Host.cshtml` may still be the host file and `blazor.server.js` may still appear there. Prefer `App.razor` and `blazor.web.js` for current Blazor Web App templates. +**Legacy Blazor Server note**: If you are on an older Server template, `_Host.cshtml` may still be the host file and `blazor.server.js` may still appear there. Prefer `App.razor` and `blazor.web.js` for current Blazor Web App templates. The same single-line addition applies — link only, do not replace `_Host.cshtml`. ## Standalone Blazor WebAssembly @@ -34,30 +25,20 @@ Toolkit components require CSS theming. Use the host file for your app type and **Theme**: Same stylesheets as the Web App host. Link `fluent.min.css` unless the user asks for high contrast. -**Example**: +**Add this line to the existing ``** in `wwwroot/index.html` (do not replace the file): ```html - - - - - - MyApp - - - - - -
- - - + ``` ## Available stylesheets +The stylesheets live under `_content/Syncfusion.Blazor.Toolkit/styles/`. Verified against package version 1.0.2: + - `fluent.min.css` — default Fluent stylesheet. Use this unless the user asks for something else. -- `highcontrast.min.css` — high-contrast stylesheet shipped with the Toolkit package. -- Individual component stylesheets: `button.min.css`, `calendar.min.css`, `chart.min.css`, `checkbox.min.css`, `dialog.min.css`, `dropdown.min.css`, `input.min.css`, `spinner.min.css`, `textbox.min.css`, `tooltip.min.css`, and others. +- `highcontrast.min.css` — high-contrast stylesheet. +- Per-component files: `button`, `buttongroup`, `calendar`, `chart`, `checkbox`, `datepicker`, `datetimepicker`, `dialog`, `input`, `numerictextbox`, `popup`, `radio-button`, `spinner`, `switch`, `textarea`, `textbox`, `timepicker`, `tooltip`, `uploader` (each with the `.min.css` suffix). + +There is no `dropdown.min.css`. Prefer `fluent.min.css`, which styles every component **except** `SfNumericTextBox`: its `.e-numerictextbox` selectors are in neither `fluent.min.css` nor `highcontrast.min.css`, so also link `numerictextbox.min.css` when that component is used. If a per-component file is linked, confirm it exists in the installed version's `styles/` folder. Do not link commercial theme files (`bootstrap5`, `tailwind`, `material`, and similar). They are not part of this package and will not style Toolkit components. @@ -75,9 +56,11 @@ Local references are preferred because they: ## Common Mistakes -1. **Linking in the wrong file**: Use `_Host.cshtml` for legacy Blazor Server, `Components/App.razor` for a Blazor Web App, or `wwwroot/index.html` for standalone WebAssembly. -2. **Wrong path directory**: The path is `_content/Syncfusion.Blazor.Toolkit/styles/` (`styles/`, not `themes/`). -3. **Wrong stylesheet name**: `bootstrap5`, `tailwind`, and `material` files are not in this package. Use `fluent.min.css` or `highcontrast.min.css`. -4. **Missing `.min` extension**: The filenames are `fluent.min.css` and `highcontrast.min.css`, not `fluent.css`. -5. **Missing link entirely**: Without the theme, components render unstyled and may be hard to see. -6. **Individual stylesheet only**: If you link only individual component stylesheets (e.g., just `button.min.css`), components not included will be unstyled. Use `fluent.min.css` for all components unless performance optimization is needed. +1. **Replacing the whole host file**: If `HeadOutlet`, `Routes`, the render-mode directive on `Routes`, or the framework script tag (`blazor.web.js`, `blazor.webassembly.js`, `blazor.server.js`) is removed while adding the stylesheet link, events and routing stop working. Restore the template and add only the `` line. +2. **Linking in the wrong file**: Use `_Host.cshtml` for legacy Blazor Server, `Components/App.razor` for a Blazor Web App, or `wwwroot/index.html` for standalone WebAssembly. +3. **Wrong path directory**: The path is `_content/Syncfusion.Blazor.Toolkit/styles/` (`styles/`, not `themes/`). +4. **Wrong stylesheet name**: `bootstrap5`, `tailwind`, and `material` files are not in this package. Use `fluent.min.css` or `highcontrast.min.css`. +5. **Missing `.min` extension**: The filenames are `fluent.min.css` and `highcontrast.min.css`, not `fluent.css`. +6. **Missing link entirely**: Without the theme, components render unstyled and may be hard to see. +7. **Per-component stylesheet only**: If you link only individual component stylesheets (e.g., just `button.min.css`), components not included will be unstyled. Use `fluent.min.css` for all components unless performance optimization is needed, and verify any per-component file you link actually exists in the package's `styles/` directory for the installed version. + diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md index 7bfc5c318d..5280ebe948 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md @@ -1,4 +1,6 @@ -# Troubleshooting Toolkit Installation +# Troubleshooting Toolkit Installation + +> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. On an older `` (for example `net6.0` or `net7.0`) restore **succeeds** but supplies no assemblies, so the build fails with `CS0246: The type or namespace name 'Syncfusion' could not be found` in `Program.cs`. Recommend upgrading the app to .NET 8 or later first; do not edit the TFM just to make the package install. ## Problem: Theme CSS not loading (404) or components unstyled @@ -43,10 +45,10 @@ ## Problem: Services not configured **Symptoms**: -- Runtime error when component tries to use Toolkit services -- Error message mentions missing or null service +- The page returns HTTP 500 (also for static SSR pages that render a Toolkit component) +- The log shows: `InvalidOperationException: Cannot provide a value for property 'SyncfusionService' on type 'Syncfusion.Blazor.Toolkit.Buttons.SfButton'. There is no registered service of type 'Syncfusion.Blazor.Toolkit.SyncfusionBlazorToolkitService'.` -**Root cause**: `AddSyncfusionBlazorToolkit()` is not called in `Program.cs`. +**Root cause**: `AddSyncfusionBlazorToolkit()` is not called on a host that renders a Toolkit component. **Diagnosis**: 1. Open `Program.cs` (or the Server/Client `Program.cs` in split Web Apps) @@ -56,16 +58,11 @@ ``` 3. If missing, add it before `builder.Build()`. -**Fix**: +**Fix**: add only these two lines to the existing `Program.cs`; leave every other template line as generated. ```csharp -using Syncfusion.Blazor.Toolkit; - -var builder = WebApplication.CreateBuilder(args); +using Syncfusion.Blazor.Toolkit; // top of the file -builder.Services.AddRazorComponents(); -builder.Services.AddSyncfusionBlazorToolkit(); - -var app = builder.Build(); +builder.Services.AddSyncfusionBlazorToolkit(); // before builder.Build() ``` --- @@ -90,8 +87,9 @@ var app = builder.Build(); @page "/mypage" @* Add one mode that matches the app's configured interactivity *@ @rendermode InteractiveServer +@using Syncfusion.Blazor.Toolkit.Buttons -Click me +Click me @code { private void OnClick() @@ -105,8 +103,9 @@ Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int ```razor @page "/mypage" @rendermode InteractiveWebAssembly +@using Syncfusion.Blazor.Toolkit.Buttons -Click me +Click me @code { private void OnClick() @@ -118,35 +117,59 @@ Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int --- -## Problem: `Syncfusion.Blazor.Toolkit` namespace not found +## Problem: `using Syncfusion.Blazor.Toolkit;` fails in `Program.cs` **Symptoms**: -- Compilation error: "The type or namespace name 'Syncfusion' could not be found" -- IntelliSense doesn't show Toolkit types +- `CS0246: The type or namespace name 'Syncfusion' could not be found` on the `using` line in a `.cs` file -**Root cause**: The NuGet package is not installed, or namespaces are not imported. +**Root cause** (check in this order): +1. The package is not referenced in **that project's** `.csproj`. In a split Web App both the server and `.Client` projects need the `PackageReference`. +2. The project targets `net7.0` or older. Restore succeeds but supplies no assemblies, so this exact error appears. Upgrade to .NET 8 or later. **Diagnosis**: 1. Check the `.csproj` file for: ```xml - - ``` -2. If missing, install the package. -3. Check `_Imports.razor` (or component file) for: - ```razor - @using Syncfusion.Blazor.Toolkit + ``` -4. If missing, add the namespace import. +2. Check `` is `net8.0`, `net9.0`, or `net10.0`. **Fix**: -1. Install the package: +1. Install the package in each project that calls the registration: ```bash dotnet add package Syncfusion.Blazor.Toolkit ``` -2. Add to `_Imports.razor`: +2. A root `@using Syncfusion.Blazor.Toolkit` in `_Imports.razor` is optional and does not affect `.cs` files. + +--- + +## Problem: Component type not found (`SfButton` and similar) + +**Symptoms**: +- Build **succeeds** with warning `RZ10012: Found markup element with unexpected name 'SfButton'. If this is intended to be a component, add a @using directive for its namespace.` +- At runtime the tag renders as an unknown HTML element: no `e-btn` class, no styling, and `OnClick` does nothing +- There is **no** `CS0246` for a missing component namespace in a `.razor` file + +**Root cause**: Toolkit **component types do not live in the root `Syncfusion.Blazor.Toolkit` namespace**. Each component family has its own child namespace (`Syncfusion.Blazor.Toolkit.Buttons`, `Syncfusion.Blazor.Toolkit.Calendars`, `Syncfusion.Blazor.Toolkit.Inputs`, etc.). The root namespace holds enums and the registration extension class, not components. + +**Fix**: +1. Add the **per-component namespace** to `_Imports.razor`. For example, when using `SfButton` (the root using is optional): ```razor - @using Syncfusion.Blazor.Toolkit + @using Syncfusion.Blazor.Toolkit.Buttons ``` +2. Match the component to its namespace (verified against package 1.0.2): `SfButton`, `SfButtonGroup` → `Buttons`; `SfCalendar`, `SfDatePicker`, `SfDateTimePicker`, `SfTimePicker` → `Calendars`; `SfTextBox`, `SfTextArea`, `SfNumericTextBox`, `SfCheckBox`, `SfRadioButton`, `SfSwitch`, `SfUploader` → `Inputs`; `SfChart` → `Charts`; `SfDialog`, `SfTooltip` → `Popups`; `SfSpinner` → `Spinner`. There is no Toolkit grid component. If a type still does not resolve, check the installed version's IntelliSense. +3. The per-component namespace **must** be added to the project that owns the component. In a split Web App, add `@using Syncfusion.Blazor.Toolkit.Buttons` to **both** the Server and `.Client` `_Imports.razor` files when both render `SfButton`. + +--- + +## Problem: Routable pages in `.Client` return 404 after editing `Program.cs` + +**Symptoms**: +- Pages defined in the `.Client` project no longer route +- It started after `Program.cs` was edited or replaced + +**Root cause**: The template's `.AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` call on `MapRazorComponents()` was removed. This is unrelated to Toolkit registration; it lets the router discover `.Client` pages. + +**Fix**: Restore the call on `MapRazorComponents()`, exactly as the template generated it. Do not move it onto `AddRazorComponents()`. --- @@ -156,7 +179,7 @@ Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int - Toolkit components work fine in Server-side pages - Same components in Client pages fail or don't render -**Root cause**: `AddSyncfusionBlazorToolkit()` is registered in Server `Program.cs` but not in Client `Program.cs`. +**Root cause**: `AddSyncfusionBlazorToolkit()` is missing in one of the two hosts. With client-only registration, `.Client` pages also fail on first load (HTTP 500), because prerendering runs them on the server. **Diagnosis**: 1. Check both `Program.cs` files (Server and Client) @@ -166,8 +189,9 @@ Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int **Fix**: - Add `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` to `.Client/Program.cs`. Do not add `RootComponents.Add("#app")`. - Also register Toolkit in the server `Program.cs` while prerendering is enabled. Keep the generated `AddInteractiveWebAssemblyComponents()` and `AddInteractiveWebAssemblyRenderMode()` calls. +- Leave the template's `AddAdditionalAssemblies(...)` call on `MapRazorComponents()` untouched. -Also ensure both projects have the NuGet package reference in their `.csproj` files and both have namespace imports in their `_Imports.razor` files. +Also ensure both projects have the NuGet package reference in their `.csproj` files and both have namespace imports in their `_Imports.razor` files. Add the per-component namespace (e.g. `@using Syncfusion.Blazor.Toolkit.Buttons` for `SfButton`) to both `_Imports.razor` files when both render the component. --- @@ -256,12 +280,15 @@ Also ensure both projects have the NuGet package reference in their `.csproj` fi Before troubleshooting further, verify: -1. ✓ Package name is `Syncfusion.Blazor.Toolkit` (not a commercial `Syncfusion.Blazor.*` package) -2. ✓ `using Syncfusion.Blazor.Toolkit;` and `AddSyncfusionBlazorToolkit()` are in `Program.cs` (in both Server and Client projects of a split Web App) -3. ✓ `@using Syncfusion.Blazor.Toolkit` is in `_Imports.razor` (in both projects of a split Web App) -4. ✓ Stylesheet link is `fluent.min.css` or `highcontrast.min.css` in the host file (`Components/App.razor` for a Blazor Web App, `Pages/_Host.cshtml` for legacy Blazor Server, `wwwroot/index.html` for standalone WebAssembly) -5. ✓ Path uses `styles/`, not `themes/`, and keeps the `.min` extension -6. ✓ Blazor Web App interactivity is inherited from `Routes` or declared once. Do not add `@rendermode` to legacy Server or standalone WebAssembly -7. ✓ Commercial packages and `SyncfusionLicenseProvider.RegisterLicense(...)` remain only where commercial components are still used -8. ✓ Build completes without errors: `dotnet build` -9. ✓ Browser console shows no 404 or JavaScript errors +1. ✓ `` in the `.csproj` is `net8.0`, `net9.0`, or `net10.0`. If it is older, recommend upgrading first. +2. ✓ Package name is `Syncfusion.Blazor.Toolkit` (not a commercial `Syncfusion.Blazor.*` package) +3. ✓ `using Syncfusion.Blazor.Toolkit;` and `AddSyncfusionBlazorToolkit()` are in `Program.cs` (in both Server and Client projects of a split Web App) +4. ✓ `@using Syncfusion.Blazor.Toolkit` is in `_Imports.razor` (in both projects of a split Web App). Per-component namespaces (e.g. `@using Syncfusion.Blazor.Toolkit.Buttons` for `SfButton`) are added to the `_Imports.razor` of every project that renders the component. +5. ✓ The template's `AddAdditionalAssemblies(...)` and `AddInteractive*` calls are unchanged; only the Toolkit `using` and `AddSyncfusionBlazorToolkit()` were added. +6. ✓ Stylesheet link is `fluent.min.css` or `highcontrast.min.css` in the host file's `` (`Components/App.razor` for a Blazor Web App, `_Host.cshtml` for legacy Blazor Server, `wwwroot/index.html` for standalone WebAssembly). The link is **added** to the existing file — `HeadOutlet`, `Routes`, the render-mode directive, and the framework script tag are preserved. +7. ✓ Path uses `styles/`, not `themes/`, and keeps the `.min` extension +8. ✓ Blazor Web App interactivity is inherited from `Routes` or declared once. Do not add `@rendermode` to legacy Server or standalone WebAssembly +9. ✓ Commercial packages and `SyncfusionLicenseProvider.RegisterLicense(...)` remain only where commercial components are still used +10. ✓ Build completes without errors: `dotnet build` +11. ✓ Browser console shows no 404 or JavaScript errors + diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml index 3d7084235b..391779f80b 100644 --- a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -32,10 +32,10 @@ stimuli: pattern: (?i)_content/Syncfusion\.Blazor\.Toolkit/styles/fluent\.min\.css - type: output-not-matches config: - pattern: (?i)(dotnet add package|PackageReference Include=\"?)\s*Syncfusion\.Blazor(?!\.Toolkit)\b + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|without|instead of|rather than|no need|unlike|wrong|mistake|incorrect)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*(?:dotnet add package|PackageReference Include=)\s*"?Syncfusion\.Blazor(?!\.Toolkit)\b' - type: output-not-matches config: - pattern: (?i)\b(enter|provide|paste|add|register) (your|a) (syncfusion )?license key + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|no|without|free|nothing|avoid|unlike)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*\b(?:enter|provide|paste|add|register) (?:your|a) (?:syncfusion )?license key' - type: prompt rubric: - Installs the open-source Toolkit package and registers its extension method with the namespace in scope. @@ -59,7 +59,7 @@ stimuli: pattern: (?i)AddSyncfusionBlazorToolkit - type: output-matches config: - pattern: (?i)(wwwroot/)?index\.html + pattern: '(?i)wwwroot[/\\]index\.html|index\.html[^\n]{0,60}(?:\("#app"\) @@ -92,7 +92,7 @@ stimuli: pattern: (?i)prerender - type: output-not-matches config: - pattern: (?i)(only (in|on) (the )?server|client inherits|register only in server) + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|wrong|mistake|incorrect|instead of|rather than|without)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*(?:register (?:it )?only (?:in|on) (?:the )?server|only (?:in|on) the server is (?:enough|sufficient)|client inherits (?:the )?(?:server(?:''s)? )?(?:registration|services))' - type: prompt rubric: - Registers Toolkit in both the server and Client hosts when both render Toolkit components. @@ -117,7 +117,10 @@ stimuli: pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/(fluent|highcontrast)\.min\.css - type: output-matches config: - pattern: (?i)Components/App\.razor|_Host\.cshtml|index\.html + pattern: '(?i)]*styles/(?:fluent|highcontrast)\.min\.css' + - type: output-not-matches + config: + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|instead of|rather than|wrong)\b|\w+n[''’]t\b))[^\n]*(?:(?:\.csproj|appsettings|Program\.cs)[^\n]{0,80}(?:` says the type or namespace could not be found. Why? + graders: + - type: output-matches + config: + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|wrong)\b|\w+n[''’]t\b))[^\n]*@using\s+Syncfusion\.Blazor\.Toolkit\.Buttons' + - type: prompt + rubric: + - Explains that SfButton is in the child namespace Syncfusion.Blazor.Toolkit.Buttons, not the root namespace. + - Adds the child namespace using to _Imports.razor rather than changing the package. + + - name: missing-registration-http-500 + tags: + capability: service-registration + risk: unregistered-service + journey: diagnose-500 + prompt: | + My Blazor Web App page with an SfButton from Syncfusion.Blazor.Toolkit returns HTTP 500. + The log says "There is no registered service of type SyncfusionBlazorToolkitService". + I referenced the package and added the stylesheet. What is wrong? + graders: + - type: output-matches + config: + pattern: AddSyncfusionBlazorToolkit + - type: output-matches + config: + pattern: (?i)using\s+Syncfusion\.Blazor\.Toolkit + - type: output-not-matches + config: + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|wrong)\b|\w+n[''’]t\b))[^\n]*\b(?:remove|uninstall|downgrade|roll back)\b[^\n]{0,40}(?:package|Syncfusion)' + - type: prompt + rubric: + - Diagnoses a missing AddSyncfusionBlazorToolkit() registration, not a package or stylesheet problem. + - Says to add the registration to every host that renders Toolkit components, including the server when prerendering. + - Adds only the using and the registration line to the existing Program.cs rather than retyping it. + + - name: numeric-textbox-unstyled + tags: + capability: theme-linking + risk: bundle-gap + journey: link-component-stylesheet + prompt: | + I linked fluent.min.css from Syncfusion.Blazor.Toolkit and my SfButton and SfTextBox look fine, + but SfNumericTextBox renders unstyled. What should I add? + graders: + - type: output-matches + config: + pattern: _content/Syncfusion\.Blazor\.Toolkit/styles/numerictextbox\.min\.css + - type: prompt + rubric: + - Adds numerictextbox.min.css alongside fluent.min.css, because the Fluent bundle does not contain the numeric textbox selectors. + - Keeps the fluent.min.css link rather than replacing it. + - name: out-of-scope-component-api tags: capability: dormancy @@ -344,7 +436,7 @@ stimuli: graders: - type: output-not-matches config: - pattern: (?i)(first|before answering|instead)[\s\S]{0,80}(install the package|AddSyncfusionBlazorToolkit|follow these installation steps) + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|no need|without|already)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*\b(?:first|before (?:answering|anything)|start by)\b[^\n]{0,80}(?:install the package|AddSyncfusionBlazorToolkit|installation steps)' - type: prompt rubric: - The install skill stayed dormant: answer the chart API question or point to component documentation. @@ -363,7 +455,7 @@ stimuli: graders: - type: output-not-matches config: - pattern: (?i)(dotnet add package|PackageReference)[\s\S]{0,40}Syncfusion + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|no need|without|later|avoid|instead of)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*(?:dotnet add package|PackageReference)[^\n]{0,40}Syncfusion' - type: prompt rubric: - The install skill stayed dormant: the request is about creating a project, not installing a UI package. @@ -381,11 +473,22 @@ stimuli: and how do I wire it up? expect_activation: false graders: + # Directional guards. They fire only on a line that INSTRUCTS the user to edit a + # Web App / legacy Server host file, or on a code line that is a Web App / + # standalone WASM registration. Any line containing a negator (not, never, + # avoid, unlike, instead of, ... or any n't contraction) is skipped, so a + # correct boundary explanation may name Components/App.razor, _Host.cshtml, + # @rendermode or RootComponents.Add freely. AddSyncfusionBlazorToolkit + # and `dotnet add package` are NOT banned: Hybrid apps may legitimately use them. + - type: output-not-matches + config: + pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|without|instead of|rather than|no need|unlike|wrong|mistake|incorrect)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*(?:^|[.:;]\s*)\s*(?:open|edit|add|put|place|update|modify|link)\b[^\n]{0,60}(?:Components/App\.razor|_Host\.cshtml)' - type: output-not-matches config: - pattern: (?i)(Components/App\.razor|_Host\.cshtml|@rendermode|RootComponents\.Add\("#app"\)|AddInteractive(Server|WebAssembly)|AddSyncfusionBlazorToolkit) + pattern: '(?im)^\s*(?:builder\.RootComponents\.Add\(|\.?AddInteractive(?:Server|WebAssembly)(?:Components|RenderMode)\()' - type: prompt rubric: - The install skill stayed dormant: the app is a MAUI Blazor Hybrid app, which is outside this skill's scope. - - Recognizes the Hybrid boundary and does not apply the Web App, legacy Server, or standalone WebAssembly host-file steps. + - Recognizes the Hybrid boundary and does not tell the user to apply the Web App, legacy Server, or standalone WebAssembly host-file or render-mode steps. + - Judged on intent, not keywords. It may name Components/App.razor, _Host.cshtml, @rendermode, RootComponents.Add, or AddSyncfusionBlazorToolkit when explaining why they do not apply to a BlazorWebView host, and it may mention the package or its registration for Hybrid. - Redirects to the Hybrid or MAUI host page (such as wwwroot/index.html in the BlazorWebView) or to Hybrid-specific documentation. From 2b1188ccccdd7abaf3e95e1083b2b9f900aeafe0 Mon Sep 17 00:00:00 2001 From: Indhumathy-Loganathan Date: Wed, 7 Oct 2026 20:04:21 +0530 Subject: [PATCH 09/27] Eval and Skill recent review changes included. --- .../SKILL.md | 33 +++--- .../references/render-modes.md | 112 ++++++++++-------- .../references/split-webapp-registration.md | 2 +- .../references/theme-and-host-files.md | 2 +- .../references/troubleshooting.md | 16 +-- .../eval.yaml | 91 ++++++++------ 6 files changed, 151 insertions(+), 105 deletions(-) diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md index 876e2da24a..84e5005d4d 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md @@ -20,12 +20,12 @@ description: > ## Core Rules -1. **Verify the target framework first.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0` only. Read `` in the app's `.csproj` before installing. On `net6.0`, `net7.0`, or older, NuGet restore still succeeds but supplies no assemblies, so the build later fails with `CS0246` on `Syncfusion`. Do not install; recommend upgrading to .NET 8 or later first (for example with the `dotnet-upgrade` plugin) and resume afterward. Never edit the TFM just to make the package install. +1. **Verify the target framework first.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first (for example with the `dotnet-upgrade` plugin), then continue with the installation steps. If the `` is unknown, read it before doing anything else. Never edit the TFM just to make the package install. 2. Use the exact package ID `Syncfusion.Blazor.Toolkit`. 3. In every `Program.cs` that calls `AddSyncfusionBlazorToolkit()`, add `using Syncfusion.Blazor.Toolkit;` so the extension method is in scope. Call it before `builder.Build()`. 4. Component types live in child namespaces, not the root. Add the namespace for each component to `_Imports.razor` (for example `@using Syncfusion.Blazor.Toolkit.Buttons` for `SfButton`). A missing namespace does not fail the build: Razor warns `RZ10012` and renders the tag as an unknown HTML element. The root `@using Syncfusion.Blazor.Toolkit` is optional and only needed to name its enums. `_Imports.razor` does not affect `Program.cs`. 5. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` (or `highcontrast.min.css`) in the app host file. Fluent is the default. Add the link to the host file's ``; do not replace the whole host file. -6. Use `@rendermode` only in a Blazor Web App. Legacy Blazor Server and standalone WebAssembly are already interactive and do not use render modes. +6. Use `@rendermode` only in a Blazor Web App. Legacy Blazor Server and standalone WebAssembly are already interactive and do not use render modes. In a Web App, **`-int Server`, `-int WebAssembly` and `-int Auto` are per-page**: `` has no directive and only pages with their own `@rendermode` are interactive. Only `-ai` (`--all-interactive`) is global. Any Toolkit component that uses events, bindings, dialogs, calendar navigation, or button clicks must sit under an interactive mode (a page directive in a per-page app, or the inherited `Routes` mode in a global app). Never leave it on a static page. 7. Toolkit components need `AddSyncfusionBlazorToolkit()` on **every host that renders them, including static SSR**. Without it the page returns HTTP 500 with `There is no registered service of type 'Syncfusion.Blazor.Toolkit.SyncfusionBlazorToolkitService'`. In a split Blazor Web App, register on the server and in `.Client`: prerendering runs `.Client` components on the server, so client-only registration still returns 500. 8. In a split Blazor Web App, the `.Client` project is not a standalone WASM app. Do not call `RootComponents.Add("#app")` there. Keep the `.AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` call the template puts on `MapRazorComponents()`; the server needs it to see `.Client` pages. It is unrelated to Toolkit, so never add, remove, or move it. 9. Do not add a commercial `Syncfusion.Blazor*` package to satisfy a Toolkit request. If the app already uses commercial components, leave those packages and `Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(...)` in place. @@ -34,7 +34,7 @@ description: > ## Don'ts -- Don't install the Toolkit on a .NET 6 or .NET 7 project. Recommend upgrading first. +- Don't install the Toolkit on a .NET 6 or .NET 7 project, or when the `` has not been checked. Recommend upgrading to .NET 8 or later first. - Don't treat `Syncfusion.Blazor` or component-specific commercial packages as Toolkit dependencies. - Don't add external script tags or commercial Syncfusion license scripts; Toolkit JS is bundled with the package. - Don't rely on static SSR when the component must respond to clicks, binding, or dynamic updates. @@ -45,17 +45,21 @@ description: > Pick the **single** row that matches the app the user is on. The "Program.cs" columns say where `AddSyncfusionBlazorToolkit()` goes; the template's own endpoint calls stay as generated. -| Scenario | Register in server `Program.cs` | Register in `.Client/Program.cs` | Host file for CSS | Interactivity | +| Scenario | Register in server `Program.cs` | Register in `.Client/Program.cs` | Host file for CSS | Where interactive Toolkit components go | | --- | --- | --- | --- | --- | -| Legacy Blazor Server (`_Host.cshtml`, .NET 8+ only for Toolkit) | Yes | n/a | `_Host.cshtml` | Already interactive (no `@rendermode`) | -| Standalone Blazor WebAssembly | n/a | Yes, in the standalone `Program.cs`; it keeps its own `RootComponents.Add("#app")` | `wwwroot/index.html` | Already interactive (no `@rendermode`; not static SSR) | -| Blazor Web App, `-int Server` | Yes | n/a (no `.Client` project) | `Components/App.razor` | Inherited from `Routes`; do not add a different child mode | -| Blazor Web App, `-int WebAssembly` | Yes | Yes; **no** `RootComponents.Add` | `Components/App.razor` | WebAssembly; prerendered on the server first | -| Blazor Web App, `-int Auto` | Yes | Yes; **no** `RootComponents.Add` | `Components/App.razor` | First visit server, later visits cached WebAssembly; a running component does not switch | -| Blazor Web App, per-page modes | Yes (prerendering runs there) | Yes, if `.Client` renders the component | `Components/App.razor` | One mode per component; a child cannot switch interactive modes | -| Static SSR only (Blazor Web App) | Yes, if any Toolkit markup is rendered | n/a | `Components/App.razor` | None; read-only only. Standalone WASM is not this row | +| Legacy Blazor Server (`_Host.cshtml`, net8.0+ only for Toolkit) | Yes | n/a | `_Host.cshtml` | Anywhere; already interactive, no `@rendermode` | +| Standalone Blazor WebAssembly | n/a | Yes, in the standalone `Program.cs`; it keeps its own `RootComponents.Add("#app")` | `wwwroot/index.html` | Anywhere; already interactive, no `@rendermode` | +| Web App `-int Server` (**per-page**) | Yes | n/a (no `.Client` project) | `Components/App.razor` | Pages with `@rendermode InteractiveServer`; pages without it are static SSR | +| Web App `-int Server -ai` (**global**) | Yes | n/a | `Components/App.razor` | Anywhere; inherited from `Routes`. Do not add a different mode | +| Web App `-int WebAssembly` (**per-page**) | Yes | Yes; **no** `RootComponents.Add` | `Components/App.razor` | Pages with `@rendermode InteractiveWebAssembly`, which **must** be in `.Client` (a server-project page prerenders, then fails in the browser) | +| Web App `-int WebAssembly -ai` (**global**) | Yes | Yes | `Components/App.razor` | Anywhere; inherited from `Routes` | +| Web App `-int Auto` (**per-page**) | Yes | Yes; **no** `RootComponents.Add` | `Components/App.razor` | Pages with `@rendermode InteractiveAuto`, which **must** be in `.Client` (a server-project Auto page prerenders, then fails in the browser). First visit server, later cached WebAssembly; a running component does not switch | +| Web App `-int Auto -ai` (**global**) | Yes | Yes | `Components/App.razor` | Anywhere; inherited from `Routes` | +| Web App `-int None` / static SSR page | Yes, if any Toolkit markup renders | n/a | `Components/App.razor` | Display-only Toolkit markup only; **never** components that use events, bindings, dialogs, or clicks | | .NET MAUI Blazor Hybrid | **Out of scope** (see below) | n/a | n/a | n/a | +Verified with `dotnet new blazor`: without `-ai`, `` carries no directive and only the sample `Counter.razor` has its own `@rendermode`. With `-ai`, `HeadOutlet` and `Routes` carry `@rendermode="Interactive..."`. See [Render modes explained](./references/render-modes.md). + ## Minimal Setup ### Package @@ -141,13 +145,13 @@ This skill does not cover .NET MAUI Blazor Hybrid. When a user asks, explain the - There is no `App.razor`, `_Host.cshtml`, `HeadOutlet`, or render mode. The UI runs in a `BlazorWebView` declared in `MainPage.xaml`. - The host page is `wwwroot/index.html`, with a `
` root wired through ``. It loads `_framework/blazor.webview.js`. - Services are registered in `MauiProgram.cs`, after `builder.Services.AddMauiBlazorWebView();`. -- The Toolkit's `net10.0` assets resolve for a platform TFM such as `net10.0-windows10.0.19041.0`. Android, iOS and Mac Catalyst were not verified, so point the user to Hybrid-specific documentation rather than promising support. +- The Toolkit's `net10.0` assets resolve for the platform TFMs `net10.0-android`, `net10.0-ios`, `net10.0-maccatalyst` and `net10.0-windows10.0.19041.0` (verified by restore against 1.0.2). `net9.0-android` and `net8.0-android` fail on the SDK itself (`NETSDK1147`, MAUI workload not installed), so Toolkit support there was not testable. Even so, this skill does not configure Hybrid apps: point the user to Hybrid-specific documentation. The same TFM check applies: a MAUI project on an unsupported .NET version needs an upgrade first. ## Common Mistakes | Mistake | Symptom | Fix | | --- | --- | --- | -| Toolkit installed on .NET 6 or .NET 7 | Restore succeeds, then the build fails with `CS0246` on `Syncfusion` (no assemblies are supplied) | Upgrade the app to .NET 8 or later first. Never change the TFM just to make the package install | +| Toolkit installed on .NET 6, .NET 7, or older | The package may restore, but Toolkit assemblies are not available to the application, so the build fails with `CS0246: ... 'Syncfusion' could not be found` | Upgrade the app to .NET 8 or later first. Never change the TFM just to make the package install | | `AddSyncfusionBlazorToolkit()` missing on a host that renders Toolkit | HTTP 500: `no registered service of type ...SyncfusionBlazorToolkitService` | Register on every rendering host, including the server for `.Client` components and for static SSR | | CSS path uses `themes/` or omits `.min` | Components are unstyled (404 in browser DevTools) | Use `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` | | CSS linked in a component file instead of the host file | Styling doesn't apply consistently | Move the `` to the host file `` | @@ -157,10 +161,11 @@ This skill does not cover .NET MAUI Blazor Hybrid. When a user asks, explain the | Commercial package added for a Toolkit-only app | License prompt, missing Toolkit components | Replace that package with `Syncfusion.Blazor.Toolkit`. If other pages still use commercial components, keep those packages and `SyncfusionLicenseProvider.RegisterLicense(...)` | | Component namespace missing | Razor warning `RZ10012`; `` renders as an unstyled unknown element that ignores events | Add the child namespace, for example `@using Syncfusion.Blazor.Toolkit.Buttons`, to `_Imports.razor` of the project that renders it | | Added an external Syncfusion CDN script tag | JavaScript conflicts or duplicate library errors | Remove the CDN script; Toolkit JS ships in the NuGet package | -| `@rendermode` missing, and no interactive mode is inherited | Clicks and binding do nothing on a Blazor Web App page | Apply one interactive mode, or inherit the mode already on `Routes` | +| Assumed `-int Server` is global, so an interactive Toolkit component has no `@rendermode` | Clicks, bindings, dialogs and calendar navigation do nothing on a Blazor Web App page | Check `Routes` in `App.razor`. In a per-page app add one `@rendermode` matching the template to the page; in a `-ai` app inherit the mode already on `Routes` | | `@rendermode` added to standalone WASM or legacy Server | No effect, and it can look like a fix | Remove it; those apps are already interactive | | Child `@rendermode` differs from the parent interactive mode | Runtime error; a child cannot switch interactive modes | Match the inherited mode, or move the component to a page with the intended mode | | Auto or WebAssembly endpoint removed from a split Web App | Client components never load, or load only after a server round-trip | Keep the endpoints the template generated | +| `InteractiveWebAssembly` or `InteractiveAuto` page created in the **server** project | HTTP 200 and the component shows from the prerender, then the browser console reports `Root component type '...' could not be found in the assembly ''` and nothing is interactive | Move the page and its components into the `.Client` project | | `RootComponents.Add("#app")` added to `.Client` | The Client host has no `#app` element | Remove it. That call belongs only in standalone WebAssembly | ## Top Failure Symptoms diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md index 7aa5bcb987..f9dd58d986 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md @@ -1,22 +1,45 @@ # Render Modes Reference -Blazor supports multiple render modes. Toolkit components need an interactive mode whenever they handle clicks, binding, or other live updates. +Toolkit components need an interactive render mode whenever they handle clicks, bindings, dialogs, calendar navigation, or any other client interaction. A Toolkit component rendered in static SSR is display-only. -> **Framework support.** The Toolkit targets `net8.0`, `net9.0`, and `net10.0`. If `` is older, recommend upgrading first: restore succeeds on `net7.0` and earlier but supplies no assemblies, so the build fails with `CS0246`. +> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. > **Namespaces.** `SfButton` lives in `Syncfusion.Blazor.Toolkit.Buttons`, so each sample below includes `@using Syncfusion.Blazor.Toolkit.Buttons`. If it is already in `_Imports.razor`, the per-page line can be dropped. Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInteractive*` and `AddAdditionalAssemblies(...)` call exactly as the project template generated it; do not add or remove them for Toolkit. -## Static SSR (Server-Side Rendering) +## Template matrix (verified with `dotnet new blazor`) -**When to use**: Read-only content where no user interaction or dynamic updates are needed. +`dotnet new blazor -int ` makes the **server project** interactive-capable but leaves pages **static** until a page opts in. Adding `-ai` (`--all-interactive`) puts the mode on `HeadOutlet` and `Routes` in `App.razor`, so every page inherits it. -**Characteristic**: Components are rendered on the server and sent as HTML; no .NET code runs on the client. +| Template command | Scope | `.Client` project | `Routes` in `App.razor` | Sample page | +| --- | --- | --- | --- | --- | +| `-int None` | Static SSR only | No | `` | none; no interactive endpoints | +| `-int Server` | **Per-page** | No | `` (static) | `Counter.razor` has `@rendermode InteractiveServer` | +| `-int Server -ai` | **Global** | No | `` | pages inherit; no per-page directive | +| `-int WebAssembly` | **Per-page** | Yes | `` (static) | `Counter.razor` has `@rendermode InteractiveWebAssembly` | +| `-int WebAssembly -ai` | **Global** | Yes | `` | pages inherit | +| `-int Auto` | **Per-page** | Yes | `` (static) | `Counter.razor` has `@rendermode InteractiveAuto` | +| `-int Auto -ai` | **Global** | Yes | `` | pages inherit | +| Legacy `blazorserver` (`_Host.cshtml`) | Always interactive | No | n/a | no render modes | +| Standalone `blazorwasm` | Always interactive | n/a | n/a | no render modes | -**Toolkit limitation**: Static SSR is not sufficient for interactive Toolkit components (buttons, forms, inputs, etc.). Event handlers and state changes will not work. Toolkit services are still required: a static page that renders `SfButton` returns HTTP 500 without `AddSyncfusionBlazorToolkit()`. +**Do not assume `-int Server` is global.** Only `-ai` is. With the default per-page template, any page that is not marked with a `@rendermode` is static SSR. -**Example (read-only only)**: +## Rule for placing Toolkit components + +1. Find the scope: read `Components/App.razor`. If `Routes` (and `HeadOutlet`) carry `@rendermode="..."`, the app is **global** and every page inherits that mode. If `` has no directive, the app is **per-page**. +2. **Global**: place Toolkit components anywhere. Do not add a different `@rendermode` to a page; a child cannot switch to a different interactive mode. +3. **Per-page**: put every Toolkit component that uses events, bindings, dialogs, calendar navigation, or button clicks on a page or component that has its own `@rendermode`, or inside a component that is rendered from such a page. Pages without a directive are static SSR and must only host display-only Toolkit markup. +4. Choose the mode to match the template: `InteractiveServer` for `-int Server`, `InteractiveWebAssembly` for `-int WebAssembly`, `InteractiveAuto` for `-int Auto`. Use a mode the app already supports; never add endpoints for Toolkit. + +## Static SSR + +**When to use**: Read-only content with no user interaction. + +**Toolkit limitation**: Static SSR is not sufficient for interactive Toolkit components. Event handlers and state changes will not work. Toolkit services are still required: a static page that renders `SfButton` returns HTTP 500 without `AddSyncfusionBlazorToolkit()`. + +**Example (display-only)**: ```razor @page "/status" @using Syncfusion.Blazor.Toolkit.Buttons @@ -24,15 +47,10 @@ Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInterac Read-only button ``` -## Interactive Server Rendering +## Interactive Server -**When to use**: Interactive components on a Blazor Web App configured for Interactive Server, or a page that opts into `@rendermode InteractiveServer`. +**Per-page (`-int Server`)**: add `@rendermode InteractiveServer` to each page that hosts interactive Toolkit components. -**Characteristic**: User interactions are sent to the server, processed, and updates stream back to the client. - -**Toolkit requirement**: Fully supported. Register Toolkit in the server `Program.cs`. - -**Example** (only when the page does not already inherit an interactive mode): ```razor @page "/counter" @rendermode InteractiveServer @@ -47,17 +65,16 @@ Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInterac } ``` -**Server `Program.cs`** (`dotnet new blazor -int Server`): leave the template's `AddInteractiveServerComponents()` and `AddInteractiveServerRenderMode()` as generated, and add only `using Syncfusion.Blazor.Toolkit;` plus `builder.Services.AddSyncfusionBlazorToolkit();` before `builder.Build()`. Do not add WebAssembly services to this template. +**Global (`-int Server -ai`)**: `Routes` already carries `@rendermode="InteractiveServer"`. Write the same page **without** the `@rendermode` line. -## Interactive WebAssembly Rendering +**`Program.cs`**: leave the template's `AddInteractiveServerComponents()` and `AddInteractiveServerRenderMode()` as generated. Add only `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` before `builder.Build()`. Do not add WebAssembly services to this template. -**When to use**: A Blazor Web App page or component that should run in the browser after download (`dotnet new blazor -int WebAssembly`, or a component in the `.Client` project). +## Interactive WebAssembly -**Characteristic**: .NET runs in the browser; no server round-trip for user interactions after load. Default prerendering still executes the component on the server first, so the server also needs Toolkit services. +Interactive pages live in the `.Client` project. Default prerendering still runs the component on the server first, so the server also needs Toolkit services. -**Do not use `@rendermode` in a standalone Blazor WebAssembly app.** That app is already interactive. The directive has no effect there and can look like a fix for a different problem. +**Per-page (`-int WebAssembly`)**: add `@rendermode InteractiveWebAssembly` to the page, and keep that page in the `.Client` project. Verified: an `InteractiveWebAssembly` page placed in the server project returns HTTP 200 and shows the button from the prerender, then fails in the browser with `Root component type '...' could not be found in the assembly ''`. -**Blazor Web App example** (only when the page does not already inherit an interactive mode): ```razor @page "/counter" @rendermode InteractiveWebAssembly @@ -72,19 +89,18 @@ Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInterac } ``` -**Server and `.Client` `Program.cs`** (`dotnet new blazor -int WebAssembly`): the template registers WebAssembly endpoints only. Keep them, and keep `AddAdditionalAssemblies(...)` on `MapRazorComponents()`. Add `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` to **both** the server and `.Client/Program.cs` (prerendering runs the component on the server). Do not add `RootComponents.Add("#app")` to `.Client`. See [Split Blazor Web App registration](./split-webapp-registration.md). +**Global (`-int WebAssembly -ai`)**: `Routes` already carries `@rendermode="InteractiveWebAssembly"`. Omit the page directive. -**Standalone WebAssembly `Program.cs`** (no Web App, no `.Client` project): the template already has `RootComponents.Add("#app")` and `RootComponents.Add("head::after")`. Add only `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` before `Build()`. +**`Program.cs`** (server and `.Client`): the template registers WebAssembly endpoints only. Keep them and `AddAdditionalAssemblies(...)` on `MapRazorComponents()`. Add `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` to **both** the server and `.Client/Program.cs`. Do not add `RootComponents.Add("#app")` to `.Client`. See [Split Blazor Web App registration](./split-webapp-registration.md). -## Interactive Auto Rendering +**Standalone WebAssembly** is a different app (no Web App, no `.Client`): it is always interactive, has no `@rendermode`, and its `Program.cs` already contains `RootComponents.Add("#app")`. Add only the Toolkit `using` and the registration. -**When to use**: A Blazor Web App that should use server interactivity on the first visit, then WebAssembly on later visits once the runtime bundle is downloaded and cached. +## Interactive Auto -**Characteristic**: Auto chooses the runtime per visit. A component that is already running does not switch from server to WebAssembly mid-circuit. See https://learn.microsoft.com/aspnet/core/blazor/components/render-modes +First visit runs on the server; later visits use the cached WebAssembly bundle. A running component does not switch runtimes. As with WebAssembly, interactive Auto pages and components must live in the `.Client` project, because the same code has to run in both places. Verified: an `@rendermode InteractiveAuto` page placed in the server project returns HTTP 200 and shows the button from the prerender, then fails in the browser with `Root component type '...' could not be found in the assembly ''`, so it never becomes interactive. See https://learn.microsoft.com/aspnet/core/blazor/components/render-modes -**Toolkit requirement**: Fully supported. Register Toolkit in both the server and `.Client` projects, because the first visit renders on the server and later visits render in WebAssembly. +**Per-page (`-int Auto`)**: add `@rendermode InteractiveAuto` to the page, and keep that page in the `.Client` project (the template's sample `Counter.razor` is in `.Client/Pages`). -**Example** (page-level `@rendermode InteractiveAuto`): ```razor @page "/counter" @rendermode InteractiveAuto @@ -99,32 +115,32 @@ Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInterac } ``` -**Server and `.Client` `Program.cs`** (`dotnet new blazor -int Auto`): the template registers both Interactive Server and Interactive WebAssembly, and `AddAdditionalAssemblies(...)` on `MapRazorComponents()`. Keep all of it. Add `using Syncfusion.Blazor.Toolkit;` and `builder.Services.AddSyncfusionBlazorToolkit();` to **both** the server and `.Client/Program.cs`. Do not add `RootComponents.Add("#app")` to `.Client`. +**Global (`-int Auto -ai`)**: `Routes` already carries `@rendermode="InteractiveAuto"`. Omit the page directive. -## Decision Tree +**`Program.cs`** (server and `.Client`): the template registers both Interactive Server and Interactive WebAssembly, plus `AddAdditionalAssemblies(...)`. Keep all of it. Add the Toolkit `using` and `AddSyncfusionBlazorToolkit()` to **both** the server and `.Client/Program.cs`. Do not add `RootComponents.Add("#app")` to `.Client`. -1. **Does the component need to respond to user clicks or changes?** - - **No** → Static rendering is enough. Stop. - - **Yes** → Go to question 2. +## Decision Tree +1. **Does the component handle clicks, bindings, dialogs, calendar navigation, or any client interaction?** + - **No** → Static rendering is enough (services are still required). Stop. + - **Yes** → Continue. 2. **Which app is this?** - - **Legacy Blazor Server or standalone WebAssembly** → Already interactive. Do not add `@rendermode`. - - **Blazor Web App** → Go to question 3. + - **Legacy `_Host.cshtml` Server or standalone WebAssembly** → Already interactive. Do not add `@rendermode`. + - **Blazor Web App** → Continue. +3. **Is `Routes` in `App.razor` already carrying `@rendermode`?** + - **Yes (global, `-ai`)** → Inherit it. Do not add a different mode. + - **No (per-page)** → Add exactly one directive on the page that hosts the component, matching the template: `InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto`. -3. **Does `Routes` in `App.razor` already apply an interactive mode?** - - **Yes** → Inherit it. A child cannot switch to a different interactive mode. - - **No** → Apply one mode on the page or component: - - Server processing → `@rendermode InteractiveServer` - - Browser processing → `@rendermode InteractiveWebAssembly` - - Server on the first visit, WebAssembly on later cached visits → `@rendermode InteractiveAuto` +An interactive Toolkit component must never be left on a page with no `@rendermode` in a per-page app. ## Common Mistakes -1. **Adding `@rendermode` under an inherited mode**: If `Routes` already has an interactive mode, a child that names a different one fails. Match the parent or move the component. -2. **Treating standalone WebAssembly as static SSR**: It has no static SSR and no render-mode directive. -3. **Adding WebAssembly endpoints to a server-only project**: That project may not reference the WebAssembly server package. -4. **Mixing the WebAssembly and Auto templates**: `-int WebAssembly` registers WebAssembly endpoints only; `-int Auto` registers both Server and WebAssembly. Keep the shape the template generated. -5. **Editing endpoints to "fit" Toolkit**: Toolkit needs only `AddSyncfusionBlazorToolkit()`. Do not add or remove `AddInteractive*` or `AddAdditionalAssemblies(...)` calls for it. -6. **Describing Auto as a live runtime switch**: The first visit uses the server; later visits use the cached WebAssembly bundle. A running component does not migrate. -7. **Assuming a missing directive means the component is static**: Check the inherited mode first. - +1. **Assuming `-int Server` is global**: it is per-page. Only `-ai` is global. A page without `@rendermode` is static SSR in a per-page app. +2. **Leaving an interactive Toolkit component on a static page**: clicks, bindings, and dialogs do nothing. Add the template's `@rendermode` to the page. +3. **Adding `@rendermode` under an inherited mode**: if `Routes` already has one (global), a child that names a different mode fails. Match the parent or move the component. +4. **Treating standalone WebAssembly or legacy Server as needing `@rendermode`**: they have no render modes. +5. **Adding WebAssembly endpoints to a server-only project**: Toolkit does not need them. +6. **Mixing the WebAssembly and Auto templates**: `-int WebAssembly` registers WebAssembly endpoints only; `-int Auto` registers both Server and WebAssembly. Keep the shape the template generated. +7. **Editing endpoints to "fit" Toolkit**: Toolkit needs only `AddSyncfusionBlazorToolkit()`. Do not add or remove `AddInteractive*` or `AddAdditionalAssemblies(...)` calls. +8. **Describing Auto as a live runtime switch**: a running component does not migrate. +9. **Assuming a missing directive means the component is interactive or static**: read `Routes` in `App.razor` first. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md index b9641ac52a..e782b661ef 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md @@ -1,6 +1,6 @@ # Split Blazor Web App Service Registration -`Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Check `` in **both** projects first; if either is older, upgrade before installing. +> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the `` of **both** projects before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. A generated `.Client` project is not a standalone WebAssembly app. The server owns `App.razor`, and the host markup has no `#app` element. Never call `RootComponents.Add("#app")` in `.Client/Program.cs`. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md index 3f407d634f..4645c4b8a7 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md @@ -2,7 +2,7 @@ Toolkit components require CSS theming. Use the host file for your app type and link the Fluent stylesheet there. -> **Framework support.** The Toolkit targets `net8.0`, `net9.0`, and `net10.0`. If `` is older, recommend upgrading before installing: restore succeeds on `net7.0` and earlier but supplies no assemblies, so the build fails with `CS0246`. +> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. > **Never replace the whole host file.** The examples below show only the lines to add to the template-generated host file. Keep `HeadOutlet`, `Routes`, the render-mode directive on `Routes`, and the existing script tags (`_framework/blazor.web.js`, `_framework/blazor.webassembly.js`, or `blazor.server.js`) exactly as the template generated them. diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md index 5280ebe948..8c126f11a4 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/troubleshooting.md @@ -1,6 +1,6 @@ # Troubleshooting Toolkit Installation -> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. On an older `` (for example `net6.0` or `net7.0`) restore **succeeds** but supplies no assemblies, so the build fails with `CS0246: The type or namespace name 'Syncfusion' could not be found` in `Program.cs`. Recommend upgrading the app to .NET 8 or later first; do not edit the TFM just to make the package install. +> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. ## Problem: Theme CSS not loading (404) or components unstyled @@ -74,15 +74,15 @@ builder.Services.AddSyncfusionBlazorToolkit(); // before builder.Build() - Clicking buttons or entering text in forms has no effect - No errors in the browser console -**Root cause**: The component is static, or an interactive child is trying to switch modes. A missing `@rendermode` does not by itself mean the component is static. +**Root cause**: In a Blazor Web App the component is on a static SSR page. `dotnet new blazor -int Server`, `-int WebAssembly` and `-int Auto` are **per-page**: `` has no `@rendermode`, so a page is static unless it declares its own. Only `-ai` (`--all-interactive`) makes the whole app interactive. A less common cause is an interactive child trying to switch to a different mode than the one it inherits. **Diagnosis**: 1. Identify the app. Legacy Blazor Server and standalone WebAssembly are already interactive; do not add `@rendermode`. -2. In a Blazor Web App, open `Components/App.razor` and check `Routes`. If `Routes` already has an interactive mode, the page inherits it. A child cannot switch to a different interactive mode. -3. If neither the page nor `Routes` has an interactive mode, the page is static SSR. -4. If a mode is already present and clicks still do nothing, check the circuit, the browser console, and failed `_content` script requests before editing the page. +2. In a Blazor Web App, open `Components/App.razor` and check `Routes`. If `Routes` carries `@rendermode="..."` (a `-ai` app), every page inherits it. A child cannot switch to a different interactive mode. +3. If `` has no directive (a per-page app) and the page has no `@rendermode`, the page is static SSR. That is the cause. +4. If a mode is already in effect and clicks still do nothing, check the circuit, the browser console, and failed `_content` script requests before editing the page. -**Fix** (only when no interactive mode is inherited): +**Fix** (per-page app, page has no interactive mode): add exactly one directive matching the template (`InteractiveServer` for `-int Server`, `InteractiveWebAssembly` for `-int WebAssembly`, `InteractiveAuto` for `-int Auto`) to the page that hosts the component: ```razor @page "/mypage" @* Add one mode that matches the app's configured interactivity *@ @@ -99,7 +99,7 @@ builder.Services.AddSyncfusionBlazorToolkit(); // before builder.Build() } ``` -Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int WebAssembly`): +Or, for a per-page Blazor Web App created with `dotnet new blazor -int WebAssembly` (the page lives in `.Client`): ```razor @page "/mypage" @rendermode InteractiveWebAssembly @@ -124,7 +124,7 @@ Or for a Blazor Web App using WebAssembly interactivity (`dotnet new blazor -int **Root cause** (check in this order): 1. The package is not referenced in **that project's** `.csproj`. In a split Web App both the server and `.Client` projects need the `PackageReference`. -2. The project targets `net7.0` or older. Restore succeeds but supplies no assemblies, so this exact error appears. Upgrade to .NET 8 or later. +2. The project targets `net6.0`, `net7.0`, or older. The package may restore, but Toolkit assemblies are not available to the application, so this error appears at build time. Upgrade to .NET 8 or later first. **Diagnosis**: 1. Check the `.csproj` file for: diff --git a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml index 391779f80b..fab2226b50 100644 --- a/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml +++ b/tests/dotnet-blazor/syncfusion-blazor-toolkit-install/eval.yaml @@ -11,7 +11,7 @@ stimuli: risk: wrong-package-or-host journey: install-legacy-server prompt: | - I'm setting up a new legacy Blazor Server project that uses _Host.cshtml. + I'm setting up a legacy-style Blazor Server project that targets net8.0 and uses _Host.cshtml. I want to install the open-source Syncfusion Blazor Toolkit. What are the steps I need to follow to get it working? graders: @@ -32,10 +32,10 @@ stimuli: pattern: (?i)_content/Syncfusion\.Blazor\.Toolkit/styles/fluent\.min\.css - type: output-not-matches config: - pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|without|instead of|rather than|no need|unlike|wrong|mistake|incorrect)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*(?:dotnet add package|PackageReference Include=)\s*"?Syncfusion\.Blazor(?!\.Toolkit)\b' + pattern: '(?im)(?:^|(?<=[.:;!?])\s+)(?!(?:(?![.:;!?](?:\s|$))[^\n])*?(?:\b(?:not|never|avoid|without|instead of|rather than|no need|unlike|cannot)\b|\w+n[''’]t\b)(?:(?![.:;!?](?:\s|$))[^\n])*?(?:dotnet add package|PackageReference Include=)\s*"?Syncfusion\.Blazor(?!\.Toolkit)\b)(?!(?:(?![.:;!?](?:\s|$))[^\n])*?(?:dotnet add package|PackageReference Include=)\s*"?Syncfusion\.Blazor(?!\.Toolkit)\b(?:(?![.:;!?](?:\s|$))[^\n])*?(?:\b(?:wrong|commercial|incorrect|mistake|deprecated)\b))(?:(?![.:;!?](?:\s|$))[^\n])*?(?:dotnet add package|PackageReference Include=)\s*"?Syncfusion\.Blazor(?!\.Toolkit)\b' - type: output-not-matches config: - pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|no|without|free|nothing|avoid|unlike)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*\b(?:enter|provide|paste|add|register) (?:your|a) (?:syncfusion )?license key' + pattern: '(?im)(?:^|(?<=[.:;!?])\s+)(?!(?:(?![.:;!?](?:\s|$))[^\n])*?(?:\b(?:not|never|no|without|free|nothing|avoid|unlike)\b|\w+n[''’]t\b|\bcannot\b))(?:(?![.:;!?](?:\s|$))[^\n])*?\b(?:enter|provide|paste|add|register) (?:your|a) (?:syncfusion )?license key' - type: prompt rubric: - Installs the open-source Toolkit package and registers its extension method with the namespace in scope. @@ -48,8 +48,8 @@ stimuli: risk: wrong-wasm-host journey: install-standalone-wasm prompt: | - I'm building a standalone Blazor WebAssembly application and want to add the Syncfusion Blazor Toolkit. - Can you guide me through installation and setup? + I'm building a standalone Blazor WebAssembly application that targets net9.0 and want to add + the Syncfusion Blazor Toolkit. Can you guide me through installation and setup? graders: - type: output-matches config: @@ -92,7 +92,7 @@ stimuli: pattern: (?i)prerender - type: output-not-matches config: - pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|wrong|mistake|incorrect|instead of|rather than|without)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*(?:register (?:it )?only (?:in|on) (?:the )?server|only (?:in|on) the server is (?:enough|sufficient)|client inherits (?:the )?(?:server(?:''s)? )?(?:registration|services))' + pattern: '(?im)(?:^|(?<=[.:;!?])\s+)(?!(?:(?![.:;!?](?:\s|$))[^\n])*?(?:\b(?:not|never|avoid|wrong|mistake|incorrect|instead of|rather than|without)\b|\w+n[''’]t\b|\bcannot\b))(?:(?![.:;!?](?:\s|$))[^\n])*?(?:register (?:it )?only (?:in|on) (?:the )?server|only (?:in|on) the server is (?:enough|sufficient)|client inherits (?:the )?(?:server(?:''s)? )?(?:registration|services))' - type: prompt rubric: - Registers Toolkit in both the server and Client hosts when both render Toolkit components. @@ -120,7 +120,7 @@ stimuli: pattern: '(?i)]*styles/(?:fluent|highcontrast)\.min\.css' - type: output-not-matches config: - pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|instead of|rather than|wrong)\b|\w+n[''’]t\b))[^\n]*(?:(?:\.csproj|appsettings|Program\.cs)[^\n]{0,80}(?: freely. AddSyncfusionBlazorToolkit - # and `dotnet add package` are NOT banned: Hybrid apps may legitimately use them. + # Directional guards, scoped to a single CLAUSE (text between . : ; ! ? marks), not a + # whole line. The first fires only on a clause that INSTRUCTS the user to edit a + # Web App / legacy Server host file. A negator (not, never, avoid, unlike, instead + # of, ... or any n't contraction) exempts only its own clause, so a correct + # boundary explanation may name Components/App.razor, _Host.cshtml, @rendermode + # or RootComponents.Add, while "You should not skip this: open + # Components/App.razor" (negator in a different clause) is still caught. + # AddSyncfusionBlazorToolkit and `dotnet add package` are NOT banned: Hybrid apps + # may legitimately use them. - type: output-not-matches config: - pattern: '(?im)^(?![^\n]*(?:\b(?:not|never|avoid|without|instead of|rather than|no need|unlike|wrong|mistake|incorrect)\b|\w+n[''’]t\b|\bcannot\b))[^\n]*(?:^|[.:;]\s*)\s*(?:open|edit|add|put|place|update|modify|link)\b[^\n]{0,60}(?:Components/App\.razor|_Host\.cshtml)' + pattern: '(?im)(?:^|(?<=[.:;!?])\s+)(?!(?:(?![.:;!?](?:\s|$))[^\n])*?(?:\b(?:not|never|avoid|without|instead of|rather than|no need|unlike|cannot)\b|\w+n[''’]t\b))(?:(?![.:;!?](?:\s|$))[^\n])*?\b(?:open|edit|add|put|place|update|modify|link)\b(?:(?![.:;!?](?:\s|$))[^\n]){0,60}(?:Components/App\.razor|_Host\.cshtml)' - type: output-not-matches config: pattern: '(?im)^\s*(?:builder\.RootComponents\.Add\(|\.?AddInteractive(?:Server|WebAssembly)(?:Components|RenderMode)\()' From f401d9314e0090a9403f0ce5dcc6a6905bf20b0e Mon Sep 17 00:00:00 2001 From: Indhumathy-Loganathan Date: Tue, 13 Oct 2026 22:00:02 +0530 Subject: [PATCH 10/27] Toolkit skill files were included. --- .../SKILL.md | 62 +++++++++++++------ .../references/package-identity.md | 9 +-- .../references/render-modes.md | 14 ++--- .../references/split-webapp-registration.md | 10 +-- .../references/theme-and-host-files.md | 22 ++++--- .../references/troubleshooting.md | 46 +++++++++----- .../eval.yaml | 12 ++-- 7 files changed, 110 insertions(+), 65 deletions(-) diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md index 84e5005d4d..f6b32030e1 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/SKILL.md @@ -1,16 +1,17 @@ ---- +--- license: MIT name: syncfusion-blazor-toolkit-install description: > - Install and register the open-source Syncfusion Blazor Toolkit package, - configure AddSyncfusionBlazorToolkit(), link the Fluent or High Contrast - stylesheet, and apply the interactive render mode that matches the app - topology (legacy Server, standalone WASM, or a Blazor Web App). + Install and register the open-source Syncfusion Blazor Toolkit package + (v2.0+), configure AddSyncfusionBlazorToolkit(), link the Fluent or High + Contrast stylesheet, apply the interactive render mode that matches the app + topology (legacy Server, standalone WASM, or a Blazor Web App), and account + for namespace consolidation and CSS isolation. USE FOR: Toolkit setup, package verification, stylesheet linking, split-app - registration, render-mode troubleshooting, and diagnosing an accidental + registration, render-mode troubleshooting, diagnosing an accidental commercial Syncfusion.Blazor install or license-key prompt when the user - wanted the open-source Toolkit. + wanted the open-source Toolkit, and migrating from Toolkit 1.x to 2.0. DO NOT USE FOR: component API details (use author-component), Blazor project creation (use create-blazor-project), configuring commercial Syncfusion components that the app actually uses, Hybrid/MAUI. @@ -20,17 +21,22 @@ description: > ## Core Rules -1. **Verify the target framework first.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first (for example with the `dotnet-upgrade` plugin), then continue with the installation steps. If the `` is unknown, read it before doing anything else. Never edit the TFM just to make the package install. -2. Use the exact package ID `Syncfusion.Blazor.Toolkit`. +1. **Verify the target framework first.** `Syncfusion.Blazor.Toolkit` 2.0.0 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first (for example with the `dotnet-upgrade` plugin), then continue with the installation steps. If the `` is unknown, read it before doing anything else. Never edit the TFM just to make the package install. +2. Use the exact package ID `Syncfusion.Blazor.Toolkit`. Prefer the latest 2.x stable release (2.0.0 or newer). Version 2.0.0 is **not source-compatible** with 1.0.2. 3. In every `Program.cs` that calls `AddSyncfusionBlazorToolkit()`, add `using Syncfusion.Blazor.Toolkit;` so the extension method is in scope. Call it before `builder.Build()`. -4. Component types live in child namespaces, not the root. Add the namespace for each component to `_Imports.razor` (for example `@using Syncfusion.Blazor.Toolkit.Buttons` for `SfButton`). A missing namespace does not fail the build: Razor warns `RZ10012` and renders the tag as an unknown HTML element. The root `@using Syncfusion.Blazor.Toolkit` is optional and only needed to name its enums. `_Imports.razor` does not affect `Program.cs`. -5. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` (or `highcontrast.min.css`) in the app host file. Fluent is the default. Add the link to the host file's ``; do not replace the whole host file. +4. **Namespace consolidation (2.0 breaking change).** All public types live under the single root namespace `Syncfusion.Blazor.Toolkit`. Domain-specific namespaces (`Syncfusion.Blazor.Toolkit.Buttons`, `.Calendars`, `.Charts`, `.Inputs`, `.Popups`, `.Spinner`, etc.) were removed. Add only: + ```razor + @using Syncfusion.Blazor.Toolkit + ``` + to `_Imports.razor` (and the equivalent `using` in C# files). A missing namespace produces Razor warning `RZ10012` and renders the tag as an unknown HTML element. `_Imports.razor` does not affect `Program.cs`. +5. Link `_content/Syncfusion.Blazor.Toolkit/styles/fluent.min.css` (or `highcontrast.min.css`) in the app host file. Fluent is the default. Add the link to the host file's ``; do not replace the whole host file. Component styles use Blazor CSS isolation (scoped bundle); the shared theme layer (`:root` tokens, base/utility styles, icon font, keyframes, dark/high-contrast/forced-colors) is emitted at render time by `SfThemeRoot`. Every consumer-facing root component renders `` as its previous sibling automatically—no extra consumer configuration is required when Toolkit components are present. Place an explicit `` only when theme emission is needed without a Toolkit component in the tree. 6. Use `@rendermode` only in a Blazor Web App. Legacy Blazor Server and standalone WebAssembly are already interactive and do not use render modes. In a Web App, **`-int Server`, `-int WebAssembly` and `-int Auto` are per-page**: `` has no directive and only pages with their own `@rendermode` are interactive. Only `-ai` (`--all-interactive`) is global. Any Toolkit component that uses events, bindings, dialogs, calendar navigation, or button clicks must sit under an interactive mode (a page directive in a per-page app, or the inherited `Routes` mode in a global app). Never leave it on a static page. 7. Toolkit components need `AddSyncfusionBlazorToolkit()` on **every host that renders them, including static SSR**. Without it the page returns HTTP 500 with `There is no registered service of type 'Syncfusion.Blazor.Toolkit.SyncfusionBlazorToolkitService'`. In a split Blazor Web App, register on the server and in `.Client`: prerendering runs `.Client` components on the server, so client-only registration still returns 500. 8. In a split Blazor Web App, the `.Client` project is not a standalone WASM app. Do not call `RootComponents.Add("#app")` there. Keep the `.AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` call the template puts on `MapRazorComponents()`; the server needs it to see `.Client` pages. It is unrelated to Toolkit, so never add, remove, or move it. 9. Do not add a commercial `Syncfusion.Blazor*` package to satisfy a Toolkit request. If the app already uses commercial components, leave those packages and `Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense(...)` in place. 10. Toolkit JavaScript is embedded in the NuGet package; do not add commercial script tags. 11. Keep this skill install-focused; use the references for details and troubleshooting. +12. **CSS isolation (2.0).** Component styles are scoped. App-level overrides that previously targeted unscoped toolkit class names (for example `.e-btn`) may need the `::deep` combinator or adjustment for isolation attributes. Review custom CSS after upgrading from 1.x. ## Don'ts @@ -39,6 +45,7 @@ description: > - Don't add external script tags or commercial Syncfusion license scripts; Toolkit JS is bundled with the package. - Don't rely on static SSR when the component must respond to clicks, binding, or dynamic updates. - Don't use this skill as a component API reference; consult the official Syncfusion Blazor Toolkit demos or documentation for API details. +- Don't use domain-specific `@using` directives from Toolkit 1.x (`Syncfusion.Blazor.Toolkit.Buttons`, `.Calendars`, etc.). They no longer exist in 2.0. - Don't replace or retype `Program.cs`, `App.razor`, `_Host.cshtml`, or `wwwroot/index.html`. Make only the additions shown below and leave every other template line (`UseExceptionHandler`, `UseHsts`, `MapStaticAssets`, `HeadOutlet`, `Routes`, render-mode directives, script tags) untouched. ## Quick Decision Table @@ -68,6 +75,8 @@ Verified with `dotnet new blazor`: without `-ai`, `` carries no direct dotnet add package Syncfusion.Blazor.Toolkit ``` +Prefer the latest 2.x version (2.0.0 or newer). + ### Program.cs: make only these additions Every template (`-int Server`, `-int WebAssembly`, `-int Auto`) already generates its own `AddRazorComponents()`, `Map*` and `AddAdditionalAssemblies(...)` calls. **Do not retype or replace them.** Pasting a trimmed `Program.cs` drops `using .Components;` (so `App` stops resolving, `CS0246`) and removes `UseExceptionHandler`, `UseHsts`, `UseHttpsRedirection`, the static-asset mapping (`MapStaticAssets` on .NET 9+, `UseStaticFiles` on .NET 8) and `app.Run()`. @@ -121,13 +130,14 @@ builder.Services.AddSyncfusionBlazorToolkit(); // add, before Bui ### _Imports.razor -Add one `@using` per component family you render. In a split Web App add it to the `_Imports.razor` of **every project that renders the component** (server `Components/_Imports.razor` and `.Client/_Imports.razor`). +Add the single root namespace. In a split Web App add it to the `_Imports.razor` of **every project that renders Toolkit components** (server `Components/_Imports.razor` and `.Client/_Imports.razor`). ```razor -@using Syncfusion.Blazor.Toolkit.Buttons -@* Other families in 1.0.2: Calendars, Charts, Inputs, Popups (SfDialog, SfTooltip), Spinner *@ +@using Syncfusion.Blazor.Toolkit ``` +Do **not** add domain-specific usings such as `@using Syncfusion.Blazor.Toolkit.Buttons` — those namespaces were removed in 2.0. + ### Host file CSS Add this single line to the `` of the existing host file. **Do not replace the rest of the file**: keep `HeadOutlet`, `Routes` and its render-mode directive, and the existing script tag (`_framework/blazor.web.js`, `_framework/blazor.webassembly.js`, or `blazor.server.js`) exactly as the template generated them. @@ -136,7 +146,20 @@ Add this single line to the `` of the existing host file. **Do not replace ``` -Pick the host file from the Quick Decision Table. Use `highcontrast.min.css` only when the user asks for high contrast. `SfNumericTextBox` additionally needs `numerictextbox.min.css`, because its selectors are not in the Fluent or High Contrast bundle. See [Theme and host files](./references/theme-and-host-files.md). +Pick the host file from the Quick Decision Table. Use `highcontrast.min.css` only when the user asks for high contrast. See [Theme and host files](./references/theme-and-host-files.md). + +`SfThemeRoot` emits the shared theme layer automatically when any Toolkit component renders. An explicit `` is only needed if the app requires theme tokens without a Toolkit component in the tree. + + +## Migrating from Toolkit 1.x to 2.0 + +1. Update the package to 2.0.0 or newer. +2. Replace every domain-specific `@using Syncfusion.Blazor.Toolkit.` with the single `@using Syncfusion.Blazor.Toolkit`. +3. Update any fully qualified type names that used the old child namespaces. +4. Keep the Fluent (or High Contrast) stylesheet link; component styles are now CSS-isolated and the shared theme is delivered by `SfThemeRoot`. +5. Review custom CSS overrides that targeted unscoped toolkit class names; isolation may require `::deep` or scope adjustments. +6. If subclasses of `DataAdaptor` exist, add `where T : notnull`. +7. Collection return types that were `List` may now be `IList`; avoid casting to `List`. ## Hybrid / MAUI boundary @@ -145,7 +168,7 @@ This skill does not cover .NET MAUI Blazor Hybrid. When a user asks, explain the - There is no `App.razor`, `_Host.cshtml`, `HeadOutlet`, or render mode. The UI runs in a `BlazorWebView` declared in `MainPage.xaml`. - The host page is `wwwroot/index.html`, with a `
` root wired through ``. It loads `_framework/blazor.webview.js`. - Services are registered in `MauiProgram.cs`, after `builder.Services.AddMauiBlazorWebView();`. -- The Toolkit's `net10.0` assets resolve for the platform TFMs `net10.0-android`, `net10.0-ios`, `net10.0-maccatalyst` and `net10.0-windows10.0.19041.0` (verified by restore against 1.0.2). `net9.0-android` and `net8.0-android` fail on the SDK itself (`NETSDK1147`, MAUI workload not installed), so Toolkit support there was not testable. Even so, this skill does not configure Hybrid apps: point the user to Hybrid-specific documentation. The same TFM check applies: a MAUI project on an unsupported .NET version needs an upgrade first. +- The Toolkit's `net10.0` assets resolve for the platform TFMs `net10.0-android`, `net10.0-ios`, `net10.0-maccatalyst` and `net10.0-windows10.0.19041.0` (verified by restore against 2.0.0). `net9.0-android` and `net8.0-android` fail on the SDK itself (`NETSDK1147`, MAUI workload not installed), so Toolkit support there was not testable. Even so, this skill does not configure Hybrid apps: point the user to Hybrid-specific documentation. The same TFM check applies: a MAUI project on an unsupported .NET version needs an upgrade first. ## Common Mistakes @@ -159,7 +182,9 @@ This skill does not cover .NET MAUI Blazor Hybrid. When a user asks, explain the | `Program.cs` retyped from a trimmed sample | `CS0246` on `App`, and `UseExceptionHandler`, `UseHsts`, `MapStaticAssets` and `app.Run()` are lost | Restore the template file, then add only the `using` and the registration line | | Template's `AddAdditionalAssemblies(typeof(.Client._Imports).Assembly)` deleted from `MapRazorComponents()` | Routable pages in `.Client` return 404 | Restore the call exactly as the template generated it | | Commercial package added for a Toolkit-only app | License prompt, missing Toolkit components | Replace that package with `Syncfusion.Blazor.Toolkit`. If other pages still use commercial components, keep those packages and `SyncfusionLicenseProvider.RegisterLicense(...)` | -| Component namespace missing | Razor warning `RZ10012`; `` renders as an unstyled unknown element that ignores events | Add the child namespace, for example `@using Syncfusion.Blazor.Toolkit.Buttons`, to `_Imports.razor` of the project that renders it | +| Domain-specific `@using` from 1.x still present | `CS0234` or unresolved type; components not recognized | Replace with `@using Syncfusion.Blazor.Toolkit` only | +| Component namespace missing (or still using 1.x child namespace) | Razor warning `RZ10012`; `` renders as an unstyled unknown element that ignores events | Add `@using Syncfusion.Blazor.Toolkit` to `_Imports.razor` of the project that renders it | +| Custom CSS from 1.x no longer applies | Styles ignored after upgrade | Account for CSS isolation; use `::deep` for child selectors when needed | | Added an external Syncfusion CDN script tag | JavaScript conflicts or duplicate library errors | Remove the CDN script; Toolkit JS ships in the NuGet package | | Assumed `-int Server` is global, so an interactive Toolkit component has no `@rendermode` | Clicks, bindings, dialogs and calendar navigation do nothing on a Blazor Web App page | Check `Routes` in `App.razor`. In a per-page app add one `@rendermode` matching the template to the page; in a `-ai` app inherit the mode already on `Routes` | | `@rendermode` added to standalone WASM or legacy Server | No effect, and it can look like a fix | Remove it; those apps are already interactive | @@ -170,11 +195,12 @@ This skill does not cover .NET MAUI Blazor Hybrid. When a user asks, explain the ## Top Failure Symptoms -- **Unstyled components**: the stylesheet link is missing, wrong, or in the wrong host file; or a component namespace is missing (`RZ10012`). See [Theme and host files](./references/theme-and-host-files.md). +- **Unstyled components**: the stylesheet link is missing, wrong, or in the wrong host file; or the root namespace is missing (`RZ10012`); or custom overrides need isolation adjustment. See [Theme and host files](./references/theme-and-host-files.md). - **HTTP 500 mentioning `SyncfusionBlazorToolkitService`**: `AddSyncfusionBlazorToolkit()` is missing on a host that renders Toolkit. See [Troubleshooting guide](./references/troubleshooting.md). - **Clicks or inputs do nothing**: check for an inherited render mode before editing the page. If none exists, the page is static SSR. See [Render modes explained](./references/render-modes.md). - **Only one half of a split app works**: register Toolkit on both hosts. See [Split Blazor Web App registration](./references/split-webapp-registration.md). - **License prompt after installing `Syncfusion.Blazor`**: that is the commercial package. See [Package identity](./references/package-identity.md) before removing anything the app still uses. +- **Unresolved types after upgrading from 1.x**: domain namespaces were removed; use only `@using Syncfusion.Blazor.Toolkit`. ## Next Steps diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md index 64279e5306..26e436e737 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/package-identity.md @@ -4,13 +4,14 @@ ### The open-source Toolkit: Syncfusion.Blazor.Toolkit -- **NuGet package name**: `Syncfusion.Blazor.Toolkit` (verified at version 1.0.2) +- **NuGet package name**: `Syncfusion.Blazor.Toolkit` (verified at version 2.0.0) - **License**: MIT - **Target frameworks**: `net8.0`, `net9.0`, `net10.0` - **Scope**: Open-source Blazor toolkit for the current published component set - **Repository**: https://github.com/syncfusion/blazor-toolkit - **Components included**: Refer to the official Syncfusion Blazor Toolkit documentation for the authoritative and current component list. This skill is not a component reference. - **No license key required**: Toolkit is free to use without registration +- **Breaking changes in 2.0**: Namespace consolidation (single root `Syncfusion.Blazor.Toolkit`), CSS isolation, and `SfThemeRoot` theme delivery. Not source-compatible with 1.0.2. ### Commercial Syncfusion.Blazor* Packages @@ -24,7 +25,7 @@ ## Install the Toolkit (and ONLY the Toolkit for this skill) ```bash -# Correct: Install Toolkit +# Correct: Install Toolkit (prefer latest 2.x) dotnet add package Syncfusion.Blazor.Toolkit # Wrong: Do NOT install commercial packages for Toolkit tasks @@ -39,8 +40,8 @@ Check the `.csproj` file: ```xml - - + + diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md index f9dd58d986..66de971edb 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/render-modes.md @@ -1,10 +1,10 @@ -# Render Modes Reference +# Render Modes Reference Toolkit components need an interactive render mode whenever they handle clicks, bindings, dialogs, calendar navigation, or any other client interaction. A Toolkit component rendered in static SSR is display-only. -> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. +> **Framework support.** `Syncfusion.Blazor.Toolkit` 2.0.0 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. -> **Namespaces.** `SfButton` lives in `Syncfusion.Blazor.Toolkit.Buttons`, so each sample below includes `@using Syncfusion.Blazor.Toolkit.Buttons`. If it is already in `_Imports.razor`, the per-page line can be dropped. +> **Namespaces (2.0).** All public component types live in the single root namespace `Syncfusion.Blazor.Toolkit`. Domain-specific namespaces from 1.x were removed. Each sample below includes `@using Syncfusion.Blazor.Toolkit`. If it is already in `_Imports.razor`, the per-page line can be dropped. Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInteractive*` and `AddAdditionalAssemblies(...)` call exactly as the project template generated it; do not add or remove them for Toolkit. @@ -42,7 +42,7 @@ Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInterac **Example (display-only)**: ```razor @page "/status" -@using Syncfusion.Blazor.Toolkit.Buttons +@using Syncfusion.Blazor.Toolkit Read-only button ``` @@ -54,7 +54,7 @@ Toolkit itself only needs `AddSyncfusionBlazorToolkit()`. Keep every `AddInterac ```razor @page "/counter" @rendermode InteractiveServer -@using Syncfusion.Blazor.Toolkit.Buttons +@using Syncfusion.Blazor.Toolkit

Count: @count

Increment @@ -78,7 +78,7 @@ Interactive pages live in the `.Client` project. Default prerendering still runs ```razor @page "/counter" @rendermode InteractiveWebAssembly -@using Syncfusion.Blazor.Toolkit.Buttons +@using Syncfusion.Blazor.Toolkit

Count: @count

Increment @@ -104,7 +104,7 @@ First visit runs on the server; later visits use the cached WebAssembly bundle. ```razor @page "/counter" @rendermode InteractiveAuto -@using Syncfusion.Blazor.Toolkit.Buttons +@using Syncfusion.Blazor.Toolkit

Count: @count

Increment diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md index e782b661ef..16b2a36472 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/split-webapp-registration.md @@ -1,6 +1,6 @@ -# Split Blazor Web App Service Registration +# Split Blazor Web App Service Registration -> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the `` of **both** projects before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. +> **Framework support.** `Syncfusion.Blazor.Toolkit` 2.0.0 targets `net8.0`, `net9.0`, and `net10.0`. Always check the `` of **both** projects before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. A generated `.Client` project is not a standalone WebAssembly app. The server owns `App.razor`, and the host markup has no `#app` element. Never call `RootComponents.Add("#app")` in `.Client/Program.cs`. @@ -10,7 +10,7 @@ Default prerendering runs WebAssembly and Auto components on the server first. V ```text System.InvalidOperationException: Cannot provide a value for property 'SyncfusionService' on type -'Syncfusion.Blazor.Toolkit.Buttons.SfButton'. There is no registered service of type +'Syncfusion.Blazor.Toolkit.SfButton'. There is no registered service of type 'Syncfusion.Blazor.Toolkit.SyncfusionBlazorToolkitService'. ``` @@ -69,11 +69,11 @@ The first visit runs on the server; later visits use the cached WebAssembly bund ## Component namespaces in both projects -Add the child namespace (for example `@using Syncfusion.Blazor.Toolkit.Buttons`) to the `_Imports.razor` of every project that renders that component. A missing namespace only warns (`RZ10012`) and renders an unstyled unknown element. +Add the single root namespace `@using Syncfusion.Blazor.Toolkit` to the `_Imports.razor` of every project that renders Toolkit components. Domain-specific namespaces from Toolkit 1.x (for example `Syncfusion.Blazor.Toolkit.Buttons`) were removed in 2.0. A missing root namespace only warns (`RZ10012`) and renders an unstyled unknown element. ## Theme CSS in a Split Web App -Add the stylesheet link to the existing `` in `Components/App.razor`; do not replace the file. Both Server and Client components use it. Fluent is the default; `highcontrast.min.css` is also valid. +Add the stylesheet link to the existing `` in `Components/App.razor`; do not replace the file. Both Server and Client components use it. Fluent is the default; `highcontrast.min.css` is also valid. From 2.0, `SfThemeRoot` emits the shared theme layer when Toolkit components render. ```html diff --git a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md index 4645c4b8a7..ca822928f5 100644 --- a/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md +++ b/plugins/dotnet-blazor/skills/syncfusion-blazor-toolkit-install/references/theme-and-host-files.md @@ -1,8 +1,8 @@ -# Theme and Host Files Reference +# Theme and Host Files Reference -Toolkit components require CSS theming. Use the host file for your app type and link the Fluent stylesheet there. +Toolkit components require CSS theming. Use the host file for your app type and link the Fluent stylesheet there. From Toolkit 2.0, component styles use Blazor CSS isolation and the shared theme layer is emitted at render time by `SfThemeRoot`. -> **Framework support.** `Syncfusion.Blazor.Toolkit` 1.0.2 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. +> **Framework support.** `Syncfusion.Blazor.Toolkit` 2.0.0 targets `net8.0`, `net9.0`, and `net10.0`. Always check the project's `` before installation. On `net6.0`, `net7.0`, or older frameworks, the package may restore successfully, but Toolkit assemblies are not available to the application, so the build later fails with errors such as `CS0246: The type or namespace name 'Syncfusion' could not be found`. Do not proceed with Toolkit installation on unsupported frameworks. Recommend upgrading the application to .NET 8 or later first, then continue with the installation steps. > **Never replace the whole host file.** The examples below show only the lines to add to the template-generated host file. Keep `HeadOutlet`, `Routes`, the render-mode directive on `Routes`, and the existing script tags (`_framework/blazor.web.js`, `_framework/blazor.webassembly.js`, or `blazor.server.js`) exactly as the template generated them. @@ -30,17 +30,20 @@ Toolkit components require CSS theming. Use the host file for your app type and ``` +## Theme delivery model (2.0) + +- **Host stylesheet** (`fluent.min.css` / `highcontrast.min.css`): still linked in the host file as above. +- **Shared theme layer**: `SfThemeRoot` writes a single `