Class UdpAppender

Namespace

log4net.Appender

Assembly

log4net.dll

Sends logging events as connectionless UDP datagrams to a remote host or a multicast group using an UdpClient.

public class UdpAppender : AppenderSkeleton, IBulkAppender, IAppender, IOptionHandler, IFlushable

Inheritance

object

AppenderSkeleton

UdpAppender

Implements

IBulkAppender

IAppender

IOptionHandler

IFlushable

Derived

RemoteSyslogAppender

Inherited Members

AppenderSkeleton.Threshold

AppenderSkeleton.ErrorHandler

AppenderSkeleton.FilterHead

AppenderSkeleton.Layout

AppenderSkeleton.Name

AppenderSkeleton.Close()

AppenderSkeleton.DoAppend(LoggingEvent)

AppenderSkeleton.DoAppend(LoggingEvent[])

AppenderSkeleton.FilterEvent(LoggingEvent)

AppenderSkeleton.AddFilter(IFilter)

AppenderSkeleton.ClearFilters()

AppenderSkeleton.IsAsSevereAsThreshold(Level)

AppenderSkeleton.Append(LoggingEvent[])

AppenderSkeleton.Append(IEnumerable<LoggingEvent>)

AppenderSkeleton.PreAppendCheck()

AppenderSkeleton.RenderLoggingEvent(LoggingEvent)

AppenderSkeleton.RenderLoggingEvent(TextWriter, LoggingEvent)

AppenderSkeleton.Flush(int)

AppenderSkeleton.LockObj

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Examples

This example shows how to log receive logging events that are sent on IP address 244.0.0.1 and port 8080 to the console. The event is encoded in the packet as a unicode string and it is decoded as such.

IPEndPoint remoteEndPoint = new IPEndPoint(IPAddress.Any, 0);
UdpClient udpClient;
byte[] buffer;
string loggingEvent;

try 
{
    udpClient = new UdpClient(8080);

    while(true) 
    {
        buffer = udpClient.Receive(ref remoteEndPoint);
        loggingEvent = System.Text.Encoding.Unicode.GetString(buffer);
        Console.WriteLine(loggingEvent);
    }
} 
catch(Exception e) 
{
    Console.WriteLine(e.ToString());
}

Dim remoteEndPoint as IPEndPoint
Dim udpClient as UdpClient
Dim buffer as Byte()
Dim loggingEvent as String

Try 
    remoteEndPoint = new IPEndPoint(IPAddress.Any, 0)
    udpClient = new UdpClient(8080)

    While True
        buffer = udpClient.Receive(ByRef remoteEndPoint)
        loggingEvent = System.Text.Encoding.Unicode.GetString(buffer)
        Console.WriteLine(loggingEvent)
    Wend
Catch e As Exception
    Console.WriteLine(e.ToString())
End Try

An example configuration section to log information using this appender to the IP 224.0.0.1 on port 8080:

<appender name="UdpAppender" type="log4net.Appender.UdpAppender">
    <remoteAddress value="224.0.0.1" />
    <remotePort value="8080" />
    <layout type="log4net.Layout.PatternLayout" value="%-5level %logger [%ndc] - %message%newline" />
</appender>

Remarks

UDP guarantees neither that messages arrive, nor that they arrive in the correct order.

To view the logging results, a custom application can be developed that listens for logging events.

When decoding events send via this appender remember to use the same encoding to decode the events as was used to send the events. See the Encoding property to specify the encoding to use.

Constructors

UdpAppender()

Initializes a new instance of the UdpAppender class.

public UdpAppender()

Remarks

The default constructor initializes all fields to their default values.

Properties

Client

Gets or sets the underlying UdpClient.

protected UdpClient? Client { get; set; }

Property Value

UdpClient

The underlying UdpClient.

Remarks

UdpAppender creates a UdpClient to send logging events over a network. Classes deriving from UdpAppender can use this property to get or set this UdpClient. Use the underlying UdpClient returned from Client if you require access beyond that which UdpAppender provides.

Encoding

Gets or sets Encoding used to write the packets.

public Encoding Encoding { get; set; }

Property Value

Encoding

The Encoding used to write the packets.

Remarks

The Encoding used to write the packets.

LocalPort

Gets or sets the TCP port number from which the underlying UdpClient will communicate.

public int LocalPort { get; set; }

Property Value

int

An integer value in the range MinPort to MaxPort indicating the TCP port number from which the underlying UdpClient will communicate.

Remarks

The underlying UdpClient will bind to this port for sending messages.

Setting the value to 0 (the default) will cause the udp client not to bind to a local port.

Exceptions

ArgumentOutOfRangeException

The value specified is less than MinPort or greater than MaxPort.

MaxDatagramSize

Gets or sets the largest datagram this appender sends, in bytes.

public int MaxDatagramSize { get; set; }

Property Value

int

A value from 512 to 65507, the maximum UDP payload of an IPv4 packet. Default 65507.

Remarks

The socket rejects a larger datagram, so a longer event is truncated to fit instead of lost. Lower the value to match a receiver that accepts less. IPv6 would carry 20 bytes more, which is not worth a second limit.

Exceptions

ArgumentOutOfRangeException

The value specified is outside 512 to 65507.

RemoteAddress

Gets or sets the IP address of the remote host or multicast group to which the underlying UdpClient should sent the logging event.

public IPAddress? RemoteAddress { get; set; }

Property Value

IPAddress

The IP address of the remote host or multicast group to which the logging event will be sent.

Remarks

Multicast addresses are identified by IP class D addresses (in the range 224.0.0.0 to 239.255.255.255). Multicast packets can pass across different networks through routers, so it is possible to use multicasts in an Internet scenario as long as your network provider supports multicasting.

Hosts that want to receive particular multicast messages must register their interest by joining the multicast group. Multicast messages are not sent to networks where no host has joined the multicast group. Class D IP addresses are used for multicast groups, to differentiate them from normal host addresses, allowing nodes to easily detect if a message is of interest.

Static multicast addresses that are needed globally are assigned by IANA. A few examples are listed in the table below:

IP Address	Description
224.0.0.1	Sends a message to all system on the subnet.
224.0.0.2	Sends a message to all routers on the subnet.
224.0.0.12	The DHCP server answers messages on the IP address 224.0.0.12, but only on a subnet.

A complete list of actually reserved multicast addresses and their owners in the ranges defined by RFC 3171 can be found at the IANA web site.

The address range 239.0.0.0 to 239.255.255.255 is reserved for administrative scope-relative addresses. These addresses can be reused with other local groups. Routers are typically configured with filters to prevent multicast traffic in this range from flowing outside of the local network.

RemoteEndPoint

Gets or sets the cached remote endpoint to which the logging events should be sent.

protected IPEndPoint? RemoteEndPoint { get; set; }

Property Value

IPEndPoint

Remarks

The ActivateOptions() method will initialize the remote endpoint with the values of the RemoteAddress and RemotePort properties.

RemotePort

Gets or sets the TCP port number of the remote host or multicast group to which the underlying UdpClient should sent the logging event.

public int RemotePort { get; set; }

Property Value

int

An integer value in the range MinPort to MaxPort indicating the TCP port number of the remote host or multicast group to which the logging event will be sent.

Remarks

The underlying UdpClient will send messages to this TCP port number on the remote host or multicast group.

Exceptions

ArgumentOutOfRangeException

The value specified is less than MinPort or greater than MaxPort.

RequiresLayout

This appender requires a log4net.Layout to be set.

protected override bool RequiresLayout { get; }

Property Value

bool

Methods

ActivateOptions()

Initialize the appender based on the options set.

public override void ActivateOptions()

Remarks

This is part of the IOptionHandler delayed object activation scheme. The ActivateOptions() method must be called on this object after the configuration properties have been set. Until ActivateOptions() is called this object is in an undefined state and must not be used.

If any of the configuration properties are modified then ActivateOptions() must be called again.

The appender will be ignored if no RemoteAddress was specified or an invalid remote or local TCP port number was specified.

Exceptions

ArgumentNullException

The required property RemoteAddress was not specified.

ArgumentOutOfRangeException

The TCP port number assigned to LocalPort or RemotePort is less than MinPort or greater than MaxPort.

Append(LoggingEvent)

This method is called by the DoAppend(LoggingEvent) method.

protected override void Append(LoggingEvent loggingEvent)

Parameters

loggingEvent LoggingEvent

The event to log.

Remarks

Sends the event using an UDP datagram.

Exceptions are passed to the ErrorHandler.

InitializeClientConnection()

Initializes the underlying UdpClient connection.

protected virtual void InitializeClientConnection()

Remarks

The underlying UdpClient is initialized and binds to the port number from which you intend to communicate.

Exceptions are passed to the ErrorHandler.

OnClose()

Closes the UDP connection and releases all resources associated with this UdpAppender instance.

protected override void OnClose()

Remarks

Disables the underlying UdpClient and releases all managed and unmanaged resources associated with the UdpAppender.