ListDTO.cs

<source lang="csharp"> /*

* Copyright CallFire.com 2009
* 
* All Rights Reserved.
*/

/*

* Using statements import needed packages and make
* them available for use within this class. Separating
* the using statements by type makes them more human
* readable.
*/

1. region Using

//System using System.Text;

1. endregion

namespace CallFireServices.ListService.Model {

   /// <summary>
   /// Data Transfer Object (DTO) for storing list information.
   /// 
   /// The purpose of the class is to encapsulate the data associated with a
   /// CallFire List. It contains the id and name of the list. Separating this data
   /// into a Model object provides greater clarity and code reuse. Using this DTO
   /// object for operations instead of ids directly, can help prevent API contract
   /// changes should the underlying web services change such as using names as 
   /// unique identifiers.
   /// </summary>
   public class ListDTO
   {
       /*
        * Using region blocks helps organize code.
        * Defining Members, Constructors, Methods, and Properties
        * is a good best practice to follow.
        */

       #region Members

       /// <summary>
       /// List id.
       /// </summary>
       private long listId;

       /// <summary>
       /// List name.
       /// </summary>
       private string listName;

       #endregion 

       #region Constructors

       /// <summary>
       /// Default constructor with default values.
       /// 
       /// This constructor assigns the id to zero which indicates that it
       /// hasn't been created yet on the server. The name value is assigned
       /// to an empty string to prevent null pointer errors. This particular
       /// constructor leverages the specific constructor to assign the values
       /// to the member variables.
       /// </summary>
       public ListDTO() : this(0, string.Empty)
       {
       }

       /// <summary>
       /// Specific constructor with given values.
       /// 
       /// Assigns given values to the corresponding member variables.
       /// </summary>
       /// <param name="id">list id</param>
       /// <param name="name">list name</param>
       public ListDTO(long id, string name)
       {
           //initialize members
           this.listId = id;
           this.listName = name;
       }

       #endregion

       #region Methods

       /// <summary>
       /// Override default ToString().
       /// 
       /// This method is overriden so that it will display
       /// formatted text when included in logging statements or is
       /// rendered in a User Interface (UI). A StringBuilder object
       /// is used to provide more efficient string concatenation.
       /// </summary>
       /// <returns></returns>
       public override string ToString()
       {
           StringBuilder sb = new StringBuilder();
           sb.Append("\nListDTO: \n");
           sb.Append("Id: ");
           sb.Append(this.Id);
           sb.Append("\n");
           sb.Append("Name: ");
           sb.Append(this.Name);

           return sb.ToString();
       }

       #endregion

       #region Properties

       /// <summary>
       /// List id.
       /// 
       /// The list id is exposed as a C# property which follows
       /// standard C# programming best practices.
       /// </summary>
       public long Id
       {
           get
           {
               return this.listId;
           }

           set
           {
               this.listId = value;
           }
       }

       /// <summary>
       /// List name.
       /// 
       /// The list name is exposed as a C# property which follows
       /// standard C# programming best practices.
       /// </summary>
       public string Name
       {
           get
           {
               return this.listName;
           }

           set
           {
               this.listName = value;
           }
       }

       #endregion
   }

}

</source>