マルチプロセッサ対応の logger の記述Writing Multi-Processor-Aware Loggers

MSBuildMSBuild では複数のプロセッサを使用できるため、プロジェクトのビルド時間が短縮されますが、同時にビルド イベント ログの複雑性も高まります。The ability of MSBuildMSBuild to take advantage of multiple processors can decrease project building time, but it also adds complexity to build event logging. シングルプロセッサ環境では、イベント、メッセージ、警告、およびエラーが順序に従った予測可能な方法で logger に到着します。In a single-processor environment, events, messages, warnings, and errors arrive at the logger in a predictable, sequential manner. それに対し、マルチプロセッサ環境では、イベントが複数のソースから同時に、または誤った順序で送られてくることがあります。However, in a multi-processor environment, events from different sources can arrive at the same time or out of sequence. この問題を解決するために、MSBuildMSBuild にはマルチプロセッサ対応の logger と新しいログ モデルが導入されており、カスタム "転送 logger" を作成できます。To provide for this, MSBuildMSBuild provides a multi-processor-aware logger and a new logging model, and lets you create custom "forwarding loggers."

マルチプロセッサ ログの問題点Multi-Processor Logging Challenges

1 つ以上のプロジェクトをマルチプロセッサ システムまたはマルチコア システムでビルドすると、すべてのプロジェクトの MSBuildMSBuild ビルド イベントが同時に生成されます。When you build one or more projects on a multi-processor or multi-core system, MSBuildMSBuild build events for all the projects are generated at the same time. 大量のイベント メッセージが同時に、または誤った順序で logger に送られてくる可能性があります。An avalanche of event messages may arrive at the logger at the same time or out of sequence. MSBuildMSBuild 2.0 の logger はこのような状況には対応していないため、logger が過負荷となり、ビルド時間の増加や不正確な logger 出力をもたらすだけでなく、ビルドが破損することもあります。Because a MSBuildMSBuild 2.0 logger is not designed to handle this situation, it can overwhelm the logger and cause increased build times, incorrect logger output, or even a broken build. これらの問題を解決するために、MSBuildMSBuild 3.5 以降の logger は順序が誤っているイベントを処理し、イベントとそのソースを対応付けます。To address these issues, the logger (starting in MSBuildMSBuild 3.5) can process out-of-sequence events and correlate events and their sources.

カスタム転送 logger を作成すると、ログの効率をさらに高めることができます。You can improve logging efficiency even more by creating a custom forwarding logger. カスタム転送 logger はフィルターの役割を果たし、ビルドを開始する前に監視の対象とするイベントのみを選択できます。A custom forwarding logger acts as a filter by letting you choose, before you build, only the events you want to monitor. カスタム転送 logger を使用すると、不要なイベントが除外されるため、logger の過負荷、ログの煩雑化、ビルド時間の増加を防ぐことができます。When you use a custom forwarding logger, unwanted events cannot overwhelm the logger, clutter your logs, or slow build times.

マルチプロセッサ ログ モデルMulti-Processor Logging Models

マルチプロセッサに起因するビルド関連の問題に対処するために、MSBuildMSBuild は中央ログ モデルと分散ログ モデルという 2 つのログ モデルをサポートしています。To provide for multi-processor-related build issues, MSBuildMSBuild supports two logging models, central and distributed.

中央ログ モデルCentral Logging Model

中央ログ モデルでは、MSBuild.exe の 1 つのインスタンスが "中央ノード" となり、中央ノードの子インスタンス ("セカンダリ ノード") が中央ノードにアタッチされ、それによってビルド タスクの実行が可能になります。In the central logging model, a single instance of MSBuild.exe acts as the "central node," and child instances of the central node ("secondary nodes") attach to the central node to help it perform build tasks.

中央 logger モデルCentral Logger Model

中央ノードにアタッチされる各種の logger を "中央 logger" といいます。Loggers of various types that attach to the central node are known as "central loggers." いずれの logger でも一度に 1 つのインスタンスのみ中央ノードにアタッチできます。Only one instance of each logger type can be attached to the central node at the same time.

ビルドを開始すると、セカンダリ ノードがビルド イベントを中央ノードにルーティングします。When a build occurs, the secondary nodes route their build events to the central node. 中央ノードは、受け取ったすべてのイベントとセカンダリ ノードのイベントを 1 つ以上のアタッチされた中央 logger にルーティングします。The central node routes all its events, and also those of the secondary nodes, to one or more of the attached central loggers. それらの logger は、受け取ったデータに基づくログ ファイルを作成します。The loggers then create log files that are based on the incoming data.

中央 logger による実装が必要なのは ILogger だけですが、中央 logger がビルドに参加するノードの数で初期化されるように、INodeLogger も実装することをお勧めします。Although only ILogger is required to be implemented by the central logger, we recommend that you also implement INodeLogger so that the central logger initializes with the number of nodes that are participating in the build. エンジンが logger を初期化するときには、次のような Initialize メソッドのオーバーロードが呼び出されます。The following overload of the Initialize method invokes when the engine initializes the logger.

public interface INodeLogger: ILogger  
{  
    public void Initialize(IEventSource eventSource, int nodeCount);  
}  

ILogger ベースの既存の logger を中央 logger として利用し、ビルドにアタッチすることができます。Any pre-existing ILogger-based loggers can act as central loggers and can attach to the build. ただし、マルチプロセッサ ログ シナリオと誤った順序のイベントの明示的なサポートが組み込まれていない中央 logger を使用すると、ビルドの破損や無意味な出力の生成につながる可能性があります。However, central loggers written without explicit support for multi-processor logging scenarios and out-of-order events may break a build or produce meaningless output.

分散ログ モデルDistributed Logging Model

中央ログ モデルでは、一度に多数のプロジェクトをビルドする場合など、大量の受信メッセージ トラフィックが発生し、中央ノードが過負荷となることがあります。In the central logging model, too much incoming message traffic can overwhelm the central node, for example, when many projects build at the same time. その結果、システム リソースの負荷増大やビルド パフォーマンスの低下を招くことがあります。This can stress system resources and decrease build performance. この問題を軽減するために、MSBuildMSBuild は分散ログ モデルをサポートしています。To ease this problem, MSBuildMSBuild supports a distributed logging model.

分散ログ モデルDistributed Logging Model

分散ログ モデルは、転送 logger の作成を可能にすることにより、中央ログ モデルを拡張したものです。The distributed logging model extends the central logging model by letting you create a forwarding logger.

転送 loggerForwarding Loggers

転送 logger は、イベント フィルターを備えた補助的で簡易な logger であり、セカンダリ ノードにアタッチされ、そのノードで生成されたビルド イベントを受け取ります。A forwarding logger is a secondary, lightweight logger that has an event filter that attaches to a secondary node and receives incoming build events from that node. 転送 logger は受け取ったイベントをフィルター処理し、指定されたイベントだけを中央ノードに転送します。It filters the incoming events and forwards only the ones that you specify to the central node. これによって、中央ノードに送信されるメッセージ トラフィックが減少し、全体的なビルド パフォーマンスが向上します。This reduces the message traffic that is sent to the central node and improves overall build performance.

分散ログには次の 2 つの使用方法があります。There are two ways to use distributed logging, as follows:

  • ConfigurableForwardingLogger という名前の用意された転送 logger をカスタマイズします。Customize the pre-fabricated forwarding logger named ConfigurableForwardingLogger.

  • カスタム転送 logger を独自に作成します。Write your own custom forwarding logger.

    ConfigurableForwardingLogger を実際の要件に合わせて変更できます。You can modify ConfigurableForwardingLogger to suit your requirements. これを行うには、この logger をコマンド ラインで MSBuild.exe を使用して呼び出し、この logger から中央ノードに転送するビルド イベントを指定します。To do this, call the logger on the command line by using MSBuild.exe, and list the build events that you want the logger to forward to the central node.

    また、カスタム転送 logger を作成することもできます。As an alternative, you can create a custom forwarding logger. カスタム転送 logger を作成すると、logger の動作を細かく調整できます。By creating a custom forwarding logger, you can fine-tune the behavior of the logger. ただし、カスタム転送 logger を作成する作業は ConfigurableForwardingLogger をカスタマイズする場合より複雑です。However, creating a custom forwarding logger is more complex than just customizing the ConfigurableForwardingLogger. 詳細については、「転送 logger の作成」を参照してください。For more information, see Creating Forwarding Loggers.

ConfigurableForwardingLogger を使用した簡単な分散ログUsing the ConfigurableForwardingLogger for Simple Distributed Logging

ConfigurableForwardingLogger またはカスタム転送 logger をアタッチするには、MSBuild.exe を使用したコマンド ライン ビルドに /distributedlogger スイッチ (短縮形は /dl) を指定します。To attach either a ConfigurableForwardingLogger or a custom forwarding logger, use the /distributedlogger switch (/dl for short) in an MSBuild.exe command-line build. logger の型名およびクラス名の形式は、/logger スイッチの場合と同じです。ただし、分散 logger は常に転送 logger と中央 logger という 2 つのログ記録クラスから成ります。The format for specifying the names of the logger types and classes is the same as that for the /logger switch, except that a distributed logger always has two logging classes instead of one, the forwarding logger and the central logger. XMLForwardingLogger というカスタム転送 logger をアタッチするコードの例を次に示します。The following is an example of how to attach a custom forwarding logger named XMLForwardingLogger.

msbuild.exe myproj.proj/distributedlogger:XMLCentralLogger,MyLogger,Version=1.0.2,Culture=neutral*XMLForwardingLogger,MyLogger,Version=1.0.2,Culture=neutral  

注意

/dl スイッチでは、2 つの logger 名をアスタリスク (*) で区切る必要があります。An asterisk (*) must separate the two logger names in the /dl switch.

ConfigurableForwardingLogger の使用方法は、通常の MSBuildMSBuild ではなく ConfigurableForwardingLogger logger をアタッチし、ConfigurableForwardingLogger から中央ノードに渡すイベントをパラメーターとして指定する点を除き、他の logger と同じです (「ビルド ログの取得」を参照)。Using the ConfigurableForwardingLogger is like using any other logger (as outlined in Obtaining Build Logs), except that you attach the ConfigurableForwardingLogger logger instead of the typical MSBuildMSBuild logger and you specify as parameters the events that you want the ConfigurableForwardingLogger to pass on to the central node.

たとえば、ビルドの開始および終了の時点とエラーの発生時のみ通知を受け取る場合は、パラメーターとして BUILDSTARTEDEVENTBUILDFINISHEDEVENT、および ERROREVENT を渡します。For example, if you want to be notified only when a build starts and ends, and when an error occurs, you would pass BUILDSTARTEDEVENT, BUILDFINISHEDEVENT, and ERROREVENT as parameters. 複数のパラメーターを渡す場合は、パラメーターをセミコロンで区切ります。Multiple parameters can be passed by separating them with semi-colons. ConfigurableForwardingLogger を使用して BUILDSTARTEDEVENTBUILDFINISHEDEVENTERROREVENT の各イベントのみを転送する方法を次の例に示します。The following is an example of how to use the ConfigurableForwardingLogger to forward only the BUILDSTARTEDEVENT, BUILDFINISHEDEVENT, and ERROREVENT events.

msbuild.exe myproj.proj /distributedlogger:XMLCentralLogger,MyLogger,Version=1.0.2,Culture=neutral*ConfigureableForwardingLogger,C:\My.dll;BUILDSTARTEDEVENT; BUILDFINISHEDEVENT;ERROREVENT  

ConfigurableForwardingLogger で使用できるパラメーターの一覧を次に示します。The following is a list of the available ConfigurableForwardingLogger parameters.

ConfigurableForwardingLogger のパラメーターConfigurableForwardingLogger Parameters
BUILDSTARTEDEVENTBUILDSTARTEDEVENT
BUILDFINISHEDEVENTBUILDFINISHEDEVENT
PROJECTSTARTEDEVENTPROJECTSTARTEDEVENT
PROJECTFINISHEDEVENTPROJECTFINISHEDEVENT
TARGETSTARTEDEVENTTARGETSTARTEDEVENT
TARGETFINISHEDEVENTTARGETFINISHEDEVENT
TASKSTARTEDEVENTTASKSTARTEDEVENT
TASKFINISHEDEVENTTASKFINISHEDEVENT
ERROREVENTERROREVENT
WARNINGEVENTWARNINGEVENT
HIGHMESSAGEEVENTHIGHMESSAGEEVENT
NORMALMESSAGEEVENTNORMALMESSAGEEVENT
LOWMESSAGEEVENTLOWMESSAGEEVENT
CUSTOMEVENTCUSTOMEVENT
COMMANDLINECOMMANDLINE
PERFORMANCESUMMARYPERFORMANCESUMMARY
NOSUMMARYNOSUMMARY
SHOWCOMMANDLINESHOWCOMMANDLINE

参照See Also

転送ロガーの作成Creating Forwarding Loggers