src/Appender/UdpAppender.cs

#region Apache License
//
// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

using System;
using System.Globalization;
using System.Net;
using System.Net.Sockets;
using System.Text;

using log4net.Layout;
using log4net.Core;
using log4net.Util;

namespace log4net.Appender
{
	/// <summary>
	/// Sends logging events as connectionless UDP datagrams to a remote host or a
	/// multicast group using an <see cref="UdpClient" />.
	/// </summary>
	/// <remarks>
	/// <para>
	/// UDP guarantees neither that messages arrive, nor that they arrive in the correct order.
	/// </para>
	/// <para>
	/// To view the logging results, a custom application can be developed that listens for logging
	/// events.
	/// </para>
	/// <para>
	/// 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 <see cref="Encoding"/>
	/// property to specify the encoding to use.
	/// </para>
	/// </remarks>
	/// <example>
	/// 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.
	/// <code lang="C#">
	/// 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());
	/// }
	/// </code>
	/// <code lang="Visual Basic">
	/// 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
	/// </code>
	/// <para>
	/// An example configuration section to log information using this appender to the
	/// IP 224.0.0.1 on port 8080:
	/// </para>
	/// <code lang="XML" escaped="true">
	/// <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>
	/// </code>
	/// </example>
	/// <author>Gert Driesen</author>
	/// <author>Nicko Cadell</author>
	public class UdpAppender : AppenderSkeleton
	{
		#region Public Instance Constructors

		/// <summary>
		/// Initializes a new instance of the <see cref="UdpAppender" /> class.
		/// </summary>
		/// <remarks>
		/// The default constructor initializes all fields to their default values.
		/// </remarks>
		public UdpAppender()
		{
		}

		#endregion Public Instance Constructors

		#region Public Instance Properties

		/// <summary>
		/// Gets or sets the IP address of the remote host or multicast group to which
		/// the underlying <see cref="UdpClient" /> should sent the logging event.
		/// </summary>
		/// <value>
		/// The IP address of the remote host or multicast group to which the logging event
		/// will be sent.
		/// </value>
		/// <remarks>
		/// <para>
		/// Multicast addresses are identified by IP class <b>D</b> 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.
		/// </para>
		/// <para>
		/// 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 <b>D</b> 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.
		/// </para>
		/// <para>
		/// Static multicast addresses that are needed globally are assigned by IANA.  A few examples are listed in the table below:
		/// </para>
		/// <para>
		/// <list type="table">
		///     <listheader>
		///         <term>IP Address</term>
		///         <description>Description</description>
		///     </listheader>
		///     <item>
		///         <term>224.0.0.1</term>
		///         <description>
		///             <para>
		///             Sends a message to all system on the subnet.
		///             </para>
		///         </description>
		///     </item>
		///     <item>
		///         <term>224.0.0.2</term>
		///         <description>
		///             <para>
		///             Sends a message to all routers on the subnet.
		///             </para>
		///         </description>
		///     </item>
		///     <item>
		///         <term>224.0.0.12</term>
		///         <description>
		///             <para>
		///             The DHCP server answers messages on the IP address 224.0.0.12, but only on a subnet.
		///             </para>
		///         </description>
		///     </item>
		/// </list>
		/// </para>
		/// <para>
		/// A complete list of actually reserved multicast addresses and their owners in the ranges
		/// defined by RFC 3171 can be found at the <A href="http://www.iana.org/assignments/multicast-addresses">IANA web site</A>.
		/// </para>
		/// <para>
		/// 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.
		/// </para>
		/// </remarks>
		public IPAddress RemoteAddress
		{
			get { return m_remoteAddress; }
			set { m_remoteAddress = value; }
		}

		/// <summary>
		/// Gets or sets the TCP port number of the remote host or multicast group to which
		/// the underlying <see cref="UdpClient" /> should sent the logging event.
		/// </summary>
		/// <value>
		/// An integer value in the range <see cref="IPEndPoint.MinPort" /> to <see cref="IPEndPoint.MaxPort" />
		/// indicating the TCP port number of the remote host or multicast group to which the logging event
		/// will be sent.
		/// </value>
		/// <remarks>
		/// The underlying <see cref="UdpClient" /> will send messages to this TCP port number
		/// on the remote host or multicast group.
		/// </remarks>
		/// <exception cref="ArgumentOutOfRangeException">The value specified is less than <see cref="IPEndPoint.MinPort" /> or greater than <see cref="IPEndPoint.MaxPort" />.</exception>
		public int RemotePort
		{
			get { return m_remotePort; }
			set
			{
				if (value < IPEndPoint.MinPort || value > IPEndPoint.MaxPort)
				{
					throw log4net.Util.SystemInfo.CreateArgumentOutOfRangeException("value", (object)value,
						"The value specified is less than " +
						IPEndPoint.MinPort.ToString(NumberFormatInfo.InvariantInfo) +
						" or greater than " +
						IPEndPoint.MaxPort.ToString(NumberFormatInfo.InvariantInfo) + ".");
				}
				else
				{
					m_remotePort = value;
				}
			}
		}

		/// <summary>
		/// Gets or sets the TCP port number from which the underlying <see cref="UdpClient" /> will communicate.
		/// </summary>
		/// <value>
		/// An integer value in the range <see cref="IPEndPoint.MinPort" /> to <see cref="IPEndPoint.MaxPort" />
		/// indicating the TCP port number from which the underlying <see cref="UdpClient" /> will communicate.
		/// </value>
		/// <remarks>
		/// <para>
		/// The underlying <see cref="UdpClient" /> will bind to this port for sending messages.
		/// </para>
		/// <para>
		/// Setting the value to 0 (the default) will cause the udp client not to bind to
		/// a local port.
		/// </para>
		/// </remarks>
		/// <exception cref="ArgumentOutOfRangeException">The value specified is less than <see cref="IPEndPoint.MinPort" /> or greater than <see cref="IPEndPoint.MaxPort" />.</exception>
		public int LocalPort
		{
			get { return m_localPort; }
			set
			{
				if (value != 0 && (value < IPEndPoint.MinPort || value > IPEndPoint.MaxPort))
				{
					throw log4net.Util.SystemInfo.CreateArgumentOutOfRangeException("value", (object)value,
						"The value specified is less than " +
						IPEndPoint.MinPort.ToString(NumberFormatInfo.InvariantInfo) +
						" or greater than " +
						IPEndPoint.MaxPort.ToString(NumberFormatInfo.InvariantInfo) + ".");
				}
				else
				{
					m_localPort = value;
				}
			}
		}

		/// <summary>
		/// Gets or sets <see cref="Encoding"/> used to write the packets.
		/// </summary>
		/// <value>
		/// The <see cref="Encoding"/> used to write the packets.
		/// </value>
		/// <remarks>
		/// <para>
		/// The <see cref="Encoding"/> used to write the packets.
		/// </para>
		/// </remarks>
		public Encoding Encoding
		{
			get { return m_encoding; }
			set { m_encoding = value; }
		}

		#endregion Public Instance Properties

		#region Protected Instance Properties

		/// <summary>
		/// Gets or sets the underlying <see cref="UdpClient" />.
		/// </summary>
		/// <value>
		/// The underlying <see cref="UdpClient" />.
		/// </value>
		/// <remarks>
		/// <see cref="UdpAppender" /> creates a <see cref="UdpClient" /> to send logging events
		/// over a network.  Classes deriving from <see cref="UdpAppender" /> can use this
		/// property to get or set this <see cref="UdpClient" />.  Use the underlying <see cref="UdpClient" />
		/// returned from <see cref="Client" /> if you require access beyond that which
		/// <see cref="UdpAppender" /> provides.
		/// </remarks>
		protected UdpClient Client
		{
			get { return this.m_client; }
			set { this.m_client = value; }
		}

		/// <summary>
		/// Gets or sets the cached remote endpoint to which the logging events should be sent.
		/// </summary>
		/// <value>
		/// The cached remote endpoint to which the logging events will be sent.
		/// </value>
		/// <remarks>
		/// The <see cref="ActivateOptions" /> method will initialize the remote endpoint
		/// with the values of the <see cref="RemoteAddress" /> and <see cref="RemotePort"/>
		/// properties.
		/// </remarks>
		protected IPEndPoint RemoteEndPoint
		{
			get { return this.m_remoteEndPoint; }
			set { this.m_remoteEndPoint = value; }
		}

		#endregion Protected Instance Properties

		#region Implementation of IOptionHandler

		/// <summary>
		/// Initialize the appender based on the options set.
		/// </summary>
		/// <remarks>
		/// <para>
		/// This is part of the <see cref="IOptionHandler"/> delayed object
		/// activation scheme. The <see cref="ActivateOptions"/> method must
		/// be called on this object after the configuration properties have
		/// been set. Until <see cref="ActivateOptions"/> is called this
		/// object is in an undefined state and must not be used.
		/// </para>
		/// <para>
		/// If any of the configuration properties are modified then
		/// <see cref="ActivateOptions"/> must be called again.
		/// </para>
		/// <para>
		/// The appender will be ignored if no <see cref="RemoteAddress" /> was specified or
		/// an invalid remote or local TCP port number was specified.
		/// </para>
		/// </remarks>
		/// <exception cref="ArgumentNullException">The required property <see cref="RemoteAddress" /> was not specified.</exception>
		/// <exception cref="ArgumentOutOfRangeException">The TCP port number assigned to <see cref="LocalPort" /> or <see cref="RemotePort" /> is less than <see cref="IPEndPoint.MinPort" /> or greater than <see cref="IPEndPoint.MaxPort" />.</exception>
		public override void ActivateOptions()
		{
			base.ActivateOptions();

			if (this.RemoteAddress == null)
			{
				throw new ArgumentNullException("The required property 'Address' was not specified.");
			}
			else if (this.RemotePort < IPEndPoint.MinPort || this.RemotePort > IPEndPoint.MaxPort)
			{
				throw log4net.Util.SystemInfo.CreateArgumentOutOfRangeException("this.RemotePort", (object)this.RemotePort,
					"The RemotePort is less than " +
					IPEndPoint.MinPort.ToString(NumberFormatInfo.InvariantInfo) +
					" or greater than " +
					IPEndPoint.MaxPort.ToString(NumberFormatInfo.InvariantInfo) + ".");
			}
			else if (this.LocalPort != 0 && (this.LocalPort < IPEndPoint.MinPort || this.LocalPort > IPEndPoint.MaxPort))
			{
				throw log4net.Util.SystemInfo.CreateArgumentOutOfRangeException("this.LocalPort", (object)this.LocalPort,
					"The LocalPort is less than " +
					IPEndPoint.MinPort.ToString(NumberFormatInfo.InvariantInfo) +
					" or greater than " +
					IPEndPoint.MaxPort.ToString(NumberFormatInfo.InvariantInfo) + ".");
			}
			else
			{
				this.RemoteEndPoint = new IPEndPoint(this.RemoteAddress, this.RemotePort);
				this.InitializeClientConnection();
			}
		}

		#endregion

		#region Override implementation of AppenderSkeleton

		/// <summary>
		/// This method is called by the <see cref="M:AppenderSkeleton.DoAppend(LoggingEvent)"/> method.
		/// </summary>
		/// <param name="loggingEvent">The event to log.</param>
		/// <remarks>
		/// <para>
		/// Sends the event using an UDP datagram.
		/// </para>
		/// <para>
		/// Exceptions are passed to the <see cref="AppenderSkeleton.ErrorHandler"/>.
		/// </para>
		/// </remarks>
		protected override void Append(LoggingEvent loggingEvent)
		{
			try
			{
				Byte [] buffer = m_encoding.GetBytes(RenderLoggingEvent(loggingEvent).ToCharArray());
#if NETSTANDARD1_3
				Client.SendAsync(buffer, buffer.Length, RemoteEndPoint).Wait();
#else
				this.Client.Send(buffer, buffer.Length, this.RemoteEndPoint);
#endif
			}
			catch (Exception ex)
			{
				ErrorHandler.Error(
					"Unable to send logging event to remote host " +
					this.RemoteAddress.ToString() +
					" on port " +
					this.RemotePort + ".",
					ex,
					ErrorCode.WriteFailure);
			}
		}

		/// <summary>
		/// This appender requires a <see cref="Layout"/> to be set.
		/// </summary>
		/// <value><c>true</c></value>
		/// <remarks>
		/// <para>
		/// This appender requires a <see cref="Layout"/> to be set.
		/// </para>
		/// </remarks>
		override protected bool RequiresLayout
		{
			get { return true; }
		}

		/// <summary>
		/// Closes the UDP connection and releases all resources associated with
		/// this <see cref="UdpAppender" /> instance.
		/// </summary>
		/// <remarks>
		/// <para>
		/// Disables the underlying <see cref="UdpClient" /> and releases all managed
		/// and unmanaged resources associated with the <see cref="UdpAppender" />.
		/// </para>
		/// </remarks>
		override protected void OnClose()
		{
			base.OnClose();

			if (this.Client != null)
			{
				this.Client.Close();
				this.Client = null;
			}
		}

		#endregion Override implementation of AppenderSkeleton

		#region Protected Instance Methods

		/// <summary>
		/// Initializes the underlying  <see cref="UdpClient" /> connection.
		/// </summary>
		/// <remarks>
		/// <para>
		/// The underlying <see cref="UdpClient"/> is initialized and binds to the
		/// port number from which you intend to communicate.
		/// </para>
		/// <para>
		/// Exceptions are passed to the <see cref="AppenderSkeleton.ErrorHandler"/>.
		/// </para>
		/// </remarks>
		protected virtual void InitializeClientConnection()
		{
			try
			{
				if (this.LocalPort == 0)
				{
#if NETCF || NET_1_0 || SSCLI_1_0 || CLI_1_0
					this.Client = new UdpClient();
#else
					this.Client = new UdpClient(RemoteAddress.AddressFamily);
#endif
				}
				else
				{
#if NETCF || NET_1_0 || SSCLI_1_0 || CLI_1_0
					this.Client = new UdpClient(this.LocalPort);
#else
					this.Client = new UdpClient(this.LocalPort, RemoteAddress.AddressFamily);
#endif
				}
			}
			catch (Exception ex)
			{
				ErrorHandler.Error(
					"Could not initialize the UdpClient connection on port " +
					this.LocalPort.ToString(NumberFormatInfo.InvariantInfo) + ".",
					ex,
					ErrorCode.GenericFailure);

				this.Client = null;
			}
		}

		#endregion Protected Instance Methods

		#region Private Instance Fields

		/// <summary>
		/// The IP address of the remote host or multicast group to which
		/// the logging event will be sent.
		/// </summary>
		private IPAddress m_remoteAddress;

		/// <summary>
		/// The TCP port number of the remote host or multicast group to
		/// which the logging event will be sent.
		/// </summary>
		private int m_remotePort;

		/// <summary>
		/// The cached remote endpoint to which the logging events will be sent.
		/// </summary>
		private IPEndPoint m_remoteEndPoint;

		/// <summary>
		/// The TCP port number from which the <see cref="UdpClient" /> will communicate.
		/// </summary>
		private int m_localPort;

		/// <summary>
		/// The <see cref="UdpClient" /> instance that will be used for sending the
		/// logging events.
		/// </summary>
		private UdpClient m_client;

		/// <summary>
		/// The encoding to use for the packet.
		/// </summary>
#if NETSTANDARD1_3
		private Encoding m_encoding = Encoding.Unicode;
#else
		private Encoding m_encoding = Encoding.Default;
#endif

		#endregion Private Instance Fields
	}
}