このガイドは、すでに ReoGrid V3(MIT ライセンスのオープンソース版)でアプリケーションを構築している開発者向けに、ReoGrid V4(商用ライセンス版)への移行手順をまとめたものです。
V3 は引き続きオープンソースとしてメンテナンスされています。V4 は別系列の商用製品で、機能が大幅に拡張されています。機能概要は V4 の新機能 をご覧ください。
要約
- V4 の DLL に差し替えただけではコンパイルが通りません。 一部の公開クラス・インターフェース名が変更され、いくつかの例外型が削除され、データバインドやフィルター周りの API が再構成されています。
- 以下のリネームには互換シムがありません。 コードの変更が必要です。ほかの古いメンバーの一部は
[Obsolete]として残っています。 - 破壊的変更は機械的に修正可能です。 多くのプロジェクトは、置換と数か所の構造修正で移行できます。コア API(
Workbook,Worksheet,Cell,RangePosition,CellPosition,WorksheetRangeStyleなど)は変更ありません。 - 挙動変更は軽微で、Excel 互換性を高めるものです。 ソート時に数式が行とともに移動する、ゼロ除算で
FormulaStatus.InvalidValueになる、などの Excel 寄りの挙動になりました。詳しくは下記セクション 2 を参照してください。 - 配布方法。 V4 は UNVELL の NuGet パッケージフィードからインストールするか、カスタマーポータルから DLL をダウンロードして利用します。詳しくはインストールをご覧ください。ルート名前空間
unvell.ReoGridとアセンブリ名は変わっていないため、パッケージまたは DLL の参照を差し替えるだけでビルド構成上の変更は完了します。V4 はnet48およびnet8.0-windowsをターゲットとします。 - ライセンスキーが必要です。 v4.5 から、アプリケーションの起動時に
ReoGridLicense.SetLicenseを呼ぶ必要があります。有効なキーがないと、グリッドがグレーのオーバーレイで覆われ、入力がブロックされます。詳しくはライセンスキーの設定をご覧ください。
0. 始める前に: ターゲットフレームワークに合った DLL を参照する
V4 のパッケージには unvell.ReoGrid.dll のビルドが 2 つ含まれています(net48 フォルダーと net8.0-windows フォルダー)。プロジェクトのターゲットフレームワークに合ったほうを参照してください。
取り違えると、API の破壊的変更のように見える大量のエラーが発生します。
Import of type 'Color' from assembly or module 'System.Drawing.Primitives.dll' failed.
Import of type 'Encoding' from assembly or module 'System.Runtime.dll' failed.
Import of type 'Stream' from assembly or module 'System.Runtime.dll' failed.
これは、net48 のプロジェクトが net8.0-windows のビルドを参照している(またはその逆の)場合の典型的な症状です。net8.0-windows の DLL はファサードアセンブリ(System.Runtime.dll、System.Drawing.Primitives.dll)への型転送を持っていますが、これらは .NET Framework 4.8 には同じ形では存在しません。合ったビルドに切り替えると、こうしたエラーはまとめて解消し、以下に挙げる実際の API の違いだけが残ります。
VB.NET プロジェクト: 同じルールが当てはまります。V4 へのアップグレード後に出る
BC30005(「型を含むアセンブリへの参照が必要です」)とBC30456は、ほとんどの場合、メンバーの欠落ではなくこの不一致が原因です。まず参照を直してからビルドし直し、残ったエラーを確認してください。
1. コンパイルエラー系
V4 でビルドした際に最初に発生する破壊的変更です。いずれも機械的に修正できます。
A. アクション基底クラスのリネーム
BaseWorksheetAction は WorksheetAction に名前が変更されました。
- public class MyAction : BaseWorksheetAction
+ public class MyAction : WorksheetAction
- void RunAction(BaseWorksheetAction action) { sheet.DoAction(action); }
+ void RunAction(WorksheetAction action) { sheet.DoAction(action); }
カスタムの Undo 可能アクションすべて、およびアクションを基底型で受け渡しているコードに影響します。なお、V4 では Worksheet.DoAction が public に昇格しました(V3 では internal)。
B. アウトライン関連の型のリネーム
行・列のグルーピング(アウトライン)に関する基底クラスとインターフェースが、ReoGrid プレフィックスを外した名称になりました。
| V3 | V4 |
|---|---|
ReoGridOutline(抽象クラス) | BaseOutline |
IReoGridOutline(インターフェース) | IOutline |
- IReoGridOutline g = sheet.GetOutline(RowOrColumn.Row, 0, 5);
+ IOutline g = sheet.GetOutline(RowOrColumn.Row, 0, 5);
RowOutline および ColumnOutline の具象型名は変わっていません。基底クラス・インターフェースのみが変更されています。
C. ヘッダー型のリネーム
ReoGridHeader は WorksheetHeader に変更されました。
- ReoGridHeader h = sheet.RowHeaders[0];
+ WorksheetHeader h = sheet.RowHeaders[0];
RowHeader・ColumnHeader の名前は変わっていませんが、基底クラスが変更されています。
D. DropdownListCell の継承階層の変更
DropdownListCell の親クラスとして、新しい中間クラス DropdownListBaseCell が挿入されました。
V3: CellBody → DropdownCell → DropdownListCell
V4: CellBody → DropdownCell → DropdownListBaseCell → DropdownListCell
DropdownListCell を直接利用している場合は変更不要です。DropdownListCell を継承して protected メンバをオーバーライドしているカスタムクラスがある場合は、継承チェーンの変化に応じてオーバーライドの確認が必要です。なお、補完候補表示に対応した新しい兄弟型 ComboListCell も利用可能です。
E. 数式関連の例外クラスが削除
V4 では、数式評価エラーごとの個別例外クラスが廃止されました。以下の型は存在しません。
FormulaEvalutionExceptionFormulaNoNameExceptionFormulaParameterMismatchExceptionFormulaTypeMismatchException
これらを参照している catch ブロックはコンパイルエラーになります。V4 では、数式評価エラーは以下の方法で取得します。
Cell.FormulaStatus—FormulaStatus列挙体(InvalidName,InvalidValueなど)
例外ベースのエラー処理を、ステータスチェックに置き換えてください。
- try { sheet.Recalculate(); }
- catch (FormulaNoNameException) { /* ... */ }
+ sheet.Recalculate();
+ if (sheet.Cells["A1"].FormulaStatus == FormulaStatus.InvalidName) { /* ... */ }
なお、構文解析時の例外(FormulaParseException、新規追加の FormulaSyntaxErrorException / FormulaLiteralTooLongException)は引き続き公開されており、catch 可能です。
F. IsValidAddress のリネーム(v4.3.0)
V3 のアドレス文字列形式を判定するメソッドは、命名を明確化するためリネームされました。
- if (CellPosition.IsValidAddress(addr)) { ... }
+ if (CellPosition.IsValidAddressFormat(addr)) { ... }
V4 では、より厳密な意味を持つ Worksheet.IsValidAddress(string) が追加されました(形式の検証に加え、範囲内であるかも確認)。さらに、検証と安全なパースを兼ねた Worksheet.IsValidCellAddress(string, out CellPosition) および Worksheet.IsValidRangeAddress(string, out RangePosition) も追加されています。新しいコードではこれらの利用を推奨します。
G. ConditionalStyleApplyCells の削除(v4.4)
ConditionalStyleApplyCells プロパティと ConditionalStyleApplyCellCollection クラスは削除されました。
セルに条件付きスタイルが適用されているかどうかを確認するには、以下を使用します。
// セル単位の軽量チェック
bool has = sheet.Cells["A1"].HasConditionalStyles;
// もしくは Worksheet 経由
bool has = sheet.HasConditionalStyle(0, 0);
bool has = sheet.HasConditionalStyle(new CellPosition("A1"));
H. AutoFitColumnWidth / AutoFitRowHeight のリネームとシグネチャの変更
Worksheet の 1 行・1 列単位の自動調整メソッドは、範囲を受け取る複数形の名前に変わりました。
| V3 | V4 |
|---|---|
worksheet.AutoFitColumnWidth(int col, bool byAction = false) | worksheet.AutoFitColumnsWidth(int startCol, int colCount, int padding = 0) |
worksheet.AutoFitRowHeight(int row, bool byAction = false) | worksheet.AutoFitRowsHeight(int startRow, int rowCount, bool byAction = false) |
- worksheet.AutoFitColumnWidth(2);
+ worksheet.AutoFitColumnsWidth(2, 1);
- worksheet.AutoFitRowHeight(0, byAction: true);
+ worksheet.AutoFitRowsHeight(0, 1, byAction: true);
ColumnHeader.FitWidthToCells() / RowHeader.FitHeightToCells() は残っています([Obsolete] 付き)が、内部で新しい複数形のワークシートメソッドを呼び出します。複数の列・行を処理するときは、ヘッダーを 1 つずつループで処理せず、範囲を指定してワークシートの API を直接呼ぶほうが高速です。
I. DropdownListCell.Items の削除
V3 には、生成後に .Add() できる可変の DropdownListCell.Items プロパティ(DropdownItemsCollection)がありました。V4 では、生成時に渡す不変の CandidateSource(IStringValueListSource)に置き換わっています。
- var dropdown = new DropdownListCell();
- dropdown.Items.Add("USD");
- dropdown.Items.Add("JPY");
- dropdown.Items.Add("EUR");
+ var dropdown = new DropdownListCell("USD", "JPY", "EUR");
+ // または: new DropdownListCell(new[] { "USD", "JPY", "EUR" });
固定のリストではなくセル範囲にバインドする場合は、次のように書きます。
var listRange = sheet.Ranges["G1:G3000"];
var dropdown = new DropdownListCell(listRange);
現在の候補を読むには、dropdown.CandidateSource.Items(読み取り専用の IEnumerable<string>)を使います。
生成後に項目を変更したい場合: 元の IEnumerable<string> への参照を手元に保持してください。StringListSource は渡された参照をコピーせずに保持し、ドロップダウンはポップアップを開くたびにそれを読み直します。つまり、元のリストを変更することが、V3 の dropdown.Items.Add(...) に相当します。
var list = new List<string> { "Item 1", "Item 2", "Item 3" };
var dropdown = new DropdownListCell(list);
sheet.Cells["F2"].Body = dropdown;
list.Add("Item 4"); // ✓ 次にドロップダウンを開いたときに反映される
list.AddRange(new[] { "Item 5", "Item 6" }); // ✓
list.Clear(); // ✓
list = new List<string>(); // ✗ 新しいインスタンス — ドロップダウンは古い参照を保持したまま
フィルタリングや非同期読み込みなど、より複雑な場合は、Items ゲッターが最新のコレクションを返す独自の IStringValueListSource を実装してください。
J. 長く非推奨だった V3 の型の削除
しばらくビルドしていないプロジェクトでは、V3 の後期にすでに [Obsolete] だった名前が V4 で削除されたことによるエラーが出ることがあります。最も多いのは次のエラーです。
Type 'unvell.ReoGrid.ReoGridCell' is not defined
ReoGridCell は V3 の 2018 年ごろに Cell に改名され、互換用の旧クラスは 2021 年 4 月(V3 v1.7)に V3 からも削除されました。V4 にもありません。 どちらも修正方法は同じです。
- unvell.ReoGrid.ReoGridCell cell = sheet.GetCell(0, 0);
+ unvell.ReoGrid.Cell cell = sheet.GetCell(0, 0);
同じ時期の V3 の整理で削除された名前には、ReoGrid で始まる各種の型エイリアスなどがあります。古い名前で「型が定義されていません」というエラーが出たら、このカテゴリに当たらないか確認してください。
K. VB.NET: Color を SolidColor に暗黙変換できない
厳密には V3 から V4 への破壊的変更ではなく V3 にも当てはまりますが、VB.NET では V4 へのアップグレード中に多数の行で一度に発生して気付くことがよくあります。
Value of type 'Color' cannot be converted to 'SolidColor'.
ReoGrid は System.Drawing.Color から SolidColor への暗黙の変換演算子を定義しています(WinForms 版)。C# では自動的に使われますが、Option Strict On の VB.NET では使われません。 VB は C# のユーザー定義暗黙演算子を縮小変換として扱うため、明示的なキャストが必要です。
' Option Strict On ではコンパイルできません:
sheet.Cells("A1").Style.BackColor = Color.Red
' 修正方法(いずれか):
sheet.Cells("A1").Style.BackColor = SolidColor.Red
sheet.Cells("A1").Style.BackColor = SolidColor.FromArgb(255, 0, 0)
sheet.Cells("A1").Style.BackColor = CType(Color.Red, SolidColor)
新しい VB.NET のコードでは SolidColor.Red(および名前付きの SolidColor 定数)を使うことをおすすめします。WPF 版: System.Drawing.Color → SolidColor の演算子自体がありません。SolidColor を直接使うか、System.Windows.Media.Color から変換してください。
2. 動作(セマンティクス)の変更
コンパイルは通りますが、挙動が V3 と異なる項目です。テストの結果が想定外になった場合は、ここを確認してください。
ソート時に数式が行と一緒に移動
V3 ではソート対象は値のみで、数式セルはその場に残っていました。V4 では、Excel と同様に数式も行と一緒に移動します。 ソート後も数式の位置を固定したい場合は、絶対参照($A$1)を使うか、ソート前に数式を値に置き換えてください。
条件付きスタイルが描画タイミングで評価
V3 ではセル編集のたびに条件付きスタイルを再評価していました。V4 では「dirty フラグ」を立てておき、描画サイクルごとにまとめて評価します。大規模シートでの応答性が大幅に向上しますが、データ代入の直後・次の描画前に「実効スタイル」を読み出すコードでは、まだ反映されていない可能性があります。描画外のコードでは HasConditionalStyles を確認し、必要に応じて明示的に再評価してください。
Excel 互換の数式パース
V4 では数式パーサーが Excel に近づいています。
- 単項プラス演算子。
=+D25-F8-F14が正しく解釈されます(V3 ではエラー)。 - 括弧や空白を含むシート名の引用。
'BS(USD)'!B3,'My Sheet'!A1が有効になりました。 0は FALSE と評価。IF(0, x, y)はyを返します。0 以外の数値は TRUE として評価されます。0 ≠ FALSEを前提としていたコードは分岐結果が変わります。- ゼロ除算。
=A1/0ではCell.FormulaStatusがNormalからFormulaStatus.InvalidValueに変わります。 - 文字列の数値変換(乗算).
="10"*2は20を返します(V3 ではエラー)。 - VLOOKUP / HLOOKUP / MATCH / XMATCH / XLOOKUP が実装されました。近似一致を使用する場合は、Excel と同様にデータが昇順にソートされている必要があります。
シートタブ描画・スクロール挙動・フォントルックアップ
ピクセル単位の UI スナップショットや視覚回帰テストを実施されている場合、スクロールバーの限界、フォントのフォールバック、シートタブ描画、ズーム時の文字スケーリングなどに微小な差異が生じます。これらは描画品質の改善であり、不具合ではありませんが、念のため再確認してください。
浮動小数点の精度補正
V4 では WorksheetOptions.FormulaCalculationPrecision が追加されました。デフォルトは LowPrecision(Excel に近い表示)です。V3 と同じ結果にするには NoPrecisionCorrection を使います(最速ですが、3.00000000000004 のように表示されることがあります)。
sheet.Options.FormulaCalculationPrecision = FormulaCalculationPrecision.NoPrecisionCorrection;
3. 採用を検討すべき新 API
コンパイルが通り、既存テストが緑になった後に検討してほしい V4 機能です。いずれも追加機能で、移行に必須ではありません。
100 万行クラスのデータに対応する遅延ロード
worksheet.SetRows(1_000_000);
worksheet.AddDataSource(
new RangePosition(0, 0, 1_000_000, 10),
new MyDataSource(logs),
DataSourceLoadMode.LazyLoading);
V3 の IDataSource<T> はチャート用途のみでしたが、V4 ではセル範囲にデータをバインドするための unvell.ReoGrid.Data.IDataSource<T> が新たに追加され、必要に応じて遅延ロードに対応します。
複数行ヘッダー
var ext = worksheet.ExtensionColumnHeader;
ext.SetRowCount(3);
ext.MergeCells(0, 1, 2, 1);
ext[0, 1].Text = "大分類";
条件付きスタイル
using unvell.ReoGrid.ConditionalStyle;
var rule = new Rule("THIS > 1000", "A1:Z30",
new WorksheetRangeStyle {
Flag = PlainStyleFlag.TextColor,
TextColor = SolidColor.Yellow,
});
sheet.ConditionalStyles.Add(rule);
THIS は現在のセルの値を参照する予約語です。
条件付きフィルター
using unvell.ReoGrid.Data.ConditionFilter;
var filter = new ConditionalDataFilter();
filter.Conditions.Add(new FilterCondition("currency", ConditionOperator.NotEquals, "USD"));
sheet.DoFilter("A1:G30", filter);
3 段階のセルロック
V4 では Cell.IsLocked プロパティ(型は CellLock 列挙体:Locked, Unlocked, Inherit)が追加されました。V3 にはセル単位のロックモデルがありませんでした。
sheet.IsLocked = true;
sheet.Cells["C5"].IsLocked = CellLock.Unlocked;
注意:列挙体の値は
Unlocked(大文字 1 つ)です。古いサンプルでUnLockedと書かれているものはタイポです。
Excel 互換のカスタム数値書式
cell.DataFormat = CellDataFormatFlag.Number;
cell.DataFormatArgs = "#,##0;[Red]-#,##0";
セル範囲を候補リストとした DropdownListCell
var listRange = sheet1.Ranges["G1:G3000"];
var dropdown = new DropdownListCell(listRange);
sheet1.Cells["A1"].Body = dropdown;
ワークブック全体のハイライト付きテキスト検索
using unvell.ReoGrid.TextSearch;
var session = new HighlightTextSearchSession(Workbook, keyword, Workbook.CurrentWorksheet);
session.Search();
session.MarkAllResultHighlight(SolidColor.Goldenrod);
session.NextMatch();
アウトラインの一括展開/折りたたみ・ボタン位置
sheet.OutlineButtonLocation = OutlineButtonLocation.Top;
var group = sheet.GetOutlineGroup(RowOrColumn.Row, 0);
group.CollapseAll();
group.ExpandAll();
WinAppDriver による UI 自動テスト
WPF 版で利用できます。
ReoGridControl.EnableUIAutomation = true;
すべての新機能は V4 新機能 と リリースノート を参照してください。
4. 移行チェックリスト
- V3 の参照を V4 に差し替え(パッケージフィードまたはカスタマーポータルから入手)
- プロジェクトのターゲットが
net48またはnet8.0-windowsであること、DLL を直接参照する場合は対応するフォルダーの DLL であることを確認(セクション 0) - ビルドして、セクション 1(A〜K)のリネームエラーを修正
- アプリケーションの起動時に
ReoGridLicense.SetLicenseを呼ぶ(v4.5 から必須) - 数式関連の
catchブロックをCell.FormulaStatusのチェックに置き換え(セクション 1-E) - 既存のテストスイートを実行し、ソート順・数式・ゼロ除算などの差異を確認(セクション 2)
- (任意)セクション 3 の新 API のうち、アプリケーションに合うものを採用
5. ライセンス
V4 は商用ライセンスの製品です。
| V4 Professional | V4 Enterprise | |
|---|---|---|
| 利用可能端末数 | 3 台以下 | 無制限 |
| アップデート&技術サポート | 1 年間付属 | 1 年間付属 |
| 価格 | 価格表 | 価格表 |
V3 は引き続き MIT ライセンスのオープンソースとして GitHub で公開されています。
6. お問い合わせ
このガイドに記載のない移行上の課題(特にカスタムセル型、カスタムアクション、大規模なデータバインド処理など)が発生した場合は、サポート窓口 までご連絡ください。V3 のパターンに対する V4 での最適な置き換え方法をご案内します。