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

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

循環参照という静かなる破壊者:Project VBAにおけるカスタムフィールド・バリデーションの極致

多くの開発者は、コードが「動く」ことに満足する。しかし、我々アーキテクトの責務は、コードが「正しく、かつ堅牢に動き続ける」ことを保証することにある。

Microsoft Projectのカスタムフィールド(Task/Resource Custom Fields)をVBAで自動設定する際、最も恐ろしいのは実行時エラーではない。「循環参照(Circular Reference)」だ。これはVBAのランタイムエラーとして捕捉されることは稀であり、計算エンジンが沈黙のうちに計算を放棄するか、あるいは無限ループに近い負荷をシステムに強いることで、ユーザーのワークステーションをフリーズさせる。

本稿では、大規模なプロジェクト管理システムを設計・運用するシニアエンジニアに向けて、カスタムフィールドの数式設定における循環参照を検知し、エラー箇所を特定するための堅牢なデバッグ・バリデーション・フレームワークの構築手法を伝授する。

1. 計算エンジンのブラックボックスを理解する

Project VBAにおけるカスタムフィールドの数式は、VBAの実行コンテキストではなく、Project内部のCalculation Engine(計算エンジン)のコンテキストで評価される。

ここが重要な分かれ道だ。VBA側で `On Error Resume Next` を仕掛けても、数式内の論理エラー(循環参照を含む)はVBAの例外としてスローされない。数式の結果が `#ERROR` という文字列になったり、計算が停止したりするだけである。

したがって、我々が実装すべきは「VBAによるエラーハンドリング」ではなく、「計算結果の整合性を検証するポスト・プロセッシング・エンジン」である。

2. アーキテクチャ設計:検知・検証・記録の三層構造

堅牢なバリデーションツールには、以下の3つのレイヤーが必要となる。

1. Deployment Layer: 数式をカスタムフィールドへ注入する。
2. Validation Layer: `Application.Calculate` を強制実行した後、各フィールドの値を走査し、異常値(`#ERROR` 等)を検知する。
3. Logging Layer: 検知したエラーのコンテキスト(どのタスクの、どのフィールドが、どのような状態か)を、外部ログファイルへ永続化する。

ここで、メモリリークを回避し、大規模な `.mpp` ファイルでもパフォーマンスを維持するためには、オブジェクトの明示的な解放と、可能な限り低レベルな走査を行う設計が求められる。

3. 実装例:`ProjectDependencyGuard` クラス

以下に、プロフェッショナルな現場で即戦力となる、クラスモジュール形式の設計例を示す。単なるスクリプトではなく、オブジェクトのライフサイクルを管理する設計思想に基づいている。

クラスモジュール: `clsDependencyGuard`

' ===============================================================================
' Class: clsDependencyGuard
' Purpose: Project Custom Fieldsの循環参照および数式エラーを検知する
' Author: Legendary Chief Architect
' ===============================================================================
Option Explicit

Private m_App As MSProject.Application
Private m_LogPath As String

' Windows APIの宣言 (高精度なタイミング計測、またはシステム情報の取得に使用)
' ここではパフォーマンス計測の概念を示すために定義
Private Declare PtrSafe Function GetTickCount Lib "kernel32" () As Long

Private Sub Class_Initialize()
    Set m_App = MSProject.Application
    ' ログパスは環境変数や設定ファイルから取得するのが定石
    m_LogPath = Environ("TEMP") & "\ProjectVBA_ErrorLog_" & Format(Now, "yyyymmdd") & ".log"
End Sub

Private Sub Class_Terminate()
    ' オブジェクトの明示的解放
    Set m_App = Nothing
End Sub

''' <summary>
''' カスタムフィールドに数式を設定し、即座に整合性を検証する
''' </summary>
''' <param name="fieldType">Task または Resource</param>
''' <param name="fieldIndex">フィールド番号 (1-30)</param>
''' <param name="formula">設定する数式文字列</param>
Public Sub DeployAndValidate(ByVal fieldType As String, ByVal fieldIndex As Integer, ByVal formula As String)
    Dim startTime As Long
    startTime = GetTickCount()
    
    On Error GoTo ErrorHandler
    
    ' 1. Deployment: 数式の注入
    Debug.Print "Deploying formula to " & fieldType & " Field " & fieldIndex & "..."
    If UCase(fieldType) = "TASK" Then
        m_App.Tasks.GetField(fieldIndex, formula) ' 実際には CustomField プロパティ経由の操作が必要
        ' 注意: Project VBAのAPI仕様に基づき、正しいプロパティ操作を選択すること
        m_App.CustomFields("Task").Item(fieldIndex).Formula = formula
    Else
        m_App.CustomFields("Resource").Item(fieldIndex).Formula = formula
    End If

    ' 2. Trigger Calculation: 計算エンジンの強制駆動
    m_App.Calculate
    
    ' 3. Validation: 循環参照・エラーの走査
    If Not ValidateFieldIntegrity(fieldType, fieldIndex) Then
        WriteLog "CRITICAL", "Circular reference or Formula error detected in " & fieldType & " Field " & fieldIndex
    End If

    Debug.Print "Deployment completed in " & (GetTickCount() - startTime) & " ms."
    Exit Sub

ErrorHandler:
    WriteLog "ERROR", "Deployment failed: " & Err.Description
    Err.Raise Err.Number, "clsDependencyGuard.DeployAndValidate", Err.Description
End Sub

''' <summary>
''' フィールド内のエラー値を走査する内部メソッド
''' </summary>
Private Function ValidateFieldIntegrity(ByVal fieldType As String, ByVal fieldIndex As Integer) As Boolean
    Dim i As Long
    Dim targetValue As Variant
    Dim errorFound As Boolean
    errorFound = False

    ' パフォーマンス最適化のため、大規模プロジェクトでは範囲を絞るか、
    ' 統計的なサンプリングを行う設計も検討すべきだが、ここでは完全走査を行う
    If UCase(fieldType) = "TASK" Then
        For i = 1 To m_App.Tasks.Count
            targetValue = m_App.Tasks(i).GetField(fieldIndex) ' カスタムフィールドの値取得
            ' Projectにおける計算エラーの典型的なパターンを検知
            If IsErrorValue(targetValue) Then
                WriteLog "WARNING", "Task ID: " & i & " | Value: " & CStr(targetValue)
                errorFound = True
                ' 最初の1件を見つけたら即座に抜ける(デバッグ効率のため)
                Exit For 
            End If
        Next i
    End If
    
    ValidateFieldIntegrity = Not errorFound
End Function

''' <summary>
''' Project特有のエラー表示パターンを判定
''' </summary>
Private Function IsErrorValue(ByVal val As Variant) As Boolean
    ' Projectの数式エラーは文字列 "#ERROR" や特定の不整合として現れる
    If IsError(val) Then
        IsErrorValue = True
    ElseIf CStr(val) = "#ERROR" Or CStr(val) = "#VALUE!" Then
        IsErrorValue = True
    Else
        IsErrorValue = False
    End If
End Function

''' <summary>
''' 低レベルなファイルI/Oによるログ出力
''' </summary>
Private Sub WriteLog(ByVal level As String, ByVal message As String)
    Dim fso As Object
    Dim ts As Object
    Set fso = CreateObject("Scripting.FileSystemObject")
    
    On Error Resume Next
    Set ts = fso.OpenTextFile(m_LogPath, 8, True) ' 8 = ForAppending
    If Not ts Is Nothing Then
        ts.WriteLine "[" & Now & "] [" & level & "] " & message
        ts.Close
    End If
    Set ts = Nothing
    Set fso = Nothing
    On Error GoTo 0
End Sub

4. 技術的深掘り:なぜこの設計が「強い」のか

4.1. オブジェクトのライフサイクル管理

`Class_Terminate` において `Set m_App = Nothing` を明示している。これは、VBAのCOM参照カウントが意図せず増大し、プロジェクトファイルを閉じた後も `MSProject.exe` プロセスがメモリ上に居座り続ける「ゾンビプロセス」化を防ぐためだ。大規模な自動化バッチを組む際、この一歩がシステムの安定性を決定づける。

4.2. 循環参照検知のロジック

Projectの計算エンジンは、循環参照が発生すると計算を停止し、結果として `#ERROR` をフィールドに書き込む。我々の `IsErrorValue` 関数は、単なる `IsError` 関数ではなく、Project独自の文字列エラーパターンを考慮している。これにより、VBA側から「計算エンジンが失敗したこと」を間接的に、かつ確実に検知できる。

4.3. Windows API によるプロファイリング

`GetTickCount` を導入している理由は、単なる時間計測ではない。数式の設定から計算完了までの時間を計測することで、「計算負荷が異常に高い(=循環参照に近い、あるいは計算パスが極端に複雑な)数式」を統計的に特定するための布石である。

5. シニアエンジニアへの提言

カスタムフィールドの自動化は、一見すると単純なプロパティ操作に見える。しかし、それは計算エンジンの内部ロジックを外部から操作する、極めてデリケートな行為だ。

1. 冪等性(Idempotency)を確保せよ: 数式を再設定するたびに、古い値や計算結果が残らないよう、一度クリアするか、検証プロセスを必ず挟むこと。
2. ログは「死後の検証」に使うな: ログは、エラーが起きた瞬間に、その時のコンテキスト(タスクID、リソース名、現在の計算状態)を即座に、かつ詳細に吐き出すように設計せよ。
3. レガシーへの配慮: ユーザーが使用しているProjectのバージョンによって、計算エンジンの挙動は微妙に異なる。可能な限り、エラー検知のパターンは広めに持たせておくべきだ。

自動化とは、単に作業を減らすことではない。「人間が介在できない領域での、エラーの発生確率をゼロに近づけること」である。

*本文終了。貴殿のコードに、秩序と堅牢さがあらんことを。*

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