Reports.web C#／.NET WASM言語ラッパー プログラマーズガイド／APIリファレンス

1. 最初に知っておくことRM001

1.1 「WASM言語ラッパー」とはRM002

本書では、各言語でPREPEJを組み立てる補助ライブラリをWASM言語ラッパーと呼びます。実装の中心はPrintDataです。ラッパー自身はWASMを直接ロードせず、SVGやPDFも描きません。出力形式を共通JSONに揃えることで、業務処理と描画エンジンを疎結合にします。

これはPure Java／Pure Python／WPF・.NETの言語別エンジンとは異なる方式です。Pure系は各言語の帳票エンジンを直接呼びます。WASM方式は7言語が同じWASMエンジンとブラウザUIを共有します。

1.2 帳票ができるまでRM003

1. デザイナーで帳票定義 .prepdj を作ります。
2. C#／.NETのPrintDataへPREPDJを設定します。
3. DBやAPIから取得した値を、デザイン上のオブジェクト名へ設定します。
4. 1ページずつ確定し、.prepejを作ります。
5. PREPEJをブラウザのプレビュアー、またはサーバーWASMへ渡します。
6. 共通エンジンがSVGプレビュー、PDF、印刷を担当します。

1.3 二つのファイルRM004

PREPEJは単なる一時レスポンスではありません。ファイル保存、再読込、メール添付、REST API、サーバー間転送、後日の再印刷に同じ文書を使えます。

2. サンプルを動かすRM005

サンプルは .NET 8を対象としたASP.NET Coreアプリ です。WPFのネイティブエンジンではなく、共通WASMへ渡す印刷データをC#で作ります。同梱のDocker構成では必要な言語環境とDBをコンテナ内に用意するため、まずPC側で準備するのはDockerです。Windows／MacではDocker Desktopを起動し、LinuxではDocker EngineとComposeプラグインが使える状態にしてください。

ZIPを全体ごと展開してください。共通RuntimeとDB初期化データも使うため、番号フォルダーだけを取り出さないでください。初回のイメージ取得とビルドにはインターネット接続が必要です。

短いコードから学ぶ場合は WebAssembly/Samples/dotnet/01.あっという間に帳票出力/README.html から始めます。ここでは全帳票を確認できる02の起動を説明します。

1. VS CodeやCursor、または使い慣れたエディターで WebAssembly/Samples/dotnet/02.全帳票をWebでプレビュー を開きます。
2. そのフォルダーでターミナルを開き、次を実行します。開発用のReports Webリポジトリをビルドする必要はありません。

docker compose up -d --build --wait
docker compose ps

3. 起動が成功してから、ブラウザで http://127.0.0.1:19231/ を開きます。URLを開くだけではアプリは起動しません。
4. 終了するときは、同じフォルダーで docker compose down を実行します。このサンプルのコンテナとネットワークが削除されます。DBデータの初期化やイメージの片付けは、そのフォルダーのREADMEに手順があります。

02では、単純帳票、10の倍数、郵便番号一覧、見積書、請求書、商品一覧、名刺、デザイン機能見本を確認できます。請求書などを選び、ソースと出力結果を見比べてください。別のアプリから帳票APIを呼ぶ使い方は、続く03のREADMEに説明しています。

3. 最初の一枚を作るRM006

01に戻り、Program.csのCreatePrintData()だけを次の関数へ置き換えてください。先頭のusingと、下のWebサーバー処理は残します。PrintDataは同梱のReportData/PrintData.csにあり、プロジェクトから参照済みです。01でも02と同じクラスを使っています。

JsonObject CreatePrintData()
{
    var definition = JsonNode.Parse(
        File.ReadAllText("definition/quick-report.prepdj"))!.AsObject();
    var print = new PrintData()
        .SetDefinition(definition)
        .PageStart()
        .SetValue("Title", "はじめての帳票")
        .SetValue("CustomerName", "パオ商事株式会社")
        .PageEnd();
    return print.ToJsonObject();
}

01のターミナルでdocker compose up -d --build --wait --wait-timeout 180を実行し、成功後にhttp://127.0.0.1:19230/を再読み込みします。見出しと会社名の変更を確かめ、PDFも保存してみてください。

TitleとCustomerNameは01のdefinition/quick-report.prepdjに付けた動的文字の名前です。C#の変数名ではありません。自分の帳票ではデザイナーで付けた名前を指定します。Results.Json(CreatePrintData())が、返したオブジェクトをJSONとして配信します。文字列を返すAPIを自作する場合はResults.Text(print.ToJson(), "application/json; charset=utf-8")とし、JSON文字列をさらにResults.Jsonで二重に変換しないでください。

呼出順は 定義を設定 → ページを開始 → 値を設定 → ページを確定 → JSONを取得 です。未完了のページがある状態ではPREPEJを取得できません。この制約により、途中までの帳票を誤って配信することを防ぎます。

4. PrintData APIリファレンスRM007

配布ZIP内の実装ファイルは WebAssembly/Samples/dotnet/02.全帳票をWebでプレビュー/ReportData/PrintData.cs です。各番号のサンプルにも必要なソースを置いています。次のAPI名は実装に合わせています。

4.1 値とインデックスRM008

引数の順序・省略値は次のとおりです。JsonObjectはSystem.Text.Json.Nodesのクラスです。

new PrintData()
SetDefinition(JsonObject value)
PageStart(JsonObject? value = null)
SetValue(string name, object? value, int index = 0, bool drawing = true)
SetRepeatedValue(string name, object? value, int x, int y, bool drawing = true)
SetTypedValue(string name, string type, object? value,
              int index = 0, bool drawing = true)
SetImage(string name, string source, int index = 0, bool drawing = true)
SetBarcode(string name, string code, int index = 0, bool drawing = true)
DrawObject(string name, int index = 0, string? type = null)
ChangeAttributes(string name, IDictionary<string, object> values, int index = 0)
ChangeRepeatedAttributes(string name, IDictionary<string, object> values,
    int index = 0, int? x = null, int? y = null, string? type = null)
PageEnd()
ToJsonObject(): JsonObject
ToJson(bool pretty = true): string
Save(string path): void

SetDefinitionからPageEndまでは同じPrintDataを返し、続けて呼び出せます。ToJsonObjectは完成データのコピー、ToJson(false)は整形用の空白を省いたJSONを返します。Saveはサーバー上のファイルを保存する同期処理で、ブラウザーへのダウンロードとは別です。

名前・インデックス・値が不正ならArgumentException、ページ開始・終了の順序が不正ならInvalidOperationExceptionになります。保存時にはファイル権限やI/Oエラーも扱います。HTTP要求ごとに新しいPrintDataを作り、作成途中のインスタンスを共有しないでください。

値には文字列、数値、真偽値、nullの単純値を渡します。配列や任意オブジェクトを値として渡さず、帳票オブジェクトごとに明示的に対応付けてください。繰返しのindex、indexX、indexYは0から始まり、負数はエラーです。

drawing=falseは、その繰返し位置を描画しない場合に使います。設定は値の一覧へ追加され、同じ名前・同じ位置の以前の設定を削除する操作ではありません。一か所への値は一度に決めて渡します。動的属性の値にはnullを使えず、xとyは両方指定するか、両方省略します。

typeを省略（null）すると、そのページで有効な帳票定義から対応するDynamic型を推論します。明示したtypeはそのまま優先します。定義にない名前は従来互換のDynamicTextになります。空の名前、負のindex、x/yの片方だけの指定、null属性値は例外です。

4.2 ページごとに定義を切り替えるRM009

表紙と本文、途中から異なる一覧形式などでは、ページ開始時に別のPREPDJを渡します。座標をプログラムへ直接書くのではなく、デザイナーで完成させた定義をページへ結び付けます。定義を変更する前に現在のページを必ず確定してください。

5. 明細と改ページRM010

以下は自作帳票へ組み込む抜粋です。definitionには「ページ」「品番」「品名」「金額」を持つ定義を、detailsにはCode・Name・Amountを持つ明細リストを用意します。01の定義へそのまま貼り付ける例ではありません。

var print = new PrintData().SetDefinition(definition);
for (var offset = 0; offset < details.Count; offset += 20) {
    print.PageStart().SetValue("ページ", offset / 20 + 1);
    foreach (var pair in details.Skip(offset).Take(20).Select((d, row) => (d, row)))
        print.SetValue("品番", pair.d.Code, pair.row)
             .SetValue("品名", pair.d.Name, pair.row)
             .SetValue("金額", pair.d.Amount, pair.row);
    print.PageEnd();
}

1ページの行数は帳票定義と業務仕様から決めます。最終ページの空行を描画するか、明細ごとに罫線を出すかもプログラム側で明示します。ページ番号はPREPEJのページ順と、帳票へ表示する業務上のページ番号を分けて考えます。

5.1 空文字で罫線・図形を消すRM011

罫線・四角・円（Line、DynamicLine、Square／Rectangle、Circle／Ellipse）は、値で表示を切り替えられます。

繰返しの行でも、1つだけの図形でも同じです。最初に書いたときも、別の値のあとに書いたときも同じです。表の行を途中で終える、合計行の上だけ線を引かない、条件で枠を消す、などに使います。次の明細線は、定義にある罫線のオブジェクト名の例です。

print.SetValue("明細線", "", row); // この行の罫線を消す

drawing=falseも描きません。PREPEJでは、図形の値が""ならDrawingがtrueでも描きません。

文字の欄（Text）は別の規則です。値が""またはnullなら、文字も枠線も背景色も描きません。SVG・印刷・PDFで同じです。

5.2 何も書かない繰返しは1行目だけ描くRM012

繰返し（RepeatCountが2以上）のある物体に、そのページで何も書かないと、定義どおり1つだけ、1行目の位置に描きます。行の数だけ並べては描きません。

一部の行にだけ書くと、書いた行だけ描きます。書かなかった行は描きません。1行目に書かなければ、1行目も描きません。

表の罫線や枠を全部の行に描くには、描きたい行それぞれにnull（値なし）を書きます。罫線・図形はnullなら描き、""なら消えます（5.1）。次の1行を上の明細のループに足すと、明細の行数ぶん明細線にnullを書きます。DrawObjectは値なし（null）を書きます。

print.DrawObject("明細線", pair.row); // この行の罫線を描く（null を書く）

文字の欄は、nullを書くとその行の文字が空になります。定義の文字を出したい行には、その文字を書きます。PREPEJへ保存した印刷データでも同じです。

6. 画像・バーコード・動的属性RM013

値を書いていない文字・四角には、同じページで前に値を書いた物体の最後の行と同じ行の属性だけが当たります。値なしの罫線・楕円・画像・バーコードの旧形式の属性は当たりません。

この抜粋では、ページ開始後のprint、画像のdata URIを持つstampDataUri、対応する「角印」「商品QR」「合計金額」を定義に用意していることを前提にします。

print.SetImage("角印", stampDataUri)
    .SetBarcode("商品QR", "https://example.jp/items/123")
    .ChangeAttributes("合計金額", new Dictionary<string, object> {
        ["bold"] = true, ["fontSize"] = 16,
        ["horizontalAlignment"] = "Right"
    });

画像は閲覧先でも取得できる管理下のURL、または許容サイズのdata URIにします。サーバーPDF生成では、任意の外部URLをそのまま取得するとSSRFにつながります。固定画像は許可リストまたはアプリ管理下のファイルから解決してください。

動的属性では、名前・型・値を無検証のリクエストから直接渡さないでください。変更できる属性をアプリ側で限定し、数値範囲、色、配置、フォント名を検証します。

7. ブラウザへ渡して表示するRM014

C#／.NET APIはPREPEJをapplication/json; charset=utf-8で返します。ブラウザ側は共通のReports Web APIへ渡します。

<iframe id="reportsViewer" title="帳票プレビュー"
        style="width:100%;height:75vh;border:0"></iframe>
<script>
const viewer = document.querySelector('#reportsViewer');
viewer.addEventListener('load', async () => {
  const response = await fetch('/print-data');
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  await viewer.contentWindow.ReportsWeb.setPrintData(await response.json());
});
viewer.src = '/reports.web/preview/index.html?empty=1';
</script>

上の抜粋は01のURLを使います。実際の受信・エラー表示・PDF保存は01のindex.htmlで確認できます。自作アプリでは配信先に合わせてURLを変更します。

親画面とプレビュアーは同一オリジンに置くのが最も簡単です。別オリジンでpostMessageを使う場合は、送信元と送信先のoriginを固定し、*を本番環境で使わないでください。

プレビュアー側ではsetZoom("auto")、ページ移動、検索、印刷、exportPdf()、savePrintData()を利用できます。独自画面へ表示面だけを組み込む場合はhideAll()でツール群を隠し、同じ機能を外側のボタンから呼び出します。

8. PDFを作る二つの場所RM015

8.1 ブラウザで作るRM016

PREPEJを利用者のブラウザへ渡し、ブラウザ内のWASMがPDFを生成します。サーバーのPDF描画負荷を抑え、プレビューからそのまま保存・印刷する操作に向きます。機密データをブラウザへ渡してよいかは、業務の認可設計で判断します。

8.2 サーバーで作るRM017

ASP.NET Coreから共通Node/WASMサービスへHTTPでPREPEJを送ります。 定期処理、メール添付、保存、監査、画面を開かない帳票生成に向きます。

POST /render/pdf
Content-Type: application/json

<PREPEJ JSON>

成功時はapplication/pdfを返します。失敗時は次の状態コードと、理由を書いたJSON（{"error":"…"}）を返します。

408・413・503のときもサーバーは止まらず、次の要求を処理します。業務アプリ側でも処理時間を制限し、失敗時の途中PDFを保存・配信しないでください。ブラウザ生成とサーバー生成は同じPREPEJを入力にするため、業務データ組立てを二重実装する必要はありません。

9. PREPEJを保存・再利用するRM018

Saveは完成したPREPEJをUTF-8 JSONとして保存します。保存前にページをすべて確定してください。ファイル名には.prepejを使い、アップロード時には拡張子だけで信用せず、Format、Version、Definition、Pages、サイズ、ページ数を検証します。

保存した文書は、Webプレビュアーの「開く」またはドラッグ＆ドロップで再表示できます。HTTPで受け渡す場合もファイルと同じJSONです。再印刷の証跡として保管する場合は、業務データの保持期間、暗号化、アクセス権、削除規則を定めます。

10. Web APIとデータベースRM019

DB列と帳票オブジェクト名はコードで明示的に対応付けます。SQLはプレースホルダーを使い、利用者が参照できる伝票かを取得前に確認します。日付、通貨、端数処理は帳票へ渡す前に業務規則で確定します。

機密帳票のレスポンスにはCache-Control: no-storeを設定します。内部例外、接続文字列、ファイルパスを利用者へ返さず、要求IDを安全なサーバーログへ残します。帳票定義や画像は可能なら公開ルート外へ置きます。

11. テストとリリース確認RM020

まず同梱01～03のREADMEに従い、表示・編集・PDF保存・PREPEJ再読込を確認します。Dockerだけを準備したPCでも行えます。開発リポジトリ専用のパスやDB設定を、配布ZIPの起動手順として使う必要はありません。

最低限、次を確認します。

• 共通印刷データの形式識別子を持ち、Versionが1.0である
• PREPDJを設定せずにページを開始するとエラーになる
• ページを閉じずに次のページを開始できない
• 日本語、改行、数値、真偽値、nullが壊れない
• 明細の先頭・最終行、改ページ前後に欠落や重複がない
• ページ途中の帳票定義切替が、完了済みページを変更しない
• 画像・角印、バーコード、動的属性がSVGとPDFへ反映される
• 保存したPREPEJを開き直すと同じページ・内容になる
• ブラウザ生成とサーバー生成のページ数・主要表示が一致する

ラッパー変更時はWASM描画エンジン全体を毎回再試験するのではなく、生成PREPEJが共通仕様と基準サンプルに一致することを中心に確認します。WASM、プレビュアー、フォント、画像処理を変更した場合は、別途描画回帰試験が必要です。

12. よくある問題RM021

13. 配置・更新・ライセンスRM022

ラッパー、プレビュアー、JavaScript／TypeScript、CSS、WASMは同じReports.web配布版から取り出してください。HTMLだけ、またはラッパーだけを別バージョンへ差し替えると、PREPEJや公開APIの互換性を判断できなくなります。

現行の製品版への切替は、購入者のメールアドレスを含む電子署名付きの reports-web.license を、実際に帳票を出力する側へ配置して行います。購入者ごとにWASMを差し替える手順ではありません。ブラウザーとサーバーでは配置先が異なるため、製品版を使い始めるに従ってください。ライセンスファイルを公開サンプルやソース管理へ混入させないでください。正式な動作環境、使用許諾、更新履歴、問い合わせ先は共通製品マニュアルを正本とします。開発ライセンスは開発用PC 1台につき1ライセンスです。