【実務・中級編】【中級者向け】カスタムフィールドの数式が循環参照を起こした際の自動検知と警告ログ出力 – Project VBA解析バイブル

スポンサーリンク
スポンサーリンク

Project VBAにおける「計算の連鎖」を支配せよ:カスタムフィールドの循環参照を検知する堅牢な設計思想

MS Projectを用いた高度なプロジェクト管理において、カスタムフィールド(数式)の活用は避けて通れない。工数、コスト、リスク、リソース負荷――これらを自動計算させる数式は、プロジェクトの「脳」となる。

しかし、多くの開発者が陥る致命的な罠がある。それが「循環参照(Circular Reference)」だ。

数式Aが数式Bを参照し、数式Bが数式Aを参照する。あるいは、数式Aが自分自身を参照する。この瞬間、計算エンジンは無限ループの淵に立たされ、プロジェクトのデータ整合性は崩壊する。最悪の場合、MS Projectの挙動が不安定になり、ユーザーは「なぜか計算結果が更新されない」という、原因特定が極めて困難なバグに直面することになる。

本記事では、単に数式を流し込むだけのコードを書く「作業者」を卒業し、計算エンジンの整合性を担保し、エラーを構造的に捕捉できる「アーキテクト」への道を提示する。

1. なぜ、あなたのデバッグは失敗するのか

多くの初級・中級者が犯すミスは、数式を `SetFormula` する際に `On Error Resume Next` でエラーを握りつぶしてしまうことだ。

' 典型的なアンチパターン:絶対に書くな
On Error Resume Next
T.SetFormula FieldID:=10, Formula:="[Text1] + [Text2]" 
' ここでエラーが出なくても、計算エンジンが走った瞬間に循環参照が発覚する
On Error GoTo 0

`SetFormula` メソッド自体は、数式の構文が正しい限り(=文字列として成立している限り)、エラーを返さない。真のエラーは、その後の計算フェーズ(Calculation Phase)、つまりオブジェクトのライフサイクルにおける「状態の更新時」に発生する。

プロフェッショナルな設計においては、「設定(Assignment)」と「検証(Validation)」を分離(Decoupling)しなければならない。

2. 堅牢な設計:検証・ログ出力・分離の3原則

循環参照を検知し、実務に耐えうるツールにするためには、以下の設計思想が必要だ。

① 検証(Validation)の分離

数式を適用した後、強制的に `Application.Calculate` を実行し、その結果として発生する計算エラーを、オブジェクトのプロパティレベルで走査して検知する。

② 構造化されたログ(Structured Logging)

`MsgBox` で警告を出すのは、ツールとしての完成度が低い。エラーが発生した「フィールド名」「数式の内容」「発生時刻」を、外部ファイル(CSV)または専用のログシートに構造化データとして書き出すべきだ。これにより、後からの監査(Audit)が可能になる。

③ 依存関係の隔離

計算ロジックをVBAコード内にハードコードせず、設定ファイルや定数管理クラスに分離することで、保守性を高める。

3. プロダクション・コードの実装例

以下に、カスタムフィールドの数式を設定し、直後に循環参照や計算エラーをスキャンしてログ出力する、実戦仕様のクラスモジュール・ロジックを示す。

実装のポイント

  • エラー検知の仕組み: MS Projectの計算エラーは、特定のフィールドを読み取ろうとした際に、計算エンジンがエラー状態を返さない場合がある。ここでは、再計算後にフィールドの整合性をチェックするアプローチをとる。
  • ログ出力: 追記型のCSVログを出力し、後続のデータ分析を容易にする。
Option Explicit

' ===========================================================================
' Module: CustomFieldValidator
' Purpose: カスタムフィールドの数式設定と、循環参照・計算エラーの検知
' ===========================================================================

Public Enum ErrorSeverity
    sevLow = 1        ' 注意
    sevCritical = 2   ' 致命的(循環参照の疑い)
End Enum

' ログ出力用の構造体
Private Type ErrorLog
    Timestamp As String
    FieldName As String
    Formula As String
    Severity As ErrorSeverity
    Message As String
End Type

''' <summary>
''' カスタムフィールドに数式を設定し、直後に整合性を検証する
''' </summary>
Public Sub ApplyAndValidateFormulas()
    Dim taskFieldID As Long
    Dim targetFormula As String
    Dim logPath As String
    
    ' 設定値(本来は外部ファイルや定数から取得すべき)
    taskFieldID = 10 ' 例: Text1
    targetFormula = "[Text2] + [Text1]" ' 意図的な循環参照のテスト用
    logPath = ThisWorkbook.Path & "\field_error_log.csv"
    
    On Error GoTo ErrorHandler

    ' 1. 数式の適用 (Assignment Phase)
    ' ここではエラーが出なくても、計算エンジンが壊れる可能性がある
    Application.TaskAssignments.SetFormula FieldID:=taskFieldID, Formula:=targetFormula
    
    ' 2. 強制再計算 (Calculation Phase)
    ' これにより、循環参照によるエラーを顕在化させる
    Application.Calculate
    
    ' 3. 検証 (Validation Phase)
    ' 計算エラーが発生していないか、フィールドの状態をスキャンする
    If Not PerformIntegrityCheck(taskFieldID, targetFormula, logPath) Then
        Debug.Print "Validation failed. Check log: " & logPath
    Else
        Debug.Print "Validation successful."
    End If

    Exit Sub

ErrorHandler:
    MsgBox "致命的なシステムエラーが発生しました: " & Err.Description, vbCritical
End Sub

''' <summary>
''' フィールドの整合性をチェックし、異常があればログに記録する
''' </summary>
Private Function PerformIntegrityCheck(fID As Long, formula As String, logPath As String) As Boolean
    Dim errFound As Boolean
    errFound = False
    
    ' MS Projectの計算エラーを検知するロジック
    ' 注意: Project VBAの仕様上、循環参照は特定のプロパティ参照時に
    ' 実行時エラーを投げるか、あるいは値が「不自然な値」になる。
    ' ここでは、計算エラーが発生しているかを確認する。
    
    On Error Resume Next
    Dim testVal As Variant
    ' 実際に値を読み取ろうとすることで、計算エンジンを動かす
    testVal = Application.TaskAssignments.GetField(FieldID:=fID, TaskID:=1)
    
    If Err.Number <> 0 Then
        ' 計算エラーが発生した場合
        WriteErrorLog logPath, "FieldID: " & fID, formula, sevCritical, "Circular Reference or Calculation Error: " & Err.Description
        errFound = True
        Err.Clear
    End If
    On Error GoTo 0
    
    PerformIntegrityCheck = Not errFound
End Function

''' <summary>
''' 構造化されたエラーログをCSV形式で出力する
''' </summary>
Private Sub WriteErrorLog(path As String, fName As String, formula As String, severity As ErrorSeverity, msg As String)
    Dim fileNum As Integer
    Dim sevText As String
    
    Select Case severity
        Case sevLow: sevText = "LOW"
        Case sevCritical: sevText = "CRITICAL"
    End Select
    
    fileNum = FreeFile
    
    ' ファイルが存在しない場合はヘッダーを書き込む
    If Dir(path) = "" Then
        Open path For Output As #fileNum
        Print #fileNum, "Timestamp,FieldName,Formula,Severity,Message"
    End If
    
    ' 追記モードでログを書き込み
    Open path For Append As #fileNum
    Print #fileNum, Format(Now, "yyyy-mm-dd HH:mm:ss") & "," & _
                    fName & "," & _
                    """" & formula & """" & "," & _
                    sevText & "," & _
                    """" & msg & """"
    Close #fileNum
End Sub

4. アーキテクトからのアドバイス:実務への適用

このコードをプロダクション環境に投入する際、以下の3点に留意せよ。

1. データベース連携への拡張

ログをCSVに出力しているが、大規模なプロジェクト管理ツールであれば、この `WriteErrorLog` を拡張し、SQL ServerやAzure SQL Databaseなどのリレーショナルデータベース(RDB)へ直接 `INSERT` する設計にせよ。これにより、複数のユーザーが実行したエラーログを一元管理し、プロジェクト全体の「計算の健全性」をダッシュボード化できる。

2. 冪等性(Idempotency)の確保

数式を再設定するコードは、何度実行しても同じ結果になる「冪等性」を持たせなければならない。既存の数式を一度クリアするのか、上書きするのか。その設計判断が、ユーザーのデータ破壊を防ぐ境界線となる。

3. 実行コンテキストの制御

`Application.Calculate` は非常に重い処理だ。全タスクに対して行うのではなく、変更を加えた特定のフィールドに関連する範囲に限定して検証を行うよう、計算範囲を絞り込むロジックを検討せよ。これは、大規模プロジェクト(数万行のタスク)において、パフォーマンスの決定的な差となる。

結論

VBAは単なる「自動化の道具」ではない。複雑なビジネスロジックを支える「インフラ」である。
循環参照を検知できないコードは、いつ爆発するか分からない時限爆弾をプロジェクトに仕込んでいるのと同じだ。

「書いたコードが正しく動くこと」ではなく、「コードが間違っていたときに、システムがいかに美しく失敗するか」を設計せよ。 それこそが、真のシニアエンジニアの仕事である。

タイトルとURLをコピーしました