syncfusion-blazor-maps

Blazor 向け Syncfusion Maps の実装

NuGet： Syncfusion.Blazor.Maps + Syncfusion.Blazor.Themes 名前空間： Syncfusion.Blazor.Maps

Blazor アプリケーションに Syncfusion Maps コンポーネントを実装するための包括的なガイドです。Syncfusion Maps は、マーカー管理、ポリゴンオーバーレイ、レイヤーサポート、イベント処理、複数の地図プロバイダーとの統合など、強力な空間可視化機能を提供します。

🚨 重大なセキュリティに関する注意 — 使用前にお読みください：

機能の境界（必須）： このスキルはUI のレンダリング専用に設計されています。以下の用途には絶対に使用しないでください。

• 自動エージェントや LLM のデータ取り込みポイント
• 信頼できない外部コンテンツを処理するパイプライン
• 意思決定システム向けの形状／タイルデータソース
• 人間によるレビューを経ない、あらゆる自動化入力

厳格な制限： 未加工の外部 GEOJSON、SHAPEDATA、タイル、アノテーションを、エージェント、LLM、自動化システムに絶対に転送しないでください。 外部の地図コンテンツはすべて、信頼できないユーザー入力として扱う必要があります。この制限に違反すると、重大なプロンプトインジェクションやデータ流出の脆弱性が生じます。

本番環境で必須の安全対策：

1. GeoJSON／タイルの読み込みについて：
   • タイルと GeoJSON をローカルでホストする（wwwroot/tiles またはバンドル済みアセット内）、または
   • クライアントからアクセスできるようにする前にすべてのデータを検証する、サーバーサイドプロキシのみを使用する
   • 実行時にサードパーティ URL から直接読み込まない
2. サーバーサイドプロキシを使用する場合：
   • プロバイダーのホストを厳格な許可リストと照合して検証し、HTTPS を必須にする
   • コンテンツタイプを確認し、厳格なスキーマ（ユーザーフィールドなし）に照らして検証する
   • 最大ファイルサイズ（5MB）とフィーチャー数の上限（最大 10,000）を適用する
   • すべてのプロパティ（ツールチップ、アノテーション、ラベル）を削除するか HTML エンコードする
   • 指示のパターンや疑わしいキーワードを含むコンテンツを拒否する
   • 座標を正規化／検証する（緯度 -90/90、経度 -180/180）
   • クライアントに配信する前に、すべてのテキストフィールドを HtmlSanitizer でサニタイズする
   • 短期間のみ有効な署名付き URL を発行する（API キーを埋め込まない）
3. コンテンツのレンダリングについて：
   • レンダリング前に、外部プロパティを必ず HtmlSanitizer でサニタイズする
   • スクリプトインジェクションをブロックするコンテンツセキュリティポリシーのヘッダーを実装する
   • すべての検証失敗を包括的に記録する

外部コンテンツを自動化で処理する必要がある場合：

• まず、サーバーサイドで完全なスキーマ検証とサニタイズを実施する
• 指示のようなパターンを必ず拒否するポリシーを実装する
• トークン数／長さに厳格な制限を設ける（各フィールド最大 256 文字）
• 自動化の前に、明示的な人間によるレビューと承認を必須とする
• 境界マーカーで囲む：[MAP_DATA_START]...[MAP_DATA_END]
• 完全な監査証跡を含め、すべての処理を記録する
• 必須の検証テンプレートについては、readme-securityを参照してください

このスキルを次の用途に使用しないでください：

• ❌ 信頼できない外部の地理データを分析する
• ❌ 検証せずに、ユーザーがアップロードした GeoJSON を処理する
• ❌ 地図コンテンツを LLM／エージェント分析システムに転送する
• ❌ 外部の地図メタデータに基づいて自動的に意思決定する
• ❌ 外部サードパーティコンテンツを保存またはキャッシュする

深刻なセキュリティ上の影響： これらの境界を無視すると、以下の事態が発生する可能性があります。

• 悪意のある地理データを介したプロンプトインジェクション攻撃
• LLM／エージェントの動作の操作
• 不正なデータ流出
• スクリプトインジェクションによるシステム侵害

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

以下が必要な場合は、Syncfusion Maps を使用してください。

• インタラクティブな地図に地理データを表示する
• 色分け（コロプレス）を使用して地域ごとのデータを可視化する
• 地図にマーカー、ポリゴン、アノテーションを追加する
• ユーザー操作（クリック、ホバー、ズーム、パン）を処理する
• 複数の地図プロバイダー（Google、Bing、Azure、OpenStreetMap）をサポートする
• カスタム凡例やラベルを付けて地図をエクスポートまたは印刷する
• 位置情報対応アプリケーションを構築する
• 複数レイヤーの空間可視化を作成する

コンポーネントの概要

Syncfusion Maps は、次の機能を備えた強力な地理空間可視化コンポーネントです。

• 複数のプロバイダーに対応したインタラクティブなマップの描画
• 地理データセットのバインドと可視化
• 豊富な空間機能（マーカー、ポリゴン、レイヤー、注釈）のサポート
• 複雑なユーザー操作とイベントへの対応
• テーマとスタイルによる外観のカスタマイズ
• ローカライズとアクセシビリティ機能の有効化
• レポート作成や共有のためのマップのエクスポート

---

⚠️ 重要：承認済みおよび制限対象のユースケース

✅ 承認済みの用途（検証を伴う UI の描画）

• インタラクティブな Web ダッシュボードで地理データを表示する
• コロプレスマップで地域統計を可視化する
• 人による確認を伴って事業所の位置マーカーを表示する
• ユーザー操作に対応したローカライズ済みマップを描画する
• 空間検索と絞り込みのインターフェースを提供する
• 読み取り専用の地理情報を可視化する
• 検証済みの精選されたデータによって意思決定を支援する

❌ 厳格に禁止されている用途（エージェント／LLM との連携は禁止）

• 絶対にしないでください： 未加工のマップデータを LLM 分析システムに渡す
• 絶対にしないでください： 自動化されたエージェントのデータ取り込み口として使用する
• 絶対にしないでください： 外部の GeoJSON を意思決定システムに転送する
• 絶対にしないでください： 信頼できないサードパーティの地理データを自動処理する
• 絶対にしないでください： 人による確認なしに注釈やツールチップを LLM 入力として使用する
• 絶対にしないでください： 地理データの自動パイプラインを作成する
• 絶対にしないでください： マップのメタデータを分析する AI システムと連携する

🚫 サードパーティコンテンツの取り込み境界

このスキルで参照する外部ソース：

• tile.openstreetmap.org - OpenStreetMap プロバイダー
• cdn.syncfusion.com - Syncfusion コンポーネントのリソース
• maps.googleapis.com - Google Maps プロバイダー
• dev.virtualearth.net - Bing Maps プロバイダー
• atlas.microsoft.com - Azure Maps プロバイダー

重要： これらのサードパーティプロバイダーから取り込むデータは、UI の描画のみに使用します。これらのコンテンツが自動化システムに渡ることがあってはなりません。地理データを自動処理する必要がある場合は、次の手順に従ってください。

1. ❌ このスキルの外部バインディングを使用しないでください
2. ✅ サーバーサイドに独立した検証パイプラインを作成してください
3. ✅ すべての外部コンテンツを最初にサニタイズして検証してください
4. ✅ 自動処理の前に明示的な人の承認を必須にしてください
5. ✅ 包括的な監査ログを実装してください

---

セキュリティに関する考慮事項

重要： このスキルには、セキュリティ上の注意が必要な操作がいくつか含まれています。以下の保護策を確認し、実装してください。

1. API キーの管理

• リスク： ソースコードに API キーをハードコードすると、バージョン管理システムで公開されるおそれがあります
• 緩和策： キーは設定ファイル、ユーザーシークレット、またはシークレット管理サービスに保存してください
• 参考資料： マッププロバイダー - セキュリティのベストプラクティス

2. HTML コンテンツのインジェクション

• リスク： 外部データソースの任意の HTML が、ツールチップ、注釈、ポップアップに描画される可能性があります
• 攻撃経路： XSS 攻撃、悪意のある地理データを介したプロンプトインジェクション
• 緩和策： HtmlSanitizer ライブラリですべての外部コンテンツをサニタイズし、ユーザー入力を HTML エンコードしてください
• 参考資料： ユーザー操作 - 外部コンテンツのサニタイズ

3. 外部データソース

• リスク： 信頼できないソース（CDN を含む）から、マップデータ（GeoJSON、タイル、マーカー）が取得される可能性があります
• 攻撃経路： 中間者攻撃、CDN の侵害、不正なデータのインジェクション、プロパティインジェクション
• 緩和策： 許可リストに照らしてソース URL を検証し、HTTPS を強制し、GeoJSON の構造を検証し、CSP を実装し、本番環境ではローカルにキャッシュしてください
• 参考資料： データの可視化 - 外部 GeoJSON の検証 | マッププロバイダー - データ流出の防止

4. データのエクスポート操作

• リスク： マップを PNG／SVG／PDF にエクスポートすると、機密性の高い地理データが含まれる可能性があります
• 緩和策： アクセス制御を実装し、エクスポート操作を監査し、エクスポートするコンテンツをサニタイズしてください
• 参考資料： 印刷とエクスポート

5. プロンプトインジェクションの防止とエージェント／LLM の境界

• 重大なリスク： 図形データ、注釈、ツールチップ、その他の外部マップメタデータには、指示のように見えるテキストが含まれている可能性があります。このスキルはサードパーティのコンテンツ（タイルプロバイダー、GeoJSON ソース）を取り込みます。明示的な人間によるレビューなしに自動エージェントや LLM に転送すると、プロンプトインジェクションに悪用される可能性があります。

• 攻撃対象領域： 外部コンテンツは以下を介して取り込まれます。

  • MapsLayer の UrlTemplate（タイルプロバイダー）
  • ShapeData および DataSource プロパティ（GeoJSON）
  • ツールチップおよび注釈のプロパティ
  • 外部ソースからのあらゆるデータバインディング

• 必須の境界： このスキルを、以下のデータソースとして使用してはなりません。

  • LLM による分析または要約
  • 自動エージェントによる意思決定
  • AI を活用した地理分析
  • 機械学習のトレーニングパイプライン
  • 人間の介入なしに AI／ML を介してマップデータを処理するあらゆるシステム

• 外部コンテンツを自動化に渡す必要がある場合：

  • クライアントでレンダリングする前に、サーバー側で検証を適用します：スキーマチェック（厳格な GeoJSON 検証）、ドメインの許可リスト検証
  • HtmlSanitizer ですべてのプロパティをサニタイズし、HTML／スクリプトタグを削除します
  • 指示のようなキーワード（"system:", "ignore", "bypass", "execute", "[SYSTEM]" など）を必ず拒否するポリシーを実装します
  • 厳格な長さ制限を適用します（プロパティごとに最大 256 文字、合計最大 5000 文字）
  • データを境界マーカーで囲みます：[MAP_DATA_START]...[MAP_DATA_END]
  • AI システムに転送する前に、明示的な人間によるレビューと承認を必須にします
  • すべての AI システムへのアクセスについて、包括的な監査ログを保持します

• 緩和策のアーキテクチャ：

  • レイヤー 1： UI レンダリング専用として指定（エージェント／LLM では使用しない）
  • レイヤー 2： パターン検出（不審なキーワードの検出）
  • レイヤー 3： 即時拒否（代替解析なし）
  • レイヤー 4： HTML サニタイズ（許可リスト方式）
  • レイヤー 5： 厳格な検証パイプライン（スキーマ、サイズ、座標）
  • レイヤー 6： 境界マーカーと監査ログ（自動化が避けられない場合）

• 参照： ユーザー操作 - プロンプトインジェクションの防止 | readme-security.md

---

セキュリティ問題への対応

このスキルは、以下の特定済みのセキュリティ警告に対処するため強化されています。

[CREDENTIALS_UNSAFE] ハードコードされた API キー

ステータス： ✅ 解決済み

指摘事項： Google Maps API キーがサンプルコードにハードコードされていました。

実施した修正：

• サンプルからハードコードされた API キーをすべて削除
• すべてのプロバイダー設定サンプルを更新し、IConfiguration からキーを読み込むように変更
• 環境変数、ユーザーシークレット、Azure Key Vault との統合を示す、包括的な API キー管理ガイドを追加
• すべてのサンプルで Configuration["MapProviders:GoogleKey"] パターンを使用

必要な対応： API キーをハードコードしないでください。構成、環境変数、またはシークレットマネージャーから読み込んでください。

参照： map-providers.md#managing-api-keys-securely

[EXTERNAL_DOWNLOADS] 外部タイルおよびデータのダウンロード

ステータス： ✅ 想定される動作として文書化済み

指摘事項： スキルが tile.openstreetmap.org、cdn.syncfusion.com、maps.googleapis.com からマップタイルをダウンロードします。

説明： これらのダウンロードは、マップの視覚化に必要な想定内の動作です。マップタイルはタイルプロバイダーから取得する必要があります。これは通常の動作であり、脆弱性ではありません。

ベストプラクティス：

• 本番環境ではローカルのタイルキャッシュを使用します
• タイル URL を検証するサーバー側プロキシを実装します
• すべてのタイルリクエストで HTTPS を強制します
• ドメインの許可リストを設定します

参照： map-providers.md#external-asset-downloads-expected-behavior

[COMMAND_EXECUTION] IJSRuntime ブラウザー API の使用

ステータス： ✅ セーフガードを導入して解決済み

参照： state-persistence.md | customization-and-styling.md

[PROMPT_INJECTION] 自動化エージェントに渡される信頼できないデータ

ステータス： ✅ 包括的な対策により解決済み

検出事項： GeoJSONや地図のメタデータに指示のようなテキストが含まれる場合があり、サニタイズせずにLLMやエージェントに渡すと、プロンプトインジェクションのリスクがあります。

多層的な緩和策を実装済み：

1. 機能の境界： このスキルの用途をUIのレンダリングのみに限定

   • 生データをLLMやエージェントに渡すことを明示的に禁止
   • すべての外部コンテンツを信頼できないものとして扱う

2. パターン検出： 指示パターンの検出を実装

   • 検出対象：「system:」、「ignore」、「bypass」、「execute」、「[SYSTEM]」など
   • 疑わしいコンテンツを検出した場合は直ちに拒否

3. サニタイズ： レンダリング前にすべてのHTMLコンテンツをサニタイズ

   • HtmlSanitizerライブラリでスクリプトや安全でないタグを削除
   • 外部プロパティにHTMLエンコードを適用
   • 外部ソースからの生HTMLは使用しない

4. 検証パイプライン： 包括的なGeoJSON検証

   • スキーマ検証（FeatureCollection構造）
   • サイズ制限（最大5MB、最大10,000フィーチャー）
   • プロパティ検証（最大50個、各最大1,000文字）
   • 座標範囲の検証（緯度：-90～90、経度：-180～180）

5. 境界マーカー： 自動化が必要な場合

   • [MAP_DATA_START] ... [MAP_DATA_END]の区切り文字を使用
   • 厳格な長さ制限（プロパティごとに256文字、合計5,000文字）
   • 検証に失敗した場合は拒否

6. ログ記録と監査： 包括的なセキュリティログ

   • すべての検証失敗を記録
   • 疑わしいパターンをコンテキストとともに記録
   • 自動化の前に必ず人間が確認

本番環境チェックリスト：

• APIキーをハードコードしていない
• GeoJSONはローカルファイルまたは検証済みのプロバイダーから取得する
• 外部リクエストにHTTPSを強制する
• HtmlSanitizerをインストールして設定する
• Content Security Policyヘッダーを設定する
• パターン検出時の拒否ポリシーを実装する
• 包括的なログ記録を有効にする
• APIキーをシークレットマネージャーに保存する
• セキュリティレビューを完了する

参考資料： readme-security.md | user-interactions.md#preventing-prompt-injection | data-visualization.md#validating-external-geojson-data

---

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

現在の作業に合ったリファレンスガイドを選択してください。

はじめに

📄 読む： references/getting-started.md

• インストールとNuGetパッケージのセットアップ
• 基本的な地図の初期化とレンダリング
• CSSのインポートとテーマの設定
• 初めてのインタラクティブな地図の作成
• セットアップ手順の解説

地図プロバイダーと設定

📄 読む： references/map-providers.md

• Google MapsのセットアップとAPIキーの設定
• Bing Mapsのセットアップと認証
• Azure Mapsプロバイダーの設定
• OpenStreetMapのセットアップ
• プロバイダーの比較と選択ガイド

マーカーとレイヤー

📄 読む： references/markers-and-layers.md

• マーカーの追加と管理
• マーカーのクラスタリングとグループ化
• レイヤーとレイヤーコレクションの操作
• レイヤーの表示と非表示の切り替え
• マーカーの動的な更新とデータバインディング

空間機能とオーバーレイ

📄 読む： references/spatial-features.md

• ポリゴンと地理的図形の描画
• ナビゲーションラインとポリラインの作成
• テキスト、アイコン、円を使った注釈の追加
• データバブルとインタラクティブなオーバーレイの作成
• 高度な空間ジオメトリ機能

データの可視化とマッピング

📄 読む： references/data-visualization.md

• 色のマッピングとコロプレスマップによる可視化
• 凡例と配置の設定
• 地図要素へのデータラベルの表示
• 地理データセットを使った地図のデータ設定
• 高度なデータバインディングと可視化のパターン

ユーザー操作

📄 読む： references/user-interactions.md

• マウスクリックとダブルクリックの処理
• ズームとパンの制御設定
• ツールチップとポップアップの動作
• キーボードナビゲーションのサポート
• カスタム操作パターン

イベントとメソッド

📄 読む： references/events-and-methods.md

• マウスイベント処理（クリック、ホバー、移動）
• パンとズームのイベント取得
• プログラムによるマップ操作メソッド（パン、ズーム、リセット、更新）
• イベントデータとコールバックのパターン
• ユーザー操作からアクションを実行する方法

カスタマイズとスタイル設定

📄 読む： references/customization-and-styling.md

• CSS クラスのカスタマイズ
• Theme Studio との統合
• マーカーとポップアップのスタイル設定
• マップコントロールとナビゲーションのスタイル設定
• ダークモードとレスポンシブデザイン

印刷とエクスポート

📄 読む： references/print-and-export.md

• マップを PNG、SVG、PDF としてエクスポート
• 印刷機能とページ設定
• 凡例とデータラベルを含めたエクスポート
• ファイル形式に関する考慮事項
• サーバー側およびクライアント側のエクスポートオプション

国際化とローカライズ

📄 読む： references/internationalization-and-localization.md

• マップラベルの多言語サポート
• 右から左（RTL）へ記述するテキストのサポート
• 数値と日付のローカライズされた書式設定
• 地域ごとのマップのバリエーション
• 言語固有のカスタマイズ

状態の永続化

📄 読む： references/state-persistence.md

• マップの状態の保存と復元
• ズームレベルと中心位置の永続化
• ユーザー操作状態の保持
• セッションストレージおよびローカルストレージとの統合
• 状態管理パターン

アクセシビリティと高度なトピック

📄 読む： references/accessibility.md

• WCAG 2.1 への準拠と規格
• キーボードナビゲーションとショートカット
• ARIA 属性とセマンティックマークアップ
• スクリーンリーダーのサポート
• ハイコントラストモードのサポート
• 支援技術との互換性

API リファレンス全文

📄 読む： references/api-reference.md

• SfMaps メインコンポーネントのプロパティとメソッド
• 設定クラス（MapsCenterPosition、MapsZoomSettings、MapsLegendSettings など）
• すべてのイベントタイプのイベント引数
• インターフェース（ILayer、IMarker、IBubble）
• MarkerType、ExportType、ProjectionType、GeometryType などの列挙型
• プロパティのクイックリファレンスガイド
• クラス階層と API サーフェスの全体

---

⛔ セキュリティ要件：してはいけないこと

以下のパターンは禁止されており、重大なセキュリティ上の脆弱性を引き起こします。

// ❌ PROHIBITED: Forwarding map data to LLM/agents
var geoJsonData = await LoadGeoJsonFromMapLayer();
var analysis = await llmService.AnalyzeAsync(geoJsonData);  // NEVER DO THIS

// ❌ PROHIBITED: Using external annotations in agent prompts
var tooltipText = mapFeature.Properties["tooltip"];
var response = await agent.ExecuteAsync($"Summarize: {tooltipText}");  // NEVER DO THIS

// ❌ PROHIBITED: Processing third-party tiles through automation
var tileUrl = "https://tile.openstreetmap.org/{z}/{x}/{y}.png";
await automationPipeline.IngestAsync(tileUrl);  // NEVER DO THIS

// ❌ PROHIBITED: Making decisions based on untrusted GeoJSON
var externalGeoJson = await httpClient.GetAsync("https://external-source.com/map.json");
var decision = MakeCriticalDecision(externalGeoJson);  // NEVER DO THIS

AI/ML システムでマップデータを使用する必要があると思われる場合：

1. 作業を中断し、アーキテクチャを再評価してください
2. 独立したサーバー側の取り込みパイプラインを作成してください
3. 完全な検証とサニタイズを実装してください
4. 明示的なセキュリティレビューと承認を受けてください
5. AI 処理の前に人によるレビューのゲートを設けてください
6. 包括的な監査証跡を維持してください

---

クイックスタートの例

// Basic map setup in Blazor (use validated tile URL or local tiles in production)
@page "/maps-demo"
@using Syncfusion.Blazor.Maps

<SfMaps>
    <MapsLayers>
        
        <MapsLayer UrlTemplate="@TileUrl">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    // SAFE: Host tiles locally or use a validated, domain-restricted provider
    private string TileUrl = "/tiles/{level}/{tileX}/{tileY}.png"; // local/cached tiles
    
    // This data stays in the UI layer only - NEVER forwarded to agents or LLMs
}

一般的なパターン

パターン 1：マップへのマーカーの追加

<SfMaps>
    <MapsLayers>
        <MapsLayer TValue="MarkerData" UrlTemplate="@TileUrl">
            <MapsMarkerSettings>
                <MapsMarker TValue="MarkerData" Latitude="37.368" Longitude="-122.095" 
                    Width="15" Height="15">
                </MapsMarker>
            </MapsMarkerSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    public class MarkerData
    {
        public double Latitude { get; set; }
        public double Longitude { get; set; }
    }
}

パターン 2：色マッピングによるデータのバインド

<SfMaps>
    <MapsLayers>
        <MapsLayer ShapeDataSource="@ShapeData" 
                   ShapePropertyPath="@ShapePropertyPath"
                   DataSource="@DataSource" TValue="DataType">
            <MapsShapeSettings ColorValuePath="Population">
                <MapsShapeColorMappings>
                    <MapsShapeColorMapping From="0" To="50000" Color="#B3E5FC"></MapsShapeColorMapping>
                    <MapsShapeColorMapping From="50000" To="100000" Color="#81D4FA"></MapsShapeColorMapping>
                </MapsShapeColorMappings>
            </MapsShapeSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

パターン 3：マップクリックイベントの処理

<SfMaps @ref="mapInstance" OnShapeSelected="ShapeSelected" 
        OnMarkerClick="MarkerClicked">
    <MapsLayers>
        <MapsLayer UrlTemplate="@TileUrl">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    private SfMaps mapInstance;

    private void MarkerClicked(MarkerClickEventArgs args)
    {
        Console.WriteLine($"Marker clicked at: {args.Latitude}, {args.Longitude}");
    }

    private void ShapeSelected(ShapeSelectedEventArgs args)
    {
        Console.WriteLine($"Shape selected: {args.Data}");
    }
}

主な機能の概要

• 複数の地図プロバイダー： Google Maps、Bing Maps、Azure Maps、OpenStreetMap に対応
• 豊富な地理空間機能： マーカー、ポリゴン、ポリライン、注釈、バブル
• データの可視化： カラーマッピング、コロプレスマップへの対応、凡例、データラベル
• インタラクティブ機能： クリック処理、ホバーツールチップ、ズーム／パン操作、キーボード操作
• レイヤー管理： 複数レイヤーへの対応、表示の切り替え、動的な更新
• エクスポート機能： 凡例とラベルを含む PNG、SVG、PDF へのエクスポート
• 国際化： 多言語対応と RTL テキストのレンダリング
• アクセシビリティ： キーボード操作とスクリーンリーダーに対応した WCAG 準拠
• カスタマイズ： Theme Studio との統合、CSS によるカスタマイズ、マーカーのスタイル設定
• パフォーマンス： 大規模なデータセットやマーカーのクラスタリングに最適化されたレンダリング