ILogger Rozhraní

Definice

Toto rozhraní definuje v systému sestavení "protokolovací nástroj".This interface defines a "logger" in the build system. Protokolovací nástroj vytváří odběr systémových událostí.A logger subscribes to build system events. Všechny třídy protokolovacího nástroje musí implementovat toto rozhraní, aby ho modul sestavení rozpoznal.All logger classes must implement this interface to be recognized by the build engine.

public interface class ILogger
[System.Runtime.InteropServices.ComVisible(true)]
public interface ILogger
[<System.Runtime.InteropServices.ComVisible(true)>]
type ILogger = interface
Public Interface ILogger
Odvozené
Atributy

Příklady

Následující příklad ukazuje, jak napsat základní protokolovací nástroj.The following example shows how to write a basic logger.

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;
    }
}

Poznámky

Všechny třídy protokolovacího nástroje musí implementovat toto rozhraní, aby ho mohl rozpoznat MSBuildMSBuild modul.All logger classes must implement this interface to be recognized by the MSBuildMSBuild engine.

Místo implementace tohoto rozhraní přímo, můžete třídu také odvodit z pomocné třídy, Logger která poskytuje výchozí implementace některých ILogger členů.Instead of implementing this interface directly, you can also derive your class from the helper class, Logger, which provides default implementations of some ILogger members.

Vlastnosti

Parameters

Tato vlastnost obsahuje parametry zadané uživatelem pro protokolovací nástroj.This property holds the user-specified parameters to the logger. Pokud nejsou zadány parametry, protokolovací nástroj by měl vrátit výchozí hodnotu.If parameters are not provided, a logger should revert to defaults. Pokud protokolovací nástroj nepřijímá parametry, může tuto vlastnost ignorovat.If a logger does not take parameters, it can ignore this property.

Verbosity

Úroveň podrobností přesměruje množství podrobností, které se zobrazí v protokolu událostí protokolovacího nástroje.The verbosity level directs the amount of detail that appears in a logger's event log. I když se jedná jenom o doporučení založené na uživatelských preferencích a protokolovací nástroj si může vybrat přesné události, které protokoluje, je stále důležité, aby se pro správné prostředí uživatele použily pokyny pro každou úroveň.Though this is only a recommendation based on user preferences, and a logger is free to choose the exact events it logs, it is still important that the guidelines for each level be followed, for a good user experience.

Metody

Initialize(IEventSource)

Volá se modulem sestavení, který umožňuje protokolovacím nástrojům přihlašovat se k odběru událostí, které chtějí.Called by the build engine to allow loggers to subscribe to the events they desire.

Shutdown()

Volá se modulem sestavení, který umožňuje protokolovacím nástrojům uvolnit všechny prostředky, které mohou být přiděleny v době inicializace nebo během sestavení.Called by the build engine to allow loggers to release any resources they may have allocated at initialization time, or during the build.

Platí pro