|
| 1 | +# Telerik WPF Upgrade Plugin |
| 2 | + |
| 3 | +Copilot CLI plugin that integrates with the Microsoft Upgrade Agent to modernize |
| 4 | +WPF applications that use Telerik UI for WPF. |
| 5 | + |
| 6 | +## Microsoft Upgrade Agent Resources |
| 7 | + |
| 8 | +This plugin extends Microsoft's Upgrade Agent. These references cover the host |
| 9 | +plugin, setup, samples, and instruction-authoring guidance: |
| 10 | + |
| 11 | +- [Microsoft Upgrade Agent plugin repository](https://github.com/microsoft/upgrade-agent-plugins) |
| 12 | +- [Upgrade Agent samples documentation](https://github.com/microsoft/upgrade-agent-samples/tree/ap/AddInitialSamples/docs) |
| 13 | +- [Instruction size and token budget guidelines](https://github.com/microsoft/upgrade-agent-samples/blob/ap/AddInitialSamples/docs/07-instruction-size-and-tokens.md) |
| 14 | +- [GitHub Copilot upgrade online docs](https://learn.microsoft.com/en-us/dotnet/core/porting/github-copilot-upgrade/overview) |
| 15 | + |
| 16 | +## Prerequisites |
| 17 | + |
| 18 | +- [GitHub Copilot CLI](https://docs.github.com/en/copilot) with Upgrade Agent support |
| 19 | +- A [Telerik user account](https://www.telerik.com/account/) with an active |
| 20 | + [DevCraft or Telerik UI for WPF license](https://www.telerik.com/purchase/individual/wpf.aspx) |
| 21 | + (or a [free trial](https://www.telerik.com/try/ui-for-wpf)) |
| 22 | +- [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download) or later — required |
| 23 | + for `dnx`, which runs the [Telerik.WPF.MCP](https://www.nuget.org/packages/Telerik.WPF.MCP) |
| 24 | + tool server (the target application can be on any supported .NET version, |
| 25 | + including .NET Framework) |
| 26 | + |
| 27 | +## Installation |
| 28 | + |
| 29 | +Add the `telerik/ai-plugins` marketplace, then install the plugin. |
| 30 | + |
| 31 | +**GitHub Copilot CLI** |
| 32 | +```bash |
| 33 | +copilot plugin marketplace add telerik/ai-plugins |
| 34 | +copilot plugin install telerik-wpf-upgrade-plugin@telerik-ai-plugins |
| 35 | +``` |
| 36 | + |
| 37 | +## What It Does |
| 38 | + |
| 39 | +This plugin registers three modernization scenarios. The agent picks the one |
| 40 | +that matches the user's intent: |
| 41 | + |
| 42 | +| Scenario | When | What happens | |
| 43 | +|----------|------|--------------| |
| 44 | +| **telerik-wpf-version-upgrade** | The project already uses Telerik and the user wants a newer Telerik version | Upgrades the Telerik package version, migrates assembly refs to NuGet, sets up licensing, and fixes breaking changes | |
| 45 | +| **telerik-wpf-assembly-to-nuget** | The user only wants direct Telerik assembly references replaced with NuGet packages, with no version or .NET target change | Detects the current Telerik version, reference style, and Xaml/NoXaml flavor, sets up the right NuGet feed, maps assemblies to packages, and migrates the project | |
| 46 | +| **telerik-wpf-licensing** | The user wants Telerik license activation set up, fixed, or migrated | Detects the licensing mechanism, repairs activation, and verifies builds | |
| 47 | + |
| 48 | +`telerik-wpf-assembly-to-nuget` is a standalone, narrower scenario for when |
| 49 | +only the reference style needs to change. |
| 50 | + |
| 51 | +### .NET version upgrades |
| 52 | + |
| 53 | +Neither scenario changes the project's `<TargetFramework>`. When the user also |
| 54 | +wants a different .NET version (.NET Framework → .NET, or .NET 8 → .NET 10), run |
| 55 | +the Microsoft `dotnet-version-upgrade` scenario **first** — the resulting .NET |
| 56 | +target determines which Telerik versions are available — then run |
| 57 | +`telerik-wpf-version-upgrade`. The scenario extensions below attach the |
| 58 | +Telerik rules to the Microsoft scenarios themselves. |
| 59 | + |
| 60 | +### Additive concerns |
| 61 | + |
| 62 | +Both scenarios detect and handle: |
| 63 | +- **Assembly → NuGet migration** — replaces direct DLL references with the |
| 64 | + minimal set of Telerik UI for WPF NuGet packages of the project's flavor, |
| 65 | + resolved from the assembly reference maps |
| 66 | +- **License activation** — for Q1 2025+ projects, Telerik control NuGet packages |
| 67 | + bring `Telerik.Licensing` transitively so the shared license file activates the application |
| 68 | + |
| 69 | +### Xaml vs NoXaml |
| 70 | + |
| 71 | +Telerik UI for WPF ships two assembly sets: **Xaml** (styles embedded in the |
| 72 | +control assemblies, themes applied with `StyleManager`) and **NoXaml** (no |
| 73 | +styles in the control assemblies, themes applied as implicit styles). |
| 74 | + |
| 75 | +- The flavor is detected per project and **always preserved** — no scenario |
| 76 | + switches Xaml ↔ NoXaml or adds packages of the other flavor. |
| 77 | +- A **mixed** flavor (Xaml and NoXaml in one project or one application) is a |
| 78 | + blocker: the agent reports the conflicting references and asks which flavor |
| 79 | + to converge on before migrating anything. |
| 80 | +- NoXaml projects need their theme packages |
| 81 | + (`Telerik.Windows.Themes.<Theme>.for.Wpf`) alongside the control packages. |
| 82 | +- Theme XAML copied from the `Themes.Implicit` folder is version-specific and |
| 83 | + is not updated by NuGet or retargeting — it must be refreshed from the new |
| 84 | + version's folder (and from the `NET` folder after a .NET Framework → .NET |
| 85 | + move). The agent asks for the folder and never hand-edits theme XAML. |
| 86 | + |
| 87 | +### Licensing |
| 88 | + |
| 89 | +The Telerik license key is shared between the MCP server and NuGet-based |
| 90 | +application activation. `telerik-wpf-version-upgrade` blocks on it because its |
| 91 | +MCP tool calls need it; `telerik-wpf-assembly-to-nuget` checks for it but |
| 92 | +continues without blocking, since its work doesn't call MCP tools. For |
| 93 | +Q1 2025+ projects that use Telerik NuGet packages, `Telerik.Licensing` is a |
| 94 | +transitive dependency, so the same key activates the application build |
| 95 | +without an explicit package reference. A .NET Framework project that retains |
| 96 | +direct Telerik assembly references must install `Telerik.Licensing` |
| 97 | +explicitly. |
| 98 | + |
| 99 | +Save the shared license file to `%AppData%\Telerik\telerik-license.txt`, or as |
| 100 | +`telerik-license.txt` in the project or solution root, before running a |
| 101 | +scenario. |
| 102 | + |
| 103 | +## MCP Server |
| 104 | + |
| 105 | +The plugin uses the [Telerik.WPF.MCP](https://www.nuget.org/packages/Telerik.WPF.MCP) |
| 106 | +NuGet package, which exposes: |
| 107 | + |
| 108 | +| Tool | What it does | |
| 109 | +|------|--------------| |
| 110 | +| `telerik-upgrade-assistant` | Breaking-change detection between Telerik versions (via Telerik CLI) | |
| 111 | +| `telerik-wpf-assistant` | Component API guidance | |
| 112 | + |
| 113 | +These run server-side against your project. Path arguments are elicited from |
| 114 | +you if the agent passes one that can't be resolved. |
| 115 | + |
| 116 | +`telerik-upgrade-assistant` additionally requires the Telerik CLI: |
| 117 | + |
| 118 | +```bash |
| 119 | +dotnet tool install --global Telerik.CLI |
| 120 | +``` |
| 121 | +## Skills |
| 122 | + |
| 123 | +### Scenarios |
| 124 | + |
| 125 | +| Skill | Purpose | |
| 126 | +|-------|---------| |
| 127 | +| `telerik-wpf-version-upgrade` | Upgrade the Telerik UI for WPF version with breaking-changes detection | |
| 128 | +| `telerik-wpf-assembly-to-nuget` | Migrate direct Telerik assembly references to NuGet packages, with no version or .NET target change | |
| 129 | +| `telerik-wpf-licensing` | Set up, fix, or migrate Telerik license activation | |
| 130 | + |
| 131 | +### Lazy (loaded on demand) |
| 132 | + |
| 133 | +| Skill | Purpose | |
| 134 | +|-------|---------| |
| 135 | +| `telerik-wpf-breaking-changes` | Detect and fix breaking changes via `telerik-upgrade-assistant` | |
| 136 | +| `telerik-wpf-dependency-management` | NuGet package management and assembly→NuGet migration | |
| 137 | +| `telerik-wpf-license-detection` | Read-only detection of the current Telerik licensing mechanism, artifacts, and entry-point shape | |
| 138 | +| `telerik-wpf-license-key-setup` | Obtain and place a license key for the recommended NuGet-based path, or the script-key path | |
| 139 | +| `telerik-wpf-license-plugin-hosts` | Set up or fix licensing for add-in/plugin (hybrid) hosts with no standard entry point | |
| 140 | +| `telerik-wpf-license-nuget-migration` | Move a project from script-key licensing to the NuGet-based `Telerik.Licensing` model | |
| 141 | +| `telerik-wpf-license-diagnostics` | Map licensing symptoms and `TKL*` codes to causes and fixes | |
| 142 | +| `telerik-wpf-license-verification` | Build and confirm a licensing setup actually activates | |
| 143 | +| `telerik-wpf-component-guidance` | Component API help via `telerik-wpf-assistant` | |
| 144 | +| `telerik-wpf-reference-detection` | Detect a project's current Telerik version, reference style (assembly / NuGet / packages.config), and flavor | |
| 145 | +| `telerik-wpf-xaml-flavor` | Detect the Xaml/NoXaml flavor, flag mixed usage, and check the theming setup after a change | |
| 146 | +| `telerik-wpf-nuget-feed-setup` | Determine, validate, and set up the NuGet feed needed for a given Telerik version | |
| 147 | +| `telerik-wpf-assembly-mapping` | Map Telerik assembly references to their owning NuGet packages for the project's flavor and target framework | |
| 148 | +| `telerik-wpf-reference-migration` | Edit a project file to replace assembly references with PackageReference | |
| 149 | +| `telerik-wpf-reference-retargeting` | Retarget direct assembly references to a new Telerik version without changing the delivery method or flavor | |
| 150 | +| `telerik-wpf-migration-verification` | Restore, build, run the NoXaml theming checks, and report after a reference migration | |
| 151 | + |
| 152 | +### Scenario Extensions (injected into host scenarios) |
| 153 | + |
| 154 | +These never appear as user-selectable scenarios. They attach Telerik-specific |
| 155 | +rules to the Microsoft `dotnet-*` scenarios the host already owns, reusing the |
| 156 | +same lazy skills above rather than duplicating the migration mechanics. |
| 157 | + |
| 158 | +| Skill | Extends | Purpose | |
| 159 | +|-------|---------|---------| |
| 160 | +| `telerik-wpf-for-dotnet-framework-upgrade` | `dotnet-framework-version-upgrade` | Verify Telerik still supports net481; offer, never force, the NuGet migration; preserve the flavor | |
| 161 | +| `telerik-wpf-for-dotnet-version-upgrade` | `dotnet-version-upgrade` | Handle both modern→newer-modern and Framework→modern sources; NuGet migration is mandatory on both whenever assembly references are found | |
| 162 | + |
| 163 | +## Plugin Structure |
| 164 | + |
| 165 | +``` |
| 166 | +telerik-wpf-upgrade-plugin/ |
| 167 | +├── .claude-plugin/ |
| 168 | +│ └── plugin.json |
| 169 | +├── upgrade-extension.json |
| 170 | +├── README.md |
| 171 | +└── upgrade/ |
| 172 | + └── skills/ |
| 173 | + ├── scenarios/ |
| 174 | + │ ├── telerik-wpf-version-upgrade/ |
| 175 | + │ │ ├── SKILL.md |
| 176 | + │ │ ├── assessment.md |
| 177 | + │ │ ├── planning.md |
| 178 | + │ │ ├── execution.md |
| 179 | + │ │ └── post-completion.md |
| 180 | + │ ├── telerik-wpf-assembly-to-nuget/ |
| 181 | + │ │ ├── SKILL.md |
| 182 | + │ │ ├── assessment.md |
| 183 | + │ │ ├── planning.md |
| 184 | + │ │ ├── execution.md |
| 185 | + │ │ └── post-completion.md |
| 186 | + │ └── telerik-wpf-licensing/ |
| 187 | + │ ├── SKILL.md |
| 188 | + │ ├── assessment.md |
| 189 | + │ ├── planning.md |
| 190 | + │ ├── execution.md |
| 191 | + │ └── post-completion.md |
| 192 | + ├── lazy/ |
| 193 | + │ ├── telerik-wpf-assembly-mapping/ |
| 194 | + │ │ ├── SKILL.md |
| 195 | + │ │ └── ref/ |
| 196 | + │ │ ├── assembly-map-noxaml.md |
| 197 | + │ │ ├── assembly-map-shared.md |
| 198 | + │ │ └── assembly-map-xaml.md |
| 199 | + │ ├── telerik-wpf-breaking-changes/ |
| 200 | + │ │ └── SKILL.md |
| 201 | + │ ├── telerik-wpf-component-guidance/ |
| 202 | + │ │ └── SKILL.md |
| 203 | + │ ├── telerik-wpf-dependency-management/ |
| 204 | + │ │ ├── SKILL.md |
| 205 | + │ │ └── ref/ |
| 206 | + │ │ └── version-compatibility.md |
| 207 | + │ ├── telerik-wpf-license-detection/ |
| 208 | + │ │ └── SKILL.md |
| 209 | + │ ├── telerik-wpf-license-diagnostics/ |
| 210 | + │ │ └── SKILL.md |
| 211 | + │ ├── telerik-wpf-license-key-setup/ |
| 212 | + │ │ └── SKILL.md |
| 213 | + │ ├── telerik-wpf-license-nuget-migration/ |
| 214 | + │ │ └── SKILL.md |
| 215 | + │ ├── telerik-wpf-license-plugin-hosts/ |
| 216 | + │ │ └── SKILL.md |
| 217 | + │ ├── telerik-wpf-license-verification/ |
| 218 | + │ │ └── SKILL.md |
| 219 | + │ ├── telerik-wpf-migration-verification/ |
| 220 | + │ │ └── SKILL.md |
| 221 | + │ ├── telerik-wpf-nuget-feed-setup/ |
| 222 | + │ │ └── SKILL.md |
| 223 | + │ ├── telerik-wpf-reference-detection/ |
| 224 | + │ │ └── SKILL.md |
| 225 | + │ ├── telerik-wpf-reference-migration/ |
| 226 | + │ │ └── SKILL.md |
| 227 | + │ ├── telerik-wpf-reference-retargeting/ |
| 228 | + │ │ └── SKILL.md |
| 229 | + │ └── telerik-wpf-xaml-flavor/ |
| 230 | + │ └── SKILL.md |
| 231 | + └── extensions/ |
| 232 | + ├── telerik-wpf-for-dotnet-framework-upgrade/ |
| 233 | + │ ├── SKILL.md |
| 234 | + │ └── scopes/ |
| 235 | + │ ├── assessment.md |
| 236 | + │ ├── planning.md |
| 237 | + │ └── execution.md |
| 238 | + └── telerik-wpf-for-dotnet-version-upgrade/ |
| 239 | + ├── SKILL.md |
| 240 | + └── scopes/ |
| 241 | + ├── assessment.md |
| 242 | + ├── planning.md |
| 243 | + └── execution.md |
| 244 | +``` |
0 commit comments