Technical Guidelines for Package Developers

This topic provides technical guidelines for developing packages in Visual Studio.

Sample files are provided below.

To learn how to package a DLL to create a .nuget package, see Use the AS Package Generator.

Do not use common names such as Direct and System within any namespace.

Application Attributes

The following code must be added to the AssemblyInfo.cs class file:

[assembly: DirectAssembly]

Create a Static Function

When creating a static function, the following attributes must be defined:

DirectDom: The display name of the function in Automation Studio
MethodDescription: The description of the function to display in Automation Studio
DirectDomMethod: (Optional) The text to display in the action builder in Automation Studio. Placeholders for the parameters to be specified (if any) are located within {parentheses}. If there are multiple parameters, the placeholders correspond to the parameters in the order in which they are listed in the function declaration.

For example:

[DirectDom("My Static Class")]
    public static class MyStaticClass
    {
        [DirectDom("Check if online"), MethodDescription("Test internet connect to see if connected to a network")]
        public static bool IsOnline()
        {
            bool result = false;

            // logic

            return result;
        }
    }

Create a Class (Complex Type)

When creating a class to define a complex type in Automation Studio:

The class must have an attribute DirectDom. The value of this attribute specifies the display name of the complex type in Automation Studio.
The class must inherit from DirectComponentBase.

For example:

namespace NICE.Database_Support_75
{
    [DirectDom("Database Support", "SQL DB", false)]
    public class DBSupport : DirectComponentBase
    {

(The above example is from the file DBSupport.cs.)

In Automation Studio:

Specify a Class Property

When specifying a property of a class to define a property of a complex variable in Automation Studio:

The property must have an attribute DirectDom. The value of this attribute specifies the display name of the property in Automation Studio.
The class must have an attribute MethodDescription. The value of this attribute is displayed as a description of the property in Automation Studio.

For example:

        [DirectDom("User Name"), MethodDescription("The user name for connecting to the database")]
        public string UserName
        {
            get
            {
                return this._Username.TypedValue;
            }
            set
            {
                this._Username.TypedValue = value;
            }
        }

(The above is example is from the file DBSupport.cs.)

In Automation Studio:

The field wrapped by the property must be named with the name of the property but with a prefixed underscore, as in the example below.

[DirectDom("SFTP", "Communication", false)]

public class SFTPConnectionDetails : DirectComponentBase

protected PropertyHolder<string> _Host = new PropertyHolder <string>("Host");

protected PropertyHolder<string> _UserName = new PropertyHolder<string>("UserName");

protected PropertyHolder<string> _Password = new PropertyHolder<string>("Password");

protected PropertyHolder<int> _Port = new PropertyHolder<int>("Port");

#region Properties

[DirectDom("Host")]

[DesignTimeInfo("Host")]

[ReadOnlyProperty]

public string Host

get { return _Host TypedValue; }

set { _Host.TypedValue = value; }

Create an Event

An event consists of multiple parts:

The event handler
The event arguments (if needed)
The event delegate

Specify an Event Handler

When specifying an event handler:

The event handler must have an attribute DirectDom. The value of this attribute specifies the display name of the event in Automation Studio.

For example:

        [DirectDom("Exception")]
        public event DBSupport.DBExceptionEventHandler ExceptionEvent;

(The above is example is from the file DBSupport.cs.)

Specify Event Arguments

When specifying event arguments:

The event arguments must inherit from DirectEventArgs.

For example:

namespace NICE.Database_Support_75
{
    [DirectDom, DirectSealed]
    public class DBExceptionEventArgs : DirectEventArgs
    {
        private string message = string.Empty;

        [DirectDom("Message")]
        public string Message
        {
            get
            {
                return this.message;
            }
        }

        public DBExceptionEventArgs(string message)
        {
            this.message = message;
        }
    }
}

(The above example is from the file DBExceptionEventArgs.cs.)

In Automation Studio:

Specify an Event Delegate

When specifying the event delegate:

The event delegate must receive IDirectComponentBase and the event arguments.

For example:

        [DirectDom]
        public delegate void DBExceptionEventHandler(IDirectComponentBase sender, DBExceptionEventArgs e);

(The above example is from the file DBSupport.cs.)

Create a Method for a Class

When creating a method for a class, the following attributes must be defined:

DirectDom: The display name of the method in Automation Studio
MethodDescription: The description of the method to display in Automation Studio
DirectDomMethod: (Optional) The text to display in the action builder in Automation Studio. Placeholders for the parameters to be specified (if any) are located within {parentheses}. If there are multiple parameters, the placeholders correspond to the parameters in the order in which they are listed in the function declaration.

For example:

[DirectDom("Get String Using Query"), DirectDomMethod("Get string using query {Query}"), MethodDescription("Execute a query to retrieve a single string from the database")]
        public string getStringUsingQuery(string sqlQuery)

(The above example is from the file DBSupport.cs.)

In Automation Studio:

Logging

To add logging capabilities, use the log4net library:

using log4net;

Within the class, create a logArchitect object:

private static readonly ILog logArchitect = LogManager.GetLogger("LibraryObjects");

Use the logArchitect object to write messages to the log:

 catch (Exception ex)
            {
                string errorDetails = "DBSupport.getStringUsingQuery: Error-" + ex.Message;
                this.ErrorDetails = errorDetails;
                this.Status = "Error";
                bool isErrorEnabled = DBSupport.logArchitect.IsErrorEnabled;
                if (isErrorEnabled)
                {
                    DBSupport.logArchitect.ErrorFormat("DBSupport.getStringUsingQuery Error - {0}", ex.Message);
                    ExceptionParams.Set(ex.Message);
                }
                if (this.ExceptionEvent != null)
                {
                    string message = string.Format("DBSupport.getStringUsingQuery Error - {0}", ex.Message);
                    DBExceptionEventArgs e = new DBExceptionEventArgs(message);
                    this.ExceptionEvent(this, e);
                }
            }

(The above example is from the file DBSupport.cs.)

The following log levels are supported:

IsDebugEnabled
IsErrorEnabled
IsWarnEnabled
IsInfoEnabled
IsFatalEnabled

Sample Files

Download the sample files here.

The ZIP file includes the following files:

\DBSupport.cs
\DBExceptionEventArgs.cs
\Properties\AssemblyInfo.cs