Zápis protokolovacích nástrojů s více procesoryWrite multi-processor-aware loggers

Schopnost nástroje MSBuild využít výhod více procesorů může zkrátit dobu sestavování projektu, ale také přináší složitost pro protokolování událostí sestavení.The ability of MSBuild to take advantage of multiple processors can decrease project building time, but it also adds complexity to build event logging. V prostředí s jedním procesorem, události, zprávy, upozornění a chyby dorazí do protokolovacího nástroje předvídatelným sekvenčním způsobem.In a single-processor environment, events, messages, warnings, and errors arrive at the logger in a predictable, sequential manner. V prostředí s více procesory ale můžou události z různých zdrojů dorazit ve stejnou dobu nebo mimo pořadí.However, in a multi-processor environment, events from different sources can arrive at the same time or out of sequence. Za tímto účelem nástroj MSBuild poskytuje protokolovací nástroj s podporou více procesorů a nový model protokolování a umožňuje vytvořit vlastní "předávací protokolovací nástroje".To provide for this, MSBuild provides a multi-processor-aware logger and a new logging model, and lets you create custom "forwarding loggers."

Výzvy k protokolování s více procesoryMulti-processor logging challenges

Při sestavování jednoho nebo více projektů v systému s více procesory nebo s více jádry jsou generovány události sestavení nástroje MSBuild pro všechny projekty ve stejnou dobu.When you build one or more projects on a multi-processor or multi-core system, MSBuild build events for all the projects are generated at the same time. Avalanche zpráv událostí může přijít do protokolovacího nástroje ve stejnou dobu nebo mimo pořadí.An avalanche of event messages may arrive at the logger at the same time or out of sequence. Vzhledem k tomu, že protokolovací nástroj MSBuild 2,0 není navržený tak, aby zpracovávala tuto situaci, může přerušit protokolovací nástroj a způsobit zvýšené časy sestavení, nesprávný výstup protokolovacího nástroje nebo dokonce i přerušené sestavení.Because an MSBuild 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. Aby bylo možné tyto problémy vyřešit, protokolovací nástroj (začínající v MSBuild 3,5) může zpracovávat události mimo pořadí a korelovat události a jejich zdroje.To address these issues, the logger (starting in MSBuild 3.5) can process out-of-sequence events and correlate events and their sources.

Efektivitu protokolování lze ještě více zlepšit vytvořením vlastního předávajícího protokolovacího nástroje.You can improve logging efficiency even more by creating a custom forwarding logger. Vlastní protokolovací nástroj pro přesměrování funguje jako filtr tím, že vám umožní vybrat, ještě než začnete vytvářet, jenom události, které chcete monitorovat.A custom forwarding logger acts as a filter by letting you choose, before you build, only the events you want to monitor. Při použití vlastního protokolovacího nástroje pro předávání nemůžou nechtěné události přesměrovat protokolovací nástroj, zbytečně zastavovat protokoly nebo zpomalovat časy sestavení.When you use a custom forwarding logger, unwanted events cannot overwhelm the logger, clutter your logs, or slow build times.

Modely protokolování s více procesoryMulti-processor logging models

Pro zajištění potíží s sestavením s více procesory podporuje nástroj MSBuild dva modely protokolování, Central a distribuované.To provide for multi-processor-related build issues, MSBuild supports two logging models, central and distributed.

Model centrálního protokolováníCentral logging model

V modelu centrálního protokolování se jedna instance MSBuild.exe chová jako "centrální uzel" a podřízené instance centrálního uzlu ("sekundární uzly") se připojují k centrálnímu uzlu, který jim usnadní provádění úloh sestavení.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.

Model centrálního protokolovacího nástrojeCentral Logger Model

Protokolovací nástroje různých typů, které se připojují k centrálnímu uzlu, se nazývají "centrální protokolovací nástroje".Loggers of various types that attach to the central node are known as "central loggers." Pouze jedna instance každého typu protokolovacího nástroje může být současně připojena k centrálnímu uzlu.Only one instance of each logger type can be attached to the central node at the same time.

Když dojde k sestavení, sekundární uzly směrují své události sestavení do centrálního uzlu.When a build occurs, the secondary nodes route their build events to the central node. Centrální uzel směruje všechny své události a také sekundární uzly na jeden nebo více připojených centrálních protokolovacích nástrojů.The central node routes all its events, and also those of the secondary nodes, to one or more of the attached central loggers. Protokolovací nástroje pak vytvoří soubory protokolů, které jsou založeny na příchozích datech.The loggers then create log files that are based on the incoming data.

I když ILogger je nutné, aby byl implementován pouze pomocí centrálního protokolovacího nástroje, doporučujeme implementovat také, aby se INodeLogger centrální protokolovací nástroj inicializuje s počtem uzlů, které se účastní sestavení.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. Následující přetížení Initialize metody vyvolá v případě, že modul inicializuje protokolovací nástroj.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);
}

Jakékoli již existující ILogger protokolovací nástroje můžou fungovat jako centrální protokolovací nástroje a můžou se připojit k sestavení.Any pre-existing ILogger-based loggers can act as central loggers and can attach to the build. Centrální protokolovací nástroje zapsané bez explicitní podpory scénářů protokolování ve více procesorech a události mimo pořadí ale můžou přerušit sestavení nebo vytvářet nevýznamné výstupy.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.

Model distribuovaného protokolováníDistributed logging model

V modelu centrálního protokolování může příliš mnoho přenosů příchozích zpráv způsobit zahlcení centrálního uzlu, například při sestavení mnoha projektů ve stejnou dobu.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. To může nastresovat systémové prostředky a snížit výkon sestavení.This can stress system resources and decrease build performance. Pro usnadnění tohoto problému nástroj MSBuild podporuje model distribuovaného protokolování.To ease this problem, MSBuild supports a distributed logging model.

Model distribuovaného protokolováníDistributed Logging Model

Model distribuovaného protokolování rozšiřuje model centrálního protokolování tím, že vám umožní vytvořit protokolovací nástroj pro předávání.The distributed logging model extends the central logging model by letting you create a forwarding logger.

Přesměrování protokolovacích nástrojůForwarding loggers

Protokolovací nástroj pro předávání je sekundární a odlehčený protokolovací nástroj, který má filtr událostí, který se připojuje k sekundárnímu uzlu a přijímá příchozí události sestavení z tohoto uzlu.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. Filtruje příchozí události a předává pouze ty, které zadáte do centrálního uzlu.It filters the incoming events and forwards only the ones that you specify to the central node. Tím se snižuje přenos zpráv odeslaných do centrálního uzlu a zlepšuje se celkový výkon sestavení.This reduces the message traffic that is sent to the central node and improves overall build performance.

Existují dva způsoby, jak distribuované protokolování použít, a to takto:There are two ways to use distributed logging, as follows:

  • Přizpůsobení předem připraveného protokolovacího nástroje pro předávání s názvem ConfigurableForwardingLogger .Customize the pre-fabricated forwarding logger named ConfigurableForwardingLogger.

  • Napište si vlastní protokolovací nástroj pro přesměrování.Write your own custom forwarding logger.

ConfigurableForwardingLogger můžete upravit tak, aby vyhovovaly vašim požadavkům.You can modify ConfigurableForwardingLogger to suit your requirements. Chcete-li to provést, zavolejte protokolovací nástroj na příkazovém řádku pomocí MSBuild.exe a uveďte události sestavení, které má protokolovací nástroj předávat do centrálního uzlu.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.

Jako alternativu můžete vytvořit vlastní protokolovací nástroj pro předávání.As an alternative, you can create a custom forwarding logger. Vytvořením vlastního protokolovacího nástroje pro předávání můžete vyladit chování protokolovacího nástroje.By creating a custom forwarding logger, you can fine-tune the behavior of the logger. Vytvoření vlastního protokolovacího nástroje pro přesměrování je ale složitější než přizpůsobení ConfigurableForwardingLogger.However, creating a custom forwarding logger is more complex than just customizing the ConfigurableForwardingLogger. Další informace najdete v tématu vytváření protokolovacíchnástrojů pro předávání.For more information, see Creating forwarding loggers.

Použití ConfigurableForwardingLogger pro jednoduché distribuované protokolováníUsing the ConfigurableForwardingLogger for simple distributed logging

Chcete-li připojit ConfigurableForwardingLogger nebo vlastní protokolovací nástroj pro předávání, použijte -distributedlogger přepínač ( -dl pro krátký) v sestavení příkazového řádku MSBuild.exe .To attach either a ConfigurableForwardingLogger or a custom forwarding logger, use the -distributedlogger switch (-dl for short) in an MSBuild.exe command-line build. Formát pro zadání názvů typů a tříd protokolovacího nástroje je stejný jako u -logger přepínače, s tím rozdílem, že distribuovaný protokolovací nástroj má vždy dvě třídy protokolování namísto jednoho, protokolovacího nástroje pro předávání a centrálního protokolovacího nástroje.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. Následuje příklad připojení vlastního protokolovacího nástroje pro předávání s názvem XMLForwardingLogger.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

Poznámka

Hvězdička (*) musí oddělit dva názvy protokolovacích nástrojů v -dl přepínači.An asterisk (*) must separate the two logger names in the -dl switch.

Použití ConfigurableForwardingLogger se podobá použití jakéhokoli jiného protokolovacího nástroje (jak je uvedeno v části získání protokolů sestavení), s tím rozdílem, že přidáváte protokolovací nástroj ConfigurableForwardingLogger namísto typického protokolovacího nástroje MSBuild a zadáte jako parametry události, které má ConfigurableForwardingLogger předat do centrálního uzlu.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 MSBuild logger and you specify as parameters the events that you want the ConfigurableForwardingLogger to pass on to the central node.

Například pokud chcete být upozorněni pouze v případě, že sestavení začíná a končí a když dojde k chybě, předáte BUILDSTARTEDEVENT , BUILDFINISHEDEVENT a ERROREVENT jako parametry.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. Více parametrů lze předat jejich oddělením středníkem.Multiple parameters can be passed by separating them with semi-colons. Následující příklad ukazuje, jak používat ConfigurableForwardingLogger k přeposílání pouze BUILDSTARTEDEVENT BUILDFINISHEDEVENT událostí, a ERROREVENT .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

Následuje seznam dostupných parametrů ConfigurableForwardingLogger.The following is a list of the available ConfigurableForwardingLogger parameters.

Parametry ConfigurableForwardingLoggerConfigurableForwardingLogger Parameters
BUILDSTARTEDEVENTBUILDSTARTEDEVENT
BUILDFINISHEDEVENTBUILDFINISHEDEVENT
PROJECTSTARTEDEVENTPROJECTSTARTEDEVENT
PROJECTFINISHEDEVENTPROJECTFINISHEDEVENT
TARGETSTARTEDEVENTTARGETSTARTEDEVENT
TARGETFINISHEDEVENTTARGETFINISHEDEVENT
TASKSTARTEDEVENTTASKSTARTEDEVENT
TASKFINISHEDEVENTTASKFINISHEDEVENT
ERROREVENTERROREVENT
WARNINGEVENTWARNINGEVENT
HIGHMESSAGEEVENTHIGHMESSAGEEVENT
NORMALMESSAGEEVENTNORMALMESSAGEEVENT
LOWMESSAGEEVENTLOWMESSAGEEVENT
CUSTOMEVENTCUSTOMEVENT
ŘÁDEKCOMMANDLINE
PERFORMANCESUMMARYPERFORMANCESUMMARY
SouhrnNOSUMMARY
SHOWCOMMANDLINESHOWCOMMANDLINE

Viz takéSee also