[Docs][SKCanvasElement] Add Troubleshooting to help Consumer and MCP Agents identify and relyably solve problem when happening while implementing this control

### What would you like clarification on? 🤔

Please add a Troubleshooting to `SKCanvasElement` Docs that allow regular Consumers, but also MCP's to identify the root cause of this problem at development time and provide clear information how to solve this.

To solve this in the future and improve the Consumer expirience with Uno but also with using Agents with Uno MCP, I asked the Agent to collect all Information we got when the Issue did happen and also, create a short Docs addition guide, following the `How-To-Template.md` we usually use for regular How-To articles as Contributors. Feel free to us this for the future improved docs guide.

> [!IMPORTANT]
> Agent does also fail updating your SKCanvasElementShowcase Sample, so great opportunity for the MCP training Team to ensure this is ensured to be fix-able from the Agent! 🚀 

*Agent suggestion* for Improving the Docs Article to ensure it would have been able to fix this for me:

---
# SKCanvasElement Documentation Enhancement Proposal

This document proposes improvements to the Uno Platform `SKCanvasElement` documentation to address common build errors encountered when using `SKCanvasElement` with WinAppSDK targets.

## 1. Main Article Enhancement

### Location
Add the following **Troubleshooting** section in the `SKCanvasElement.md` article immediately after the "Full example" section and before "WinAppSDK Specifics".

### Content

````markdown
## Troubleshooting

### Build Errors on WinAppSDK Targets (`net10.0-windows10.XXXXX`)

When using `SKCanvasElement` in projects that target **WinAppSDK** (Target Framework Moniker: `net10.0-windows10.XXXXX` or similar), you may encounter compilation errors even though the code appears correct.

#### Common Error Symptoms

**AI Agents and Developers**: If you see these errors, follow the resolution steps below:

| Error Code | Description | Affected Code |
|------------|-------------|---------------|
| **CS0012** | `The type 'FrameworkElement' is defined in an assembly that is not referenced. You must add a reference to assembly 'Uno.UI, Version=255.255.255.255, Culture=neutral, PublicKeyToken=null'.` | Any member of your `SKCanvasElement` subclass |
| **CS0115** | `'YourClass.RenderOverride(SKCanvas, Size)': no suitable method found to override` | `RenderOverride` method signature |
| **CS0534** | `'YourClass' does not implement inherited abstract member 'SKCanvasElement.RenderOverride(SKCanvas, Size)'` | Class declaration |
| **CS0103** | `The name 'GetValue'/'SetValue' does not exist in the current context` | Dependency property accessors |

#### Root Cause

These errors occur specifically when:

- **Target Platform**: Your project includes `net10.0-windows10.XXXXX` (WinAppSDK) in `<TargetFrameworks>`
- **UnoFeatures**: You have `SkiaRenderer` enabled (with or without the `Skia` feature)
- **Platform Conflict**: WinAppSDK uses **native rendering** by default, not Skia rendering, causing type resolution conflicts

> [!NOTE]
> As stated in the [Using Skia Desktop](xref:Uno.Skia.Desktop#using-skia-desktop) documentation:
> "When using WinAppSDK, the **native rendering engine** is always used, regardless of whether Skia or Native is enabled in `UnoFeatures`."

> [!TIP]
> For a complete working example of `SKCanvasElement` usage, see the [SKCanvasElementShowcase](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SKCanvasElementShowcase/SKCanvasElementShowcase) sample in the Uno.Samples repository.

#### Resolution: Add x64/ARM64 Build Configuration

[!INCLUDE [](includes/winappsdk-skia-configuration.md)]
````

---

## 2. New Reusable Include File

### Location
Create new file: `includes/winappsdk-skia-configuration.md`

### Purpose
Provides step-by-step guidance for configuring WinAppSDK projects to work with `SKCanvasElement`. This include can be referenced from multiple documentation pages.

### Content

````markdown


### Prerequisites

- **For ARM64 support**: Install ARM64 build tools via Visual Studio Installer if not already present
  - Go to **Tools** > **Get Tools and Features**
  - Under **Individual components**, search for "ARM64" and install:
    - `MSVC v143 - VS 2022 C++ ARM64 build tools (Latest)` (or equivalent for your VS version)
    - `.NET SDK ARM64 targeting pack` (for .NET 10 or later)

### Visual Studio 2022/2025 Configuration Steps

1. **Open Configuration Manager**
   - **Method A**: Select **Build** > **Configuration Manager** from the menu
   - **Method B**: Click the **Solution Platforms** dropdown in the toolbar > **Configuration Manager...**

2. **Create New Solution Platform**
   - In the **Active solution platform** dropdown, select **<New...>**
   - In the **New Solution Platform** dialog:
     - **Type or select the new platform**: Choose `x64` (or `ARM64` for ARM devices)
     - **Copy settings from**: Select `Any CPU` or existing platform
     - **Create new project platforms**: ✅ Ensure this checkbox is **checked**
     - Click **OK**

3. **Verify Project Platform Assignment**
   - In **Configuration Manager**, locate your Uno Platform project row
   - Confirm the **Platform** column shows `x64` (or `ARM64`) for both Debug and Release configurations
   - If it shows `<New>` or blank, click the dropdown and select the platform you just created
   - Click **Close**

4. **Rebuild the Solution**
   ```powershell
   # Command line alternative:
   dotnet build -c Debug -f net10.0-windows10.0.26100 /p:Platform=x64
   ```

### Visual Studio Code / Command Line

When building WinAppSDK targets from VS Code or terminal:

```bash
# Explicitly specify the platform
dotnet build -f net10.0-windows10.0.26100 /p:Platform=x64

# For ARM64 devices:
dotnet build -f net10.0-windows10.0.26100 /p:Platform=ARM64
```

### Common Issues with Solution Files

#### Issue: `.slnx` Format Auto-Generated Entries Causing Build Failures

**Symptoms**: After creating x64/ARM64 configurations in Visual Studio 2025, the `.slnx` file gains extra project-specific platform entries that cause:
- `Unknown identifier` errors when reopening in Visual Studio
- Build failures in both Visual Studio and VS Code

**Resolution**:

1. **Close Visual Studio 2025**

2. **Edit the `.slnx` file** in VS Code or a text editor:
   - **Keep** the top-level `<Configurations>` section:
     ```xml
<Solution>
  <Configurations>
    <Platform Name="Any CPU" />
    <Platform Name="ARM" />
    <Platform Name="ARM64" />
    <Platform Name="iPhone" />
    <Platform Name="iPhoneSimulator" />
    <Platform Name="x64" />
    <Platform Name="x86" />
  </Configurations>
  <Folder Name="/Solution Items/">
    <File Path=".editorconfig" />
    <File Path=".gitignore" />
    <File Path=".vsconfig" />
    <File Path="Directory.Build.props" />
    <File Path="Directory.Build.targets" />
    <File Path="Directory.Packages.props" />
    <File Path="global.json" />
  </Folder>
  <Project Path="SKCanvasElementShowcase/SKCanvasElementShowcase.csproj">
    <Deploy />
  </Project>
</Solution>
     ```
   
   - **Remove** any auto-generated project-specific platform mappings that appear **inside** `<Project>` elements
     (These often appear as nested `<Configuration>` or `<Platform>` tags under individual projects)

3. **Save** and reopen the solution in Visual Studio

> [!TIP]
> For `.sln` format solutions, Visual Studio manages platform mappings correctly. The `.slnx` format is newer and may require manual cleanup in Visual Studio 2025 Preview/RC builds.

### Additional WinAppSDK-Specific Settings

Some WinAppSDK projects may require additional configuration in the `.csproj`:

```xml
<PropertyGroup Condition="'$(TargetFramework)' == 'net10.0-windows10.0.26100'">
  
  <Platforms>x64;ARM64</Platforms>
</PropertyGroup>
```

#### Publish Profiles

> [!NOTE]
> You typically do **not** need to modify `Platforms/Windows/Properties/PublishProfiles/` files. Visual Studio handles these automatically when you create platform configurations via Configuration Manager.

### Verification

After configuration, verify the build succeeds:

```bash
dotnet build -f net10.0-windows10.0.26100 /p:Platform=x64
```

Expected output should include:
```
Build succeeded.
    0 Warning(s)
    0 Error(s)
```

### Reference Documentation

- [Configure projects to target platforms (Visual Studio)](https://learn.microsoft.com/en-us/visualstudio/ide/how-to-configure-projects-to-target-platforms)
- [Add ARM support to Windows apps](https://learn.microsoft.com/en-us/windows/arm/add-arm-support)
- [Uno Platform Skia Desktop Documentation](xref:Uno.Skia.Desktop)
- **[SKCanvasElementShowcase Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SKCanvasElementShowcase/SKCanvasElementShowcase)** - Official Uno Platform sample demonstrating `SKCanvasElement` usage across all platforms
````

---

## 3. Updated "WinAppSDK Specifics" Section

### Location
Replace the existing "WinAppSDK Specifics" section in `SKCanvasElement.md`

### Content

````markdown
## WinAppSDK Specifics

When using `SKCanvasElement` with **WinAppSDK** targets (`net10.0-windows10.XXXXX`), platform-specific build configuration is required.

### Required: x64 or ARM64 Configuration

WinAppSDK requires explicit platform targeting (cannot use `Any CPU`). You **must** create and use an `x64` or `ARM64` solution configuration.

[!INCLUDE [](includes/winappsdk-skia-configuration.md)]

### Why This Is Required

Unlike other Uno Platform targets that use Skia rendering by default:

- **WinAppSDK always uses native rendering**, even when `SkiaRenderer` is enabled in `UnoFeatures`
- The native renderer requires platform-specific compilation (`x64` or `ARM64`)
- Without explicit platform configuration, type resolution fails for `FrameworkElement` and related WinUI types

> [!TIP]
> If you see build errors like `CS0012` mentioning `Uno.UI` assembly not found, this indicates you need to add the platform configuration above.

### Debugging

Use the configuration relevant to your development environment:

| Your Device | Configuration | Platform |
|-------------|---------------|----------|
| Windows x64 PC | Debug or Release | `x64` |
| Windows ARM64 PC/Laptop | Debug or Release | `ARM64` |
| Any (for distribution) | Release | Both `x64` **and** `ARM64` |
````

---

## 4. Quick Reference for AI Agents

### Detection Pattern

**Automatic Issue Detection**:

When an AI agent encounters the following combination, it should recognize this as a WinAppSDK + SKCanvasElement configuration issue:

```yaml
Error Pattern:
  - CS0012: "type 'FrameworkElement' is defined in an assembly that is not referenced"
  - CS0012: "assembly 'Uno.UI, Version=255.255.255.255'"
  - CS0115: "no suitable method found to override" (RenderOverride)
  - CS0534: "does not implement inherited abstract member"
  - CS0103: "'GetValue'/'SetValue' does not exist"

Project Pattern:
  - File: *.csproj
  - Contains: <TargetFrameworks> with "net10.0-windows10.XXXXX"
  - Contains: <UnoFeatures> with "SkiaRenderer"

Code Pattern:
  - Class inherits from: SKCanvasElement
  - File uses: using Uno.WinUI.Graphics2DSK;
```

### Quick Fix Command

**Immediate workaround** (VS Code/CLI):
```bash
dotnet build -f net10.0-windows10.0.26100 /p:Platform=x64
```

**Permanent solution**: Follow the Configuration Manager steps in the include file.

### Root Cause Summary

- WinAppSDK (`net10.0-windows10.XXXXX`) uses **native WinUI rendering**
- `SKCanvasElement` requires **Skia rendering infrastructure**
- The conflict creates type resolution errors for `FrameworkElement` base types
- Solution: Explicit `x64`/`ARM64` platform configuration enables proper assembly resolution

---

## 5. Implementation Checklist

### Documentation Team Tasks

- [ ] Review and approve proposed content
- [ ] Create `includes/winappsdk-skia-configuration.md` file
- [ ] Update `controls/SKCanvasElement.md` with Troubleshooting section
- [ ] Replace existing WinAppSDK Specifics section
- [ ] Test DocFX include syntax rendering
- [ ] Validate all cross-reference links (xref:)
- [ ] Verify Microsoft Docs external links
- [ ] Add to review/QA pipeline

### Content Quality Checks

- [ ] Screenshots needed for Configuration Manager steps?
- [ ] Video walkthrough for .slnx issue resolution?
- [ ] **Code sample repository link**: Link to [SKCanvasElementShowcase](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SKCanvasElementShowcase/SKCanvasElementShowcase) sample
- [ ] Localization considerations for error messages?

### Post-Publication

- [ ] Monitor user feedback on clarity
- [ ] Track if AI agents successfully detect and resolve issues
- [ ] Update for Visual Studio 2025 RTM changes to .slnx handling
- [ ] Consider adding to "Getting Started" guides as preventive measure

---

## 6. Benefits of This Proposal

### For Human Developers
- **Clear error identification**: Error codes mapped to specific causes
- **Step-by-step resolution**: Visual Studio and CLI workflows covered
- **Edge case handling**: .slnx format issues documented
- **Time savings**: No need to search forums or file issues

### For AI Agents
- **Pattern detection**: Structured error signatures for automated diagnosis
- **Contextual awareness**: Understanding of TFM + UnoFeatures interaction
- **Actionable guidance**: Direct commands and configuration steps
- **Conversation history**: Reusable include reduces token consumption

### For Uno Platform
- **Reduced support burden**: Common issue self-service resolution
- **Better developer experience**: Frustration reduced for WinAppSDK users
- **Documentation quality**: Proactive troubleshooting vs. reactive FAQ
- **AI-first documentation**: Sets pattern for future AI-assisted development content

---

## 7. Related Issues and Context

### Original Problem Scenario

**Project Configuration**:
- Target Frameworks: `net10.0-desktop`, `net10.0-android`, `net10.0-ios`, `net10.0-browserwasm`, `net10.0-windows10.0.26100`
- UnoFeatures: `SkiaRenderer` enabled
- Custom Control: `WorldMapCanvas : SKCanvasElement`

**Build Failures**:
- All errors appeared only for `net10.0-windows10.0.26100` target
- Other targets (desktop, WASM, mobile) built successfully
- Error messages suggested missing assembly references
- `RenderOverride` method appeared correctly implemented but still flagged as missing

**Resolution**:
- Added `x64` platform configuration via Configuration Manager
- Rebuilt solution with explicit `/p:Platform=x64`
- All errors resolved immediately

### Community Impact

This issue is likely affecting many developers because:
- Single Project templates include WinAppSDK by default
- `SkiaRenderer` is a common UnoFeature for cross-platform rendering
- Error messages don't clearly indicate platform configuration as root cause
- AI coding assistants struggle without explicit documentation

---

## Appendix: Example Error Log

For reference, here's a complete error log that would trigger this troubleshooting guide:

```
Build started...
1>------ Build started: Project: DevTKSS.SantaTrackerApp1, Configuration: Debug Any CPU ------
1>DevTKSS.SantaTrackerApp1 -> C:\...\bin\Debug\net10.0-desktop\DevTKSS.SantaTrackerApp1.dll
1>DevTKSS.SantaTrackerApp1 -> C:\...\bin\Debug\net10.0-browserwasm\DevTKSS.SantaTrackerApp1.dll
1>Controls\WorldMapCanvas.cs(9,38): error CS0012: The type 'FrameworkElement' is defined in an assembly that is not referenced. You must add a reference to assembly 'Uno.UI, Version=255.255.255.255, Culture=neutral, PublicKeyToken=null'.
1>Controls\WorldMapCanvas.cs(54,29): error CS0115: 'WorldMapCanvas.RenderOverride(SKCanvas, Size)': no suitable method found to override
1>Controls\WorldMapCanvas.cs(9,21): error CS0534: 'WorldMapCanvas' does not implement inherited abstract member 'SKCanvasElement.RenderOverride(SKCanvas, Size)'
1>Controls\WorldMapCanvas.cs(35,16): error CS0103: The name 'GetValue' does not exist in the current context
1>Controls\WorldMapCanvas.cs(36,16): error CS0103: The name 'SetValue' does not exist in the current context
========== Build: 3 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========
========== Build completed at 01:50 and took 12.765 seconds ==========
```

**Target Framework Analysis**:
- ✅ `net10.0-desktop` - Built successfully (uses Skia rendering)
- ✅ `net10.0-browserwasm` - Built successfully (uses Skia rendering)
- ❌ `net10.0-windows10.0.26100` - Build failed (WinAppSDK native rendering conflict)

**Solution Applied**:
```powershell
# After adding x64 platform configuration:
dotnet build -f net10.0-windows10.0.26100 /p:Platform=x64
# Result: Build succeeded with 0 errors
```

---

**Proposal Status**: Draft for Review  
**Target Uno Platform Version**: 6.x and later  
---
*(End of Agent Proposal)*

Trying to implement from above there are still some issues, I would like the Uno Team to check and hopefully find a solution:
- with the csproj `Platforms` Tag usage, the regular Condition usage still shows the mentioned Errors independant on Selecting "Build Solution" or "Build Project" but running in Debugger for Desktop, the the Build succeeds.
- Tryed with "Using the Uno.Sdk" Article provided `Choose` MSBuild tag for Windows  and the Warnings are finally gone **IF** you specify your Build/Debug Target as e.g. Desktop!

  Used setup for this:
  ```xml
    <Choose>
      <When Condition="$(TargetFramework.Contains('windows10'))" Label="SKCanvasElement requirement for Windows TFM">
        <PropertyGroup>
          <Platforms>ARM64;x64</Platforms>
        </PropertyGroup>
      </When>
    </Choose>
  ```
  not sure if we need a `Otherwhise` entry also for the other targets, to not restrict them to those Targets, but since Building Debug + AnyCPU succeeds for the Desktop Target, I would assume we dont need this other tag.

- The `Choose` Block does not solve this issue as soon as:
  - The Agent builds the Project -> This results in the Agent will up from there go to iterate over this file, even if the `*.instructions.md` includes the Instruction, to NOT do this. So you either can Stop him + repeat the Restriction for this in Chat from time to time (=> spend your Prompts per month for doing so) or spend your tokens of the current prompt on this (seems like) not-solveable errors.
  - "Build Solution" (I am using .slnx which supported tags are currently still lacking on Documentation except from that one Solution wide `<Configurations>` Section, which would not fullfill the docs instruction "apply to your Project"

### Concern 📚

- Developing with Uno 🛠️
- Using Uno Docs MCP

### Renderer 🎨

- [ ] Skia
- [x] Native

### Affected platforms 📱💻🖥️

Windows App SDK, Build tasks

### Any feedback? 💬

I recently asked Agent with initialized uno knowledge and specifically sending him to inspect and compare the Implementation we have with any guidiance the Uno Docs MCP can provide for this Control, but it ended up without a working solution.
After comparing the Uno.Sample for the `SKCanvasElement` I myself was able, to identify the missing `ARM64` Target to be the problem, because removing the Windows Target was not longer having a problem and I, same as the Agent seem to have missed that small part at the end for WinAppSdk Specifics.

- Updated to latest version using slnx here https://github.com/unoplatform/Uno.Samples/pull/905 so the consumer can compare in migration szenarios with a working sample 👍

[Docs][SKCanvasElement] Add Troubleshooting to help Consumer and MCP Agents identify and relyably solve problem when happening while implementing this control #22214

Description

What would you like clarification on? 🤔

SKCanvasElement Documentation Enhancement Proposal

1. Main Article Enhancement

Location

Content

2. New Reusable Include File

Location

Purpose

Content

3. Updated "WinAppSDK Specifics" Section

Location

Content

4. Quick Reference for AI Agents

Detection Pattern

Quick Fix Command

Root Cause Summary

5. Implementation Checklist

Documentation Team Tasks

Content Quality Checks

Post-Publication

6. Benefits of This Proposal

For Human Developers

For AI Agents

For Uno Platform

7. Related Issues and Context

Original Problem Scenario

Community Impact

Appendix: Example Error Log

Proposal Status: Draft for Review Target Uno Platform Version: 6.x and later

Concern 📚

Renderer 🎨

Affected platforms 📱💻🖥️

Any feedback? 💬

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Proposal Status: Draft for Review
Target Uno Platform Version: 6.x and later