Skip to content

Latest commit

 

History

History
232 lines (188 loc) · 12.3 KB

create-custom-listeners-auditing-diagnostics-traces.md

File metadata and controls

232 lines (188 loc) · 12.3 KB
Raw
title description ms.date ms.topic author ms.author search.audienceType ms.custom
Create custom listeners for auditing, diagnostics and traces | MicrosoftDocs
Learn to create custom listeners to write audit, diagnostics, and trace logs in Unified Service Desk.
06/27/2024
article
gandhamm
mgandham
customizer
developer
evergreen

Create custom listeners for auditing, diagnostics and traces

A listener lets you target the log output to files, the event log, or other sources. Until the previous version of [!INCLUDEpn_unified_service_desk], you could only use the standard listeners to write auditing, diagnostics, and trace logs in [!INCLUDEpn_unified_service_desk].

With [!INCLUDEpn_unified_service_desk_20], you can configure custom listeners to log auditing, diagnostics, and tracing data. Specify a custom listener by using the new type of hosted control called Listener Hosted Control that contains a reference to the assembly (.dll file) containing your custom listener code.

What does creating custom listeners involve?

Creating and using custom listeners in [!INCLUDEpn_unified_service_desk] involves developers and administrators working together. The following table outlines the process.

Step Who does it? Task See here
1 Developer Write code for your custom listener. Define your custom listener for Unified Service Desk
2 Developer Compress assembly into a .zip file to create a customization file for Unified Service Desk. Prepare for distribution of your sample code
3 Developer/Administrator Create instances of the Listener Hosted Control to use the custom listener code. Create Listener Hosted Control instances to use your custom listener code
4 Administrator Create instances of Auditing & Diagnostics Settings record to configure your auditing, diagnostics, or trace logging information. Configure auditing and diagnostics in Unified Service Desk
5 Administrator Create Customization Files, and attach the .zip file created by the developer in step #2. Distribute custom hosted controls using Customization Files
6 Administrator Attach the Customization Files record to the appropriate instance of the Configuration entity. Associate auditing and diagnostics with a configuration

Define your custom listener for Unified Service Desk

You can combine the code for your custom listener for auditing, diagnostics, and trace logging into a single assembly or different assemblies. The class containing your listener code must be derived from:

Note

Make a note of the namespace and class names in your listener code. You will need these to create instances of Listener Hosted Control to refer to your custom code.

Custom Listener for Auditing Logs

The following sample code demonstrates how to create a custom listener that writes audit data to USDAudit.log file in the C:\USDLogs folder.

using Microsoft.Uii.AifServices;  
using Microsoft.Uii.Common.Entities;  
using Microsoft.Uii.Common.Logging;  
using System;  
using System.Collections.Generic;  
using System.Configuration;  
using System.IO;  
using System.Linq;  
using System.Text;  
using System.Threading.Tasks;  
  
namespace SampleCustomUSDListener  
{  
    public class CustomUSDAuditListener : IAuditService  
    {  
        public void SaveAudit(IEnumerable<Microsoft.Uii.Common.Entities.LogData> logCache)  
        {  
            LogToFile(logCache);  
        }  
  
        private void LogToFile(IEnumerable<LogData> logCache)  
        {  
            string filename = Path.GetPathRoot(Environment.SystemDirectory) + "USDLogs\\USDAudit.log";  
            foreach (var item in logCache)  
            {  
                try  
                {  
                    File.AppendAllText(filename, item.GetLogData());  
                }  
                catch (Exception ex)  
                {   
                    Logging.Error("USD",ex.StackTrace);   
                }  
            }  
        }  
    }  
}

Custom Listener for Diagnostic Logs

The following sample code demonstrates how to create a custom listener that writes diagnostic data to the USDDiagnostics.log file in the C:\USDLogs folder.

using Microsoft.Uii.Common.Logging;  
using Microsoft.Uii.Common.Entities;  
using System;  
using System.Collections.Generic;  
using System.Linq;  
using System.Text;  
using System.IO;  
using System.Configuration;  
using System.Threading.Tasks;  
  
namespace SampleCustomUSDListener  
{  
    class CustomUSDDiagnosticListener : ILogging  
    {  
        string filename = Path.GetPathRoot(Environment.SystemDirectory) + "USDLogs\\USDDiagnostics.log";  
        public void Error(string applicationName, string message, string advanced)  
        {  
            File.AppendAllText(filename, "\nError is logged\n" + "\nApplication Name:\n" + applicationName + "\nMessage:\n" + message + "\nAdvanced:\n" + advanced);  
        }  
  
        public void Information(string applicationName, string message)  
        {  
            File.AppendAllText(filename, "\nInformation is logged\n" + "\nApplication Name:\n" + applicationName + "\nMessage:\n" + message);  
        }  
  
        public void Initialize(string name, System.Collections.Specialized.NameValueCollection configValue)  
        {  
            //Not needed  
        }  
  
        public bool ShowErrors  
        {  
            get  
            {  
                throw new NotImplementedException();  
            }  
            set  
            {  
                throw new NotImplementedException();  
            }  
        }  
  
        public string Tag  
        {  
            get  
            {  
                throw new NotImplementedException();  
            }  
            set  
            {  
                throw new NotImplementedException();  
            }  
        }  
  
        public void Trace(string applicationName, string message)  
        {  
            File.AppendAllText(filename, "\nVerbose is logged\n" + "\nApplication Name:\n" + applicationName + "\nMessage:\n" + message);  
        }  
  
        public void Warn(string applicationName, string message)  
        {  
            File.AppendAllText(filename, "\nWarning is logged\n" + "\nApplication Name:\n" + applicationName + "\nMessage:\n" + message);  
        }  
    }  
}

Custom Listener for Trace Logs

The following sample code demonstrates how to create a custom listener that writes trace data to the USDTraces.log file in the C:\USDLogs folder.

using System;  
using System.Diagnostics;  
using System.IO;  
  
namespace SampleCustomUSDListener  
{  
    class CustomUSDTraceListener : TraceListener  
    {  
        string filename = Path.GetPathRoot(Environment.SystemDirectory) + "USDLogs\\USDTraces.log";  
        public override void Write(string message)  
        {  
            File.AppendAllText(filename, message);  
        }  
  
        public override void WriteLine(string message)  
        {  
            File.AppendAllText(filename, message);  
        }  
    }  
}

Prepare for distribution of your sample code

After you have built your custom listener code into an assembly (.dll) file, work with your administrator to distribute your code to the client computers so that they can consume your custom listeners. To distribute your custom files, compress the files along with a [Content_Types].xml file into a .zip file and provide the .zip file to you administrator to attach it to a Customization Files record. See Next steps for administrator.

The [Content_Types].xml file provides MIME type information of the file type extensions that are included in the .zip file. Typically, the file types are: .config, .dll, .exe, and .xml. However, you can include any file type that’s supported on Windows in the [Content_Types].xml file and in the zip file.

Here is a sample [Content_Types].xml file with file types listed that are typically used for customizing [!INCLUDEpn_unified_service_desk]:

<?xml version="1.0" encoding="utf-8"?>  
<Types xmlns="https://schemas.openxmlformats.org/package/2006/content-types">  
  <Default Extension="config" ContentType="application/octet-stream" />  
  <Default Extension="dll" ContentType="application/octet-stream" />  
  <Default Extension="exe" ContentType="application/octet-stream" />  
  <Default Extension="xml" ContentType="application/octet-stream" />  
</Types>

Create Listener Hosted Control instances to use your custom listener code

The new Listener hosted Control in [!INCLUDEpn_unified_service_desk] lets you reference and use your custom listener code for logging data as per your code. The Assembly Info area in the new hosted control screen lets you specify the details about your assembly that you want to be referred to by the Listener Hosted Control. Specify your assembly (.dll) name in the Assembly URI field, and <AssemblyName>.<ClassName> in the Assembly Type field. The <ClassName> should be the class that contains your code.

For example, if we consider the sample code for custom listeners earlier in this topic and assuming that all the sample codes are compiled into a single assembly called SampleCustomUSDListener.dll, you must create a listener hosted control record each for audit, diagnostic, and trace with the following values in the Assembly URI and Assembly Type fields.

Audit Diagnostic Trace
- Assembly URI: SampleCustomUSDListener
- Assembly Type: SampleCustomUSDListener.CustomUSDAuditListener		 - Assembly URI: SampleCustomUSDListener
- Assembly Type: SampleCustomUSDListener.CustomUSDDiagnosticListener		 - Assembly URI: SampleCustomUSDListener
- Assembly Type: SampleCustomUSDListener.CustomUSDTraceListener

Save the listener hosted control records.

Next steps for administrator

As an administrator, you should now do the following two things to use the custom listener code in your organization:

See also

Extend Unified Service Desk

[!INCLUDEfooter-include]