Cómo: Escribir un registrador
Actualización: noviembre 2007
Los registradores proporcionan un método para personalizar el resultado de la generación y de mostrar mensajes, errores o advertencias en respuesta a eventos de generación específicos. Cada registrador se implementa como una clase .NET que, a su vez, implementa la interfaz ILogger, definida en el ensamblado Microsoft.Build.Framework.dll.
Existen dos métodos que se pueden utilizar al implementar un registrador:
Implementar la interfaz ILogger directamente.
Derive la clase a partir de la clase auxiliar, Logger, que se define en el ensamblado Microsoft.Build.Utilities.dll. Logger implementa ILogger y proporciona implementaciones predeterminadas de algunos miembros ILogger.
En este tema se explica cómo escribir un registrador simple que se deriva de Logger y muestra mensajes en la consola en respuesta a ciertos eventos de generación.
Registrarse para eventos
El propósito de un registrador consiste en recopilar información relacionada con la progresión del proceso de generación atendiendo a la notificación del motor de generación y, a continuación, elaborar informes con dicha información para que resulte útil. Todos los registradores deben reemplazar al método Initialize, que es donde el registrador se registra para los eventos. En este ejemplo, el registrador se registra para los eventos TargetStarted, ProjectStarted y ProjectFinished.
public class MySimpleLogger : Logger
{
public override void Initialize(Microsoft.Build.Framework.IEventSource eventSource)
{
//Register for the ProjectStarted, TargetStarted, and ProjectFinished events
eventSource.ProjectStarted += new ProjectStartedEventHandler(eventSource_ProjectStarted);
eventSource.TargetStarted += new TargetStartedEventHandler(eventSource_TargetStarted);
eventSource.ProjectFinished += new ProjectFinishedEventHandler(eventSource_ProjectFinished);
}
Responder a eventos
Ahora que el registrador se registra para eventos concretos, es necesario controlar dichos eventos cuando se producen. Para los eventos ProjectStarted y ProjectFinished, el registrador simplemente escribe una frase corta y el nombre del archivo de proyecto implicados en el evento. Todos los mensajes del registrador se escriben en la ventana de la consola.
void eventSource_ProjectStarted(object sender, ProjectStartedEventArgs e)
{
Console.WriteLine("Project Started: " + e.ProjectFile);
}
void eventSource_ProjectFinished(object sender, ProjectFinishedEventArgs e)
{
Console.WriteLine("Project Finished: " + e.ProjectFile);
}
Responder a los valores verbosity del registrador
En algunos casos, es posible que sólo se desee registrar información de un evento si el modificador /verbosity de MSBuild.exe contiene un determinado valor. En este ejemplo, el controlador de eventos TargetStarted sólo registra un mensaje si la propiedad Verbosity, que establece el modificador /verbosity, es igual a Detailed.
void eventSource_TargetStarted(object sender, TargetStartedEventArgs e)
{
if (Verbosity == LoggerVerbosity.Detailed)
{
Console.WriteLine("Target Started: " + e.TargetName);
}
}
Especificar un registrador
Cuando el registrador se compila en un ensamblado, es necesario indicar a MSBuild que utilice dicho registrador durante las compilaciones. Esto se hace utilizando el modificador /logger con MSBuild.exe. Para obtener más información sobre los modificadores disponibles para MSBuild.exe, vea Referencia de la línea de comandos de MSBuild.
La siguiente línea de comandos genera el proyecto MyProject.csproj y utiliza la clase de registrador implementada en SimpleLogger.dll. El modificador /nologo oculta la pancarta y el mensaje de copyright y el modificador /noconsolelogger deshabilita el registrador de consola de MSBuildpredeterminado.
MSBuild /nologo /noconsolelogger /logger:SimpleLogger.dll
La siguiente línea de comandos genera el proyecto con el mismo registrador, pero con un nivel Verbosity de Detailed.
MSBuild /nologo /noconsolelogger /logger:SimpleLogger.dll /verbosity:Detailed
Ejemplo
Descripción
El ejemplo siguiente contiene el código completo del registrador.
Código
using System;
using Microsoft.Build.Utilities;
using Microsoft.Build.Framework;
namespace SimpleLogger
{
public class MySimpleLogger : Logger
{
public override void Initialize(Microsoft.Build.Framework.IEventSource eventSource)
{
//Register for the ProjectStarted, TargetStarted, and ProjectFinished events
eventSource.ProjectStarted += new ProjectStartedEventHandler(eventSource_ProjectStarted);
eventSource.TargetStarted += new TargetStartedEventHandler(eventSource_TargetStarted);
eventSource.ProjectFinished += new ProjectFinishedEventHandler(eventSource_ProjectFinished);
}
void eventSource_ProjectStarted(object sender, ProjectStartedEventArgs e)
{
Console.WriteLine("Project Started: " + e.ProjectFile);
}
void eventSource_ProjectFinished(object sender, ProjectFinishedEventArgs e)
{
Console.WriteLine("Project Finished: " + e.ProjectFile);
}
void eventSource_TargetStarted(object sender, TargetStartedEventArgs e)
{
if (Verbosity == LoggerVerbosity.Detailed)
{
Console.WriteLine("Target Started: " + e.TargetName);
}
}
}
}
Ejemplo
Descripción
El ejemplo siguiente muestra cómo implementar un registrador que escribe el registro en un archivo en lugar de mostrarlo en la ventana de la consola.
Código
using System;
using System.IO;
using System.Security;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;
namespace MyLoggers
{
// This logger will derive from the Microsoft.Build.Utilities.Logger class,
// which provides it with getters and setters for Verbosity and Parameters,
// and a default empty Shutdown() implementation.
public class BasicFileLogger : Logger
{
/// <summary>
/// Initialize is guaranteed to be called by MSBuild at the start of the build
/// before any events are raised.
/// </summary>
public override void Initialize(IEventSource eventSource)
{
// The name of the log file should be passed as the first item in the
// "parameters" specification in the /logger switch. It is required
// to pass a log file to this logger. Other loggers may have zero or more than
// one parameters.
if (null == Parameters)
{
throw new LoggerException("Log file was not set.");
}
string[] parameters = Parameters.Split(';');
string logFile = parameters[0];
if (String.IsNullOrEmpty(logFile))
{
throw new LoggerException("Log file was not set.");
}
if (parameters.Length > 1)
{
throw new LoggerException("Too many parameters passed.");
}
try
{
// Open the file
this.streamWriter = new StreamWriter(logFile);
}
catch (Exception ex)
{
if
(
ex is UnauthorizedAccessException
|| ex is ArgumentNullException
|| ex is PathTooLongException
|| ex is DirectoryNotFoundException
|| ex is NotSupportedException
|| ex is ArgumentException
|| ex is SecurityException
|| ex is IOException
)
{
throw new LoggerException("Failed to create log file: " + ex.Message);
}
else
{
// Unexpected failure
throw;
}
}
// For brevity, we'll only register for certain event types. Loggers can also
// register to handle TargetStarted/Finished and other events.
eventSource.ProjectStarted += new ProjectStartedEventHandler(eventSource_ProjectStarted);
eventSource.TaskStarted += new TaskStartedEventHandler(eventSource_TaskStarted);
eventSource.MessageRaised += new BuildMessageEventHandler(eventSource_MessageRaised);
eventSource.WarningRaised += new BuildWarningEventHandler(eventSource_WarningRaised);
eventSource.ErrorRaised += new BuildErrorEventHandler(eventSource_ErrorRaised);
eventSource.ProjectFinished += new ProjectFinishedEventHandler(eventSource_ProjectFinished);
}
void eventSource_ErrorRaised(object sender, BuildErrorEventArgs e)
{
// BuildErrorEventArgs adds LineNumber, ColumnNumber, File, amongst other parameters
string line = String.Format(": ERROR {0}({1},{2}): ", e.File, e.LineNumber, e.ColumnNumber);
WriteLineWithSenderAndMessage(line, e);
}
void eventSource_WarningRaised(object sender, BuildWarningEventArgs e)
{
// BuildWarningEventArgs adds LineNumber, ColumnNumber, File, amongst other parameters
string line = String.Format(": Warning {0}({1},{2}): ", e.File, e.LineNumber, e.ColumnNumber);
WriteLineWithSenderAndMessage(line, e);
}
void eventSource_MessageRaised(object sender, BuildMessageEventArgs e)
{
// BuildMessageEventArgs adds Importance to BuildEventArgs
// Let's take account of the verbosity setting we've been passed in deciding whether to log the message
if ((e.Importance == MessageImportance.High && IsVerbosityAtLeast(LoggerVerbosity.Minimal))
|| (e.Importance == MessageImportance.Normal && IsVerbosityAtLeast(LoggerVerbosity.Normal))
|| (e.Importance == MessageImportance.Low && IsVerbosityAtLeast(LoggerVerbosity.Detailed))
)
{
WriteLineWithSenderAndMessage(String.Empty, e);
}
}
void eventSource_TaskStarted(object sender, TaskStartedEventArgs e)
{
// TaskStartedEventArgs adds ProjectFile, TaskFile, TaskName
// To keep this log clean, this logger will ignore these events.
}
void eventSource_ProjectStarted(object sender, ProjectStartedEventArgs e)
{
// ProjectStartedEventArgs adds ProjectFile, TargetNames
// Just the regular message string is good enough here, so just display that.
WriteLine(String.Empty, e);
indent++;
}
void eventSource_ProjectFinished(object sender, ProjectFinishedEventArgs e)
{
// The regular message string is good enough here too.
indent--;
WriteLine(String.Empty, e);
}
/// <summary>
/// Write a line to the log, adding the SenderName and Message
/// (these parameters are on all MSBuild event argument objects)
/// </summary>
private void WriteLineWithSenderAndMessage(string line, BuildEventArgs e)
{
if (0 == String.Compare(e.SenderName, "MSBuild", true /*ignore case*/))
{
// Well, if the sender name is MSBuild, let's leave it out for prettiness
WriteLine(line, e);
}
else
{
WriteLine(e.SenderName + ": " + line, e);
}
}
/// <summary>
/// Just write a line to the log
/// </summary>
private void WriteLine(string line, BuildEventArgs e)
{
for (int i = indent; i > 0; i--)
{
streamWriter.Write("\t");
}
streamWriter.WriteLine(line + e.Message);
}
/// <summary>
/// Shutdown() is guaranteed to be called by MSBuild at the end of the build, after all
/// events have been raised.
/// </summary>
public override void Shutdown()
{
// Done logging, let go of the file
streamWriter.Close();
}
private StreamWriter streamWriter;
private int indent;
}
}
Vea también
Conceptos
Información general sobre registro en MSBuild