syncfusion-winui-getting-started

Syncfusion WinUI のセットアップとライセンスの実装

このスキルを使用する場面

次の場合にこのスキルを使用します：

• Syncfusion WinUI コンポーネントをインストールする必要がある場合
• ライセンスの登録または検証が必要な場合
• システム要件を確認する必要がある場合
• インストールエラーが発生した場合
• 構成（テーマ、ローカライズ、RTL）が必要な場合
• セットアップまたはライセンスの問題をトラブルシューティングする場合
• 試用版から購入済みライセンスにアップグレードする場合
• CI/CD 環境でセットアップする場合

セットアップの概要

Syncfusion WinUI コンポーネントのセットアップには、次の 3 つの主要なフェーズが必要です。

1. 前提条件とシステムの確認 - OS、.NET バージョン、互換性を確認します
2. ライセンスの登録 - Syncfusion ライセンスを登録して検証します
3. パッケージのインストールと構成 - NuGet 経由でインストールし、機能を構成します

各フェーズは前のフェーズを踏まえて進みます。手順を省略すると、後続の問題につながる可能性があります。

---

ドキュメントとナビゲーションガイド

システム要件と前提条件

📄 参照: references/system-requirements.md

• WinUI と Windows OS の互換性
• .NET バージョン要件
• Visual Studio の前提条件
• ハードウェアとブラウザーの要件
• ターゲットフレームワークの互換性

ライセンスの概要

📄 参照: references/licensing-overview.md

• ライセンスの種類とオプション
• ライセンスキーの入手先
• ライセンス登録の手順
• Community ライセンスの対象要件
• 試用版と購入済みライセンスの違い

インストールとパッケージのセットアップ

📄 参照: references/installation-setup.md

• NuGet パッケージのインストール手順
• 名前空間の登録
• オンラインインストーラーの構成
• オフラインインストーラーのダウンロードとセットアップ
• インストールの成功確認

ライセンスの検証とアクティベーション

📄 参照: references/license-validation.md

• コードでのライセンスキーの登録
• オフラインでのライセンス検証
• インターネット接続の要件
• よくあるライセンスエラーと解決策
• 試用版から購入済みライセンスへのアップグレード手順

テーマ設定

📄 参照: references/theming.md

• 利用可能なテーマ（Light、Dark）
• テーマの設定と切り替え
• システムテーマの検出

ローカライズと言語サポート

📄 参照: references/localization.md

• サポート対象の言語とカルチャコード
• アプリケーション言語の設定（WinUI 固有の方法）
• .resw ファイルを使用したローカライズ（リソースベースの方法）
• .resw ファイルを使用しないローカライズ（ILocalizationProvider とプログラムによる方法）
• カスタムリソースファイルと既定の文字列の編集
• RTL（右から左へ記述する言語）のサポート
• 動的な言語切り替え

アクセシビリティとコンパクトサイズ

📄 参照: references/configuration-basics.md

• スクリーンリーダーのサポート
• オートメーションプロパティと ARIA
• キーボードナビゲーション
• ハイコントラストモード
• コンパクトサイズのオプション

インストールのトラブルシューティング

📄 参照: references/troubleshooting-installation.md

• インストールエラーの解決策
• NuGet の復元とパッケージの問題
• ライセンス検証のトラブルシューティング
• 構成の問題の修正
• サポートの利用とデバッグ

アップグレードとパッチ

📄 参照: references/upgrade-and-patches.md

• 試用版から購入済みライセンスへのアップグレード
• サービスパックとパッチの適用
• バージョンアップグレード時の考慮事項
• 既存のインストール環境の維持
• ロールバック手順

---

クイックスタートの例

// 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"
xmlns:editors="using:Syncfusion.UI.Xaml.Editors"

// 3. Use components
<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    PlaceholderText="Select an item"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

---

よくあるセットアップパターン

パターン 1：新規プロジェクトのセットアップ

1. Visual Studio で WinUI プロジェクトを作成します
2. Syncfusion NuGet パッケージをインストールします：Install-Package Syncfusion.WinUI
3. App.xaml.cs でライセンスを登録します
4. XAML に名前空間を追加します
5. コンポーネントの使用を開始します

パターン 2：試用版から製品版へのアップグレード

1. コードで現在の試用版ライセンスを確認します
2. 購入したライセンスキーを取得します
3. 新しいキーでライセンス登録を更新します
4. すべてのコンポーネントが試用版の制限なしで動作することをテストします
5. 製品環境にデプロイします

パターン 3：CI/CD 環境のセットアップ

1. ビルド環境でオフラインのライセンス検証を設定します
2. 環境変数またはセキュアなボールトでライセンスを設定します
3. ビルドプロセス中にライセンスを参照します
4. すべての依存関係が事前にキャッシュされていることを確認します
5. 分離された環境でビルドをテストします

パターン 4：機能の設定

1. Syncfusion の基本パッケージをインストールします
2. 必要なテーマ（FluentLight、FluentDark、MaterialLight など）を設定します
3. ローカライズファイル（.resw 方式）を追加するか、ILocalizationProvider を実装します（プログラム方式）
4. アラビア語またはヘブライ語のユーザーを対象にする場合は、RTL を有効にします
5. コンプライアンス対応のため、アクセシビリティ機能を有効にします

パターン 5：ローカライズのセットアップ

オプション A - .resw ファイル方式：

1. Syncfusion GitHub から既定のリソースファイルをダウンロードします
2. プロジェクトに Resources/{language}/ フォルダーを作成します
3. 対象言語の .resw ファイルをコピーします
4. コードで ApplicationLanguages.PrimaryLanguageOverride を設定します
5. 対象言語でテストします

オプション B - プロバイダー方式：

1. ILocalizationProvider インターフェイスを実装するクラスを作成します
2. GetLocalizedString(LocalizationInfo) メソッドを実装します
3. InitializeComponent() の前に LocalizationProvider.Provider を設定します
4. 特定のリソースキーに対してカスタム文字列を返します
5. アセンブリ固有のローカライズには ResourceAssemblyName を使用します

---

主な要件のチェックリスト

Syncfusion WinUI コンポーネントをインストールする前に、次の項目を確認してください。

• OS： Windows 10 バージョン 1809 以降、または Windows 11
• .NET バージョン： .NET 5 以降（通常は .NET 6 以降）
• Visual Studio： VS 2019 v16.9 以降、または VS 2022
• WinUI 3： 最新の安定バージョンがインストール済み
• ライセンス： 有効なライセンスキーを取得済み、または試用版が有効
• NuGet： 最新バージョンに更新済み
• 管理者権限： 一部のインストールシナリオで必要
• インターネット： オンラインでのパッケージ復元に利用可能（またはオフラインパッケージがキャッシュ済み）

---

クイック判定ツリー

ユーザーのニーズ

• Syncfusion をインストールする場合 → インストールとパッケージのセットアップ
• ライセンスを登録する場合 → ライセンスの概要、続いてライセンスの検証
• インストールエラーを修正する場合 → インストールのトラブルシューティング
• システムに互換性があるか確認する場合 → システム要件
• テーマを設定する場合 → テーマ設定
• 言語／RTL を設定する場合 → ローカライズと言語のサポート
• .resw ファイルでローカライズする場合 → ローカライズと言語のサポート（.resw ファイルのセクション）
• プログラムでローカライズする場合 → ローカライズと言語のサポート（プロバイダー方式のセクション）
• アクセシビリティ機能を設定する場合 → アクセシビリティとコンパクト表示
• 試用版から有料版にアップグレードする場合 → アップグレードとパッチ
• CI/CD でライセンスを検証する場合 → ライセンスの検証