syncfusion-winui-getting-started

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinUI Setup and Licensing

Syncfusion WinUI组件的设置与许可实现

When to Use This Skill

何时使用本指南

Use this skill when:

Users need to install Syncfusion WinUI components
License registration or validation is required
System requirements must be verified
Installation errors occur
Configuration (themes, localization, RTL) is needed
Troubleshooting setup or licensing issues
Upgrading from trial to purchased license
Setting up in CI/CD environments

在以下场景中使用本指南：

用户需要安装Syncfusion WinUI组件
需要进行许可证注册或验证
必须验证系统要求
出现安装错误
需要进行配置（主题、本地化、RTL）
排查设置或许可相关问题
从试用版升级至付费许可证
在CI/CD环境中进行设置

Setup Overview

设置概述

Syncfusion WinUI components require three core setup phases:

Prerequisites & System Check - Verify OS, .NET version, and compatibility
License Registration - Register and validate Syncfusion license
Package Installation & Configuration - Install via NuGet and configure features

Each phase builds on the previous, and skipping any step can cause downstream issues.

Syncfusion WinUI组件需要三个核心设置阶段：

先决条件与系统检查 - 验证操作系统、.NET版本及兼容性
许可证注册 - 注册并验证Syncfusion许可证
包安装与配置 - 通过NuGet安装并配置功能

每个阶段都基于前一阶段，跳过任何步骤都可能导致后续问题。

Documentation and Navigation Guide

文档与导航指南

System Requirements & Prerequisites

系统要求与先决条件

📄 Read: references/system-requirements.md

WinUI and Windows OS compatibility
.NET version requirements
Visual Studio prerequisites
Hardware and browser requirements
Target framework compatibility

📄 阅读： references/system-requirements.md

WinUI与Windows操作系统兼容性
.NET版本要求
Visual Studio先决条件
硬件与浏览器要求
目标框架兼容性

Licensing Overview

许可概述

📄 Read: references/licensing-overview.md

License types and options
Where to obtain license keys
License registration process
Community license eligibility
Trial vs. purchased license differences

📄 阅读： references/licensing-overview.md

许可证类型与选项
许可证密钥获取渠道
许可证注册流程
社区许可证资格
试用版与付费版的差异

Installation and Package Setup

安装与包设置

📄 Read: references/installation-setup.md

NuGet package installation steps
Namespace registration
Online installer configuration
Offline installer download and setup
Verifying successful installation

📄 阅读： references/installation-setup.md

NuGet包安装步骤
命名空间注册
在线安装程序配置
离线安装程序下载与设置
验证安装是否成功

License Validation and Activation

许可证验证与激活

📄 Read: references/license-validation.md

License key registration in code
Offline license validation
Internet connection requirements
Common license errors and solutions
Trial to purchased upgrade process

📄 阅读： references/license-validation.md

代码中的许可证密钥注册
离线许可证验证
网络连接要求
常见许可证错误及解决方案
从试用版升级至付费版的流程

Theming

主题设置

📄 Read: references/theming.md

Available themes (Fluent, Material, WinUI)
Setting and switching themes
System theme detection
Custom theme creation
Theme persistence

📄 阅读： references/theming.md

可用主题（Fluent、Material、WinUI）
主题设置与切换
系统主题检测
自定义主题创建
主题持久化

Localization and Language Support

本地化与语言支持

📄 Read: references/localization.md

Supported languages and culture codes
Setting application language (WinUI-specific methods)
Localizing with .resw files (resource-based approach)
Localizing without .resw files (ILocalizationProvider and programmatic approach)
Custom resource files and editing default strings
RTL (Right-to-Left) language support
Dynamic language switching

📄 阅读： references/localization.md

支持的语言与区域代码
设置应用语言（WinUI专属方法）
使用.resw文件进行本地化（基于资源的方式）
不使用.resw文件的本地化（ILocalizationProvider与程序化方式）
自定义资源文件与编辑默认字符串
RTL（从右到左）语言支持
动态语言切换

Accessibility and Compact Sizing

无障碍与紧凑布局

📄 Read: references/configuration-basics.md

Screen reader support
Automation properties and ARIA
Keyboard navigation
High contrast mode
Compact sizing options

📄 阅读： references/configuration-basics.md

屏幕阅读器支持
自动化属性与ARIA
键盘导航
高对比度模式
紧凑布局选项

Troubleshooting Installation

安装故障排查

📄 Read: references/troubleshooting-installation.md

Installation error solutions
NuGet restore and package issues
License validation troubleshooting
Configuration problem fixes
Getting support and debugging

📄 阅读： references/troubleshooting-installation.md

安装错误解决方案
NuGet还原与包相关问题
许可证验证故障排查
配置问题修复
获取支持与调试方法

Upgrades and Patches

升级与补丁

📄 Read: references/upgrade-and-patches.md

Upgrading from trial to purchased license
Applying service packs and patches
Version upgrade considerations
Maintaining existing installations
Rollback procedures

📄 阅读： references/upgrade-and-patches.md

从试用版升级至付费许可证
应用服务包与补丁
版本升级注意事项
维护现有安装
回滚流程

Quick Start Example

快速入门示例

csharp

// 1. Register License (in App.xaml.cs or MainWindow.xaml.cs)
using Syncfusion.Licensing;

public partial class App : Application
{
    public App()
    {
        // Register your license key before using any Syncfusion component
        SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY");
        this.InitializeComponent();
    }
}

// 2. Add namespaces in XAML
xmlns:syncfusion="using:Syncfusion.UI.Xaml.Controls"

// 3. Use components
<syncfusion:SfButton Content="Click Me" />

csharp

// 1. 注册许可证（在App.xaml.cs或MainWindow.xaml.cs中）
using Syncfusion.Licensing;

public partial class App : Application
{
    public App()
    {
        // 在使用任何Syncfusion组件之前注册许可证密钥
        SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY");
        this.InitializeComponent();
    }
}

// 2. 在XAML中添加命名空间
xmlns:syncfusion="using:Syncfusion.UI.Xaml.Controls"

// 3. 使用组件
<syncfusion:SfButton Content="Click Me" />

Common Setup Patterns

常见设置模式

Pattern 1: New Project Setup

模式1：新项目设置

Create WinUI project in Visual Studio
Install Syncfusion NuGet packages:
```
Install-Package Syncfusion.WinUI
```
Register license in App.xaml.cs
Add namespace to XAML
Start using components

在Visual Studio中创建WinUI项目
安装Syncfusion NuGet包：
```
Install-Package Syncfusion.WinUI
```
在App.xaml.cs中注册许可证
向XAML添加命名空间
开始使用组件

Pattern 2: Trial to Production Upgrade

模式2：从试用版升级至生产版

Verify current trial license in code
Obtain purchased license key
Update license registration with new key
Test all components work without trial limitations
Deploy to production

验证代码中的当前试用许可证
获取付费许可证密钥
使用新密钥更新许可证注册
测试所有组件在无试用限制的情况下正常工作
部署至生产环境

Pattern 3: CI/CD Environment Setup

模式3：CI/CD环境设置

Set up offline license validation in build environment
Configure license in environment variables or secure vault
Reference license during build process
Ensure all dependencies are pre-cached
Test build in isolated environment

在构建环境中设置离线许可证验证
在环境变量或安全密钥库中配置许可证
在构建过程中引用许可证
确保所有依赖项已预缓存
在隔离环境中测试构建

Pattern 4: Feature Configuration

模式4：功能配置

Install base Syncfusion package
Configure required theme (FluentLight, FluentDark, MaterialLight, etc.)
Add localization files (.resw approach) OR implement ILocalizationProvider (programmatic approach)
Enable RTL if targeting Arabic/Hebrew users
Enable accessibility features for compliance

安装基础Syncfusion包
配置所需主题（FluentLight、FluentDark、MaterialLight等）
添加本地化文件（.resw方式）或实现ILocalizationProvider（程序化方式）
若面向阿拉伯语/希伯来语用户，启用RTL
启用无障碍功能

Pattern 5: Localization Setup

模式5：本地化设置

Option A - .resw Files Approach:

Download default resource files from Syncfusion GitHub
Create Resources/{language}/ folders in project
Copy .resw files for target languages

Set

ApplicationLanguages.PrimaryLanguageOverride

in code

Test with target language

Option B - Provider Approach:

Create class implementing
```
ILocalizationProvider
```
interface
Implement
```
GetLocalizedString(LocalizationInfo)
```
method
Set
```
LocalizationProvider.Provider
```
before InitializeComponent()
Return custom strings for specific resource keys
Use
```
ResourceAssemblyName
```
for assembly-specific localization

选项A - .resw文件方式：

从Syncfusion GitHub下载默认资源文件
在项目中创建Resources/{语言}/文件夹
复制目标语言的.resw文件

在代码中设置

ApplicationLanguages.PrimaryLanguageOverride

使用目标语言进行测试

选项B - 提供程序方式：

创建实现
```
ILocalizationProvider
```
接口的类
实现
```
GetLocalizedString(LocalizationInfo)
```
方法
在InitializeComponent()之前设置
```
LocalizationProvider.Provider
```
针对特定资源键返回自定义字符串
为程序集特定本地化使用
```
ResourceAssemblyName
```

Key Requirements Checklist

关键要求检查清单

Quick Decision Tree

快速决策树

User needs to...

Install Syncfusion? → Installation and Package Setup
Register license? → Licensing Overview then License Validation
Fix installation error? → Troubleshooting Installation
Check if system is compatible? → System Requirements
Set up themes? → Theming
Configure language/RTL? → Localization and Language Support
Localize with .resw files? → Localization and Language Support (.resw Files section)
Localize programmatically? → Localization and Language Support (Provider Method section)
Set accessibility features? → Accessibility and Compact Sizing
Upgrade trial to paid? → Upgrades and Patches
Validate license in CI/CD? → License Validation

用户需要...

安装Syncfusion？ → 安装与包设置
注册许可证？ → 先查看许可概述，再查看许可证验证
修复安装错误？ → 安装故障排查
检查系统是否兼容？ → 系统要求
设置主题？ → 主题设置
配置语言/RTL？ → 本地化与语言支持
使用.resw文件进行本地化？ → 本地化与语言支持（.resw文件章节）
程序化本地化？ → 本地化与语言支持（提供程序方法章节）
设置无障碍功能？ → 无障碍与紧凑布局
从试用版升级至付费版？ → 升级与补丁
在CI/CD中验证许可证？ → 许可证验证