syncfusion-aspnetcore-uploader

ASP.NET Core での Uploader の実装

Uploader は、ファイルの選択、検証、非同期アップロード、ドラッグ＆ドロップのサポート、進行状況の追跡に対応した、ASP.NET Core 用の強力なファイルアップロードコンポーネントです。このスキルでは、Syncfusion の TagHelper 構文を使用して、ASP.NET Core アプリケーションに Uploader を実装する方法を説明します。

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

次のような場合に、このスキルを使用してください。

• 画像、ドキュメント、メディア用のファイルアップロードフォームを作成する
• 進行状況を表示しながら非同期でファイルをアップロードする
• アップロード前にファイルの種類とサイズを検証する
• ファイル選択時のドラッグ＆ドロップをサポートする
• 複数のファイルを同時にアップロードする
• ファイルの削除とクリーンアップを処理する
• エンタープライズ向けのファイル管理インターフェースを構築する
• 大容量ファイルのチャンクアップロードを実装する
• ファイルアップロードを HTML フォームに統合する
• クリップボードからの貼り付けによるアップロードとディレクトリのアップロードをサポートする
• 適切なファイル処理とセキュリティを確保する

主な機能

機能	使用例
非同期アップロード	SaveUrl/RemoveUrl のハンドラーを使用したノンブロッキングアップロード
複数ファイルのアップロード	一度に複数のファイルを選択してアップロード
単一ファイルのアップロード	1 回の選択につき 1 ファイルに制限
ファイル検証	拡張子、サイズ、数、重複を検証
ドラッグ＆ドロップ	Uploader 領域にファイルを直接ドロップ
カスタムドロップ領域	外部要素をドロップゾーンとして指定
自動アップロード	ファイルを自動または手動でアップロード
進行状況の追跡	プログレスバーでアップロードの進行状況を表示
ファイルの削除	RemoveUrl ハンドラーでアップロード済みファイルを削除
チャンクアップロード	大容量ファイルをチャンクに分割して確実にアップロード
貼り付けによるアップロード	クリップボードから画像をアップロード
ディレクトリのアップロード	フォルダー全体とディレクトリ構造をアップロード
フォームへの統合	フォーム送信の一部としてファイルを送信
テンプレート	ファイルリストとボタンの外観をカスタマイズ
ローカライズ	複数の言語と地域設定をサポート
エラー処理	カスタムメッセージでアップロードの失敗を表示

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

はじめに

📄 参照: references/getting-started.md

• 前提条件とシステム要件
• Syncfusion.EJ2.AspNetCore NuGet パッケージのインストール
• _ViewImports.cshtml での TagHelpers の設定
• CDN によるスタイルシートとスクリプトリソースの追加
• スクリプトマネージャーの登録
• 最初の Uploader の作成
• 基本的な設定とプロパティ

非同期アップロード

📄 参照: references/async-upload.md

• SaveUrl エンドポイントと RemoveUrl エンドポイントの設定
• 単一ファイルと複数ファイルのアップロードモード
• 自動アップロードの設定と手動アップロードの開始
• 成功時と失敗時のイベントハンドラー
• 進行状況の追跡とアップロードのライフサイクル
• アップロードのキャンセル処理

ファイル検証

📄 参照: references/file-validation.md

• allowed-extensions によるファイルの種類の検証
• ファイルサイズの制限（min-file-size、max-file-size）
• ファイル数の上限
• 重複ファイルの検出と防止
• カスタム検証パターンとエラーメッセージ
• アップロード前後の検証

ドラッグ＆ドロップのサポート

📄 参照: references/drag-drop-support.md

• デフォルトのドラッグ＆ドロップ動作
• カスタムドロップ領域の設定
• 1 ページ上での複数のドロップゾーン
• ドラッグ＆ドロップイベントとイベント処理
• クリップボードからの貼り付けによるアップロード
• ディレクトリのドラッグ＆ドロップのサポート

テンプレートとスタイル設定

📄 参照: references/templates-and-styling.md

• UI をカスタマイズするための Template プロパティ
• ボタンのカスタマイズと配置
• ファイルリスト項目のレンダリング
• CSS クラスのカスタマイズ
• テーマの統合（Fluent、Material、Bootstrap）
• レスポンシブデザインのパターン

高度なパターン

📄 参照： references/advanced-patterns.md

• 大容量ファイル向けのチャンクアップロード
• ファイルアップロードを含むフォーム送信
• ディレクトリのアップロード処理
• ファイルの削除とクリーンアップ戦略
• 高度なエラー処理
• セキュリティに関する考慮事項と CORS

クイックスタートの例

非同期アップロードを使用する基本的なアップローダー（TagHelper）

<div class="form-group">
    <ejs-uploader id="uploader">
        <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
        <e-upload-files></e-upload-files>
    </ejs-uploader>
</div>

<div id="uploadedFiles"></div>

HomeController.cs での設定

using Microsoft.AspNetCore.Mvc;
using System.IO;

public class HomeController : Controller
{
    private readonly IWebHostEnvironment _webHostEnvironment;

    public HomeController(IWebHostEnvironment webHostEnvironment)
    {
        _webHostEnvironment = webHostEnvironment;
    }

    [HttpPost]
    public IActionResult Save(IFormFile[] uploader)
    {
        if (uploader != null && uploader.Length > 0)
        {
            string uploadPath = Path.Combine(_webHostEnvironment.WebRootPath, "Uploads");
            if (!Directory.Exists(uploadPath))
                Directory.CreateDirectory(uploadPath);

            foreach (IFormFile file in uploader)
            {
                string filePath = Path.Combine(uploadPath, file.FileName);
                using (FileStream fs = System.IO.File.Create(filePath))
                {
                    file.CopyTo(fs);
                    fs.Flush();
                }
            }
        }
        return Ok();
    }

    [HttpPost]
    public IActionResult Remove(string[] files)
    {
        string uploadPath = Path.Combine(_webHostEnvironment.WebRootPath, "Uploads");
        
        foreach (string file in files)
        {
            string filePath = Path.Combine(uploadPath, file);
            if (System.IO.File.Exists(filePath))
                System.IO.File.Delete(filePath);
        }
        return Ok();
    }
}

_ViewImports.cshtml での設定（初回のみ）

@addTagHelper *, Syncfusion.EJ2

_Layout.cshtml 内（初回のみ）

W012 – 実行時のリモートコード依存リスク： 外部 CDN からスクリプトやスタイルを読み込むと、CDN のファイルが侵害または改ざんされた場合、ユーザーのブラウザーで実行されます。以下の 2 つの方法のいずれかでリスクを軽減してください。

推奨 – アセットをセルフホストする（実行時のリモート依存を完全に排除します）：

1. NuGet パッケージ、または一度だけダウンロードした CDN から ej2.min.js とテーマ CSS を wwwroot/lib/syncfusion/ にコピーします。
2. 相対パスで参照します。ファイルは独自のオリジンから配信されるため、integrity 属性は不要です。

代替案 – Subresource Integrity（SRI）を使用した CDN： CDN を使用する必要がある場合は、integrity ハッシュを設定してファイルを固定し、改ざんされたバージョンをブラウザーが拒否するようにします。openssl dgst -sha384 -binary <file> | openssl base64 -A でハッシュを計算し、バージョンをアップグレードするたびに更新してください。

オプション A — セルフホスト（推奨）

<head>
    
    <link rel="stylesheet" href="~/lib/syncfusion/fluent.css" />
</head>
<body>
    @RenderBody()

    <script src="~/lib/syncfusion/ej2.min.js"></script>
    <ejs-scripts></ejs-scripts>
</body>

オプション B — SRI による固定を使用した CDN

<head>
    
    <link rel="stylesheet"
          href="https://cdn.syncfusion.com/ej2/24.1.48/fluent.css"
          integrity="sha384-REPLACE_WITH_ACTUAL_HASH_FOR_fluent.css"
          crossorigin="anonymous" />
</head>
<body>
    @RenderBody()

    <script src="https://cdn.syncfusion.com/ej2/24.1.48/dist/ej2.min.js"
            integrity="sha384-REPLACE_WITH_ACTUAL_HASH_FOR_ej2.min.js"
            crossorigin="anonymous"></script>
    <ejs-scripts></ejs-scripts>
</body>

よく使われるパターン

パターン 1：進行状況を表示する複数ファイルのアップロード

<ejs-uploader id="multiUploader"
    allowed-extensions=".jpg,.png,.pdf,.doc,.docx"
    max-file-size="5242880"
    auto-upload="false"
    multiple="true"
    uploading="onUploading"
    success="onSuccess"
    failure="onFailure">
    <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
</ejs-uploader>

<script>
function onUploading(args) {
    console.log('Uploading: ' + args.file.name);
    console.log('Progress: ' + (args.percentComplete * 100) + '%');
}

function onSuccess(args) {
    if (args.operation === 'upload') {
        console.log(args.file.name + ' uploaded successfully');
    }
}

function onFailure(args) {
    console.log('Upload failed: ' + args.response);
}
</script>

パターン 2：検証付きの単一ファイルアップロード

<ejs-uploader id="singleUploader"
    allowed-extensions=".jpg,.png,.jpeg"
    max-file-size="2097152"
    multiple="false"
    selected="onFileSelected"
    auto-upload="true">
    <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
</ejs-uploader>

<script>
function onFileSelected(args) {
    if (args.filesData.length > 1) {
        args.filesData.splice(1);
        alert('Only one file can be selected');
    }
}
</script>

パターン 3：カスタム領域へのドラッグ＆ドロップ

<div id="dropArea" style="border: 2px dashed #ccc; padding: 20px; min-height: 200px;">
    Drop files here
</div>

<ejs-uploader id="uploader"
    drop-area="#dropArea"
    auto-upload="true">
    <e-async-settings save-url="Home/Save" remove-url="Home/Remove"></e-async-settings>
</ejs-uploader>

主なプロパティ

プロパティ	型	デフォルト	目的
allowed-extensions	string	""	許可するファイル形式（例：".jpg,.png"）
max-file-size	long	28.4MB	ファイルサイズの最大値（バイト単位）
min-file-size	long	0	ファイルサイズの最小値（バイト単位）
multiple	bool	true	複数ファイルの選択を許可します
auto-upload	bool	true	選択後にファイルを自動でアップロードします
save-url	string	""	ファイル保存用の URL ハンドラー
remove-url	string	""	ファイル削除用の URL ハンドラー
drop-area	string	""	カスタムドロップ領域の CSS セレクター

よくあるユースケース

ユースケース 1：プロフィール写真のアップロード

• 単一ファイル、画像のみ、自動アップロード
• 参照先：references/advanced-patterns.md

ユースケース 2：ドキュメント管理

• 複数ファイル、検証、大容量ファイル向けのチャンクアップロード
• 参照先：references/async-upload.md

ユースケース 3：一括インポート

• ディレクトリのアップロード、フォーム送信、エラー処理
• 参照先：references/advanced-patterns.md

ユースケース 4：メディアギャラリー

• 複数ファイルのアップロード、カスタムテンプレート、ドラッグ＆ドロップ
• 参照先：references/templates-and-styling.md

---

次のステップ： references/getting-started.md を読んで、ASP.NET Core アプリケーションで Uploader の実装を始めましょう。