Outlook Technologies

Outlook Forms

Languages

Samples

More Outlook Resource Sites

Microsoft Developer Network (MSDN)

FAQs and other general resources

share code 02-Sep-2010 22:23

Looking for help with Outlook programming projects — VSTO, add-ins, VBA, custom Outlook forms, etc.? You′ve come to the right place!

NEW! >> Subscribe to this site via RSS. For more RSS options, see the complete list of feeds on our main news page.

Code level: advanced Code area: Outlook and .NET Printer Friendly Version
Title: C# AddIn: HowTo implement BusinessRules
Description: C# sample AddIn that demonstrates a way how to enforce business rules on outlook items
Date: 27-Aug-2006 06:35
Code level: advanced
Code area: Outlook and .NET
Posted by: Helmut Obertanner
Body: Hello all, this is a sample technique that uses delegates to enforce businessrules on outlook items. The sample was written with VS2005 / Office2003 and has 4 Files. The complete solution could be found on my homepage http://www.x4u.de Create a new Shared Office AddIn "BusinessRules" and paste in the following files: Usage: try to create new contact or modify a contact and see what happens. -------------- Connect.cs ------------------ /* ******************************************************************************************* * This sample demonstrates how to implement business rules within outlook add-ins. * Should be easy to use this technique in all other project-types too. * The idea: * Every business object will have a collection of business rules. * Every business rule is checked by a single method that returns true when the business rule * has been met. * Before the object is saved, we call a Validate method that performs all checks for the * business rules. If one or more rules fails, we inform the user and cancel the save. * * This sample was written with Visual-Studio 2005 and Outlook2007 Beta2 * * (c)2006 H.Obertanner - X4U electronix - flash [at] x4u [dot] de * * In this sample we will monitor the selected contacts in the contact folder (Explorer) * and when an item was displayed. (Inspector) * *******************************************************************************************/ namespace BusinessRules { using System; using Extensibility; using System.Runtime.InteropServices; // Outlook specific using Outlook = Microsoft.Office.Interop.Outlook; using Office = Microsoft.Office.Core; using System.Collections.Generic; /// <summary> /// The object for implementing an Add-in. /// </summary> /// <seealso class='IDTExtensibility2' /> [GuidAttribute("BE0B5581-1579-4E26-AC46-248972BFC4A5"), ProgId("BusinessRules.Connect")] public class Connect : Object, Extensibility.IDTExtensibility2 { #region Internal variables /// <summary> /// The initial Outlook application object that we use in our application. /// </summary> Outlook.Application _Application = null; /// <summary> /// This Variable is the instance object of this AddIn. /// </summary> object _AddInInstance = null; /// <summary> /// We will monitor the _Explorer for selection change events /// </summary> Outlook.ExplorerClass _Explorer = null; /// <summary> /// The Inspectors. /// </summary> Outlook.Inspectors _Inspectors = null; /// <summary> /// A list of ContactItems. /// </summary> List<X4UContactInspector> _X4UInspectors = new List<X4UContactInspector>(); /// <summary> /// This variable holds a reference to the Contact Folder. /// </summary> Outlook.MAPIFolder _ContactFolder = null; /// <summary> /// This holds a collection to all in explorer selected contacts, to force checking of business rules. /// </summary> List<X4UContactItem> _ContactItemsToMonitor = new List<X4UContactItem>(); #endregion #region IExtensibility interface /// <summary> /// Implements the constructor for the Add-in object. /// Place your initialization code within this method. /// </summary> public Connect() { } /// <summary> /// Implements the OnConnection method of the IDTExtensibility2 interface. /// Receives notification that the Add-in is being loaded. /// </summary> /// <param term='application'> /// Root object of the host application. /// </param> /// <param term='connectMode'> /// Describes how the Add-in is being loaded. /// </param> /// <param term='addInInst'> /// Object representing this Add-in. /// </param> /// <seealso class='IDTExtensibility2' /> public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom) { // remember the initial application object. _Application = application as Outlook.Application ; // keep a reference to this AddIn instance in memory. _AddInInstance = addInInst; } /// <summary> /// Implements the OnDisconnection method of the IDTExtensibility2 interface. /// Receives notification that the Add-in is being unloaded. /// </summary> /// <param term='disconnectMode'> /// Describes how the Add-in is being unloaded. /// </param> /// <param term='custom'> /// Array of parameters that are host application specific. /// </param> /// <seealso class='IDTExtensibility2' /> public void OnDisconnection(Extensibility.ext_DisconnectMode disconnectMode, ref System.Array custom) { // release all objects from memory this.ShutDownAddIn(); } /// <summary> /// Implements the OnAddInsUpdate method of the IDTExtensibility2 interface. /// Receives notification that the collection of Add-ins has changed. /// </summary> /// <param term='custom'> /// Array of parameters that are host application specific. /// </param> /// <seealso class='IDTExtensibility2' /> public void OnAddInsUpdate(ref System.Array custom) { } /// <summary> /// Implements the OnStartupComplete method of the IDTExtensibility2 interface. /// Receives notification that the host application has completed loading. /// </summary> /// <param term='custom'> /// Array of parameters that are host application specific. /// </param> /// <seealso class='IDTExtensibility2' /> public void OnStartupComplete(ref System.Array custom) { // Outlook startup is completed, now we start our addin this.InitializeAddIn(); } /// <summary> /// Implements the OnBeginShutdown method of the IDTExtensibility2 interface. /// Receives notification that the host application is being unloaded. /// </summary> /// <param term='custom'> /// Array of parameters that are host application specific. /// </param> /// <seealso class='IDTExtensibility2' /> public void OnBeginShutdown(ref System.Array custom) { } #endregion /// <summary> /// Initializes the add in. /// </summary> private void InitializeAddIn() { // we will monitor all ContactItems for this example _ContactFolder = _Application.Session.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderContacts); _Explorer = _Application.ActiveExplorer() as Outlook.ExplorerClass ; _Explorer.SelectionChange += new Microsoft.Office.Interop.Outlook.ExplorerEvents_10_SelectionChangeEventHandler(_Explorer_SelectionChange); _Explorer.ExplorerEvents_10_Event_Close += new Microsoft.Office.Interop.Outlook.ExplorerEvents_10_CloseEventHandler(_Explorer_ExplorerEvents_10_Event_Close); _Inspectors = _Application.Inspectors; _Inspectors.NewInspector += new Microsoft.Office.Interop.Outlook.InspectorsEvents_NewInspectorEventHandler(_Inspectors_NewInspector); } /// <summary> /// This event is raised when a new inspector was opened. /// </summary> /// <param name="Inspector">The inspector.</param> void _Inspectors_NewInspector(Microsoft.Office.Interop.Outlook.Inspector Inspector) { // check what type of inspector we have Outlook.ContactItem item = Inspector.CurrentItem as Outlook.ContactItem; // do we have an contact item. if (item != null) { X4UContactInspector x4uInspector = new X4UContactInspector(item); x4uInspector.Close += new InspectorCloseDelegate(x4uInspector_Close); _X4UInspectors.Add(x4uInspector); } } /// <summary> /// this event occures when the inspector has been closed. /// </summary> /// <param name="inspectorId"></param> void x4uInspector_Close(Guid inspectorId) { // Release the Inspector from memory. foreach (X4UContactInspector inspector in _X4UInspectors) { if (inspector.Id == inspectorId) _X4UInspectors.Remove(inspector); } } /// <summary> /// This event occures when the explorer has been closed. /// </summary> void _Explorer_ExplorerEvents_10_Event_Close() { // when the explorer has closed, we will terminate our addin. this.ShutDownAddIn(); } /// <summary> /// This event occures when the user has selected some items.... /// </summary> void _Explorer_SelectionChange() { // Clar the list of monitored items _ContactItemsToMonitor.Clear(); // first we well check if we are in the contacts folder. if (_Explorer.CurrentFolder.Equals (_ContactFolder )) { // loop over the selected items and add to monitor collection foreach (object selectedItem in _Explorer.Selection) { // check if we have a contactitem Outlook.ContactItem contact = selectedItem as Outlook.ContactItem; if (contact != null) { // if so, we will monitor this item _ContactItemsToMonitor.Add (new X4UContactItem (contact)); } } } } /// <summary> /// Shuts the down add in. /// </summary> private void ShutDownAddIn() { _ContactFolder = null; _Explorer.SelectionChange -= new Microsoft.Office.Interop.Outlook.ExplorerEvents_10_SelectionChangeEventHandler(_Explorer_SelectionChange); _Explorer.ExplorerEvents_10_Event_Close -= new Microsoft.Office.Interop.Outlook.ExplorerEvents_10_CloseEventHandler(_Explorer_ExplorerEvents_10_Event_Close); _Explorer = null; _Inspectors.NewInspector -= new Microsoft.Office.Interop.Outlook.InspectorsEvents_NewInspectorEventHandler(_Inspectors_NewInspector); _Inspectors = null; } } } ------- end of Connect.cs ----------------- ------- X4UContactItem.cs --------------- using System; using System.Collections.Generic; using System.Text; // Outlook specific using Outlook = Microsoft.Office.Interop.Outlook; using Office = Microsoft.Office.Core; using System.Windows.Forms; namespace BusinessRules { /// <summary> /// The <b>X4UContactItem</b> class is a wrapper for an outlook contactitem. /// </summary> public class X4UContactItem { #region events /// <summary> /// The <b>Open</b> event is raised when the contactItem was displayed. /// </summary> public event EventHandler Open; #endregion #region contact variables /// <summary> /// The internal list of BusinessRules /// </summary> List<X4UBusinessRule> _BusinessRules = new List<X4UBusinessRule>(); /// <summary> /// The <b>Outlook ContactItem</b> that we will monitor here. /// </summary> Outlook.ContactItem _Item = null; #endregion /// <summary> /// Initializes a new instance of the <see cref="T:X4UContactItem"/> class. /// </summary> /// <param name="contactItem">The outlook contact item.</param> public X4UContactItem(Outlook.ContactItem contactItem) { // remember the Item that we want to monitor _Item = contactItem as Outlook.ContactItem; // we register for the write event to apply our business rules _Item.Write += new Microsoft.Office.Interop.Outlook.ItemEvents_10_WriteEventHandler(_Item_Write); _Item.Open += new Microsoft.Office.Interop.Outlook.ItemEvents_10_OpenEventHandler(_Item_Open); // here we setup our business rules for this business object SetupBusinessRules(); } /// <summary> /// This Method is call. /// </summary> /// <param name="Cancel">if set to <c>true</c> [cancel].</param> void _Item_Open(ref bool Cancel) { if (Open != null) Open(this, EventArgs.Empty); } /// <summary> /// This event gets called whenever the item should be saved. /// </summary> /// <param name="Cancel">if set to <c>true</c> [cancel].</param> void _Item_Write(ref bool Cancel) { // check all business rules, and if one rule has not meet the requirements, Cancel the write event. bool isValid = Validate(); Cancel = !isValid; } #region business rule check methods /// <summary> /// The <b>SetupBusinessRules</b> will register all business rules for this object. /// </summary> private void SetupBusinessRules() { _BusinessRules.Add (new X4UBusinessRule ("LastNameUppercase", "The Lastname of the contact must be uppercase.", this.BusinessRuleCheck_LastNameUppercase )); _BusinessRules.Add (new X4UBusinessRule ("CompanyName3Letters", "The Company Name must have a minimum length of 3.", this.BusinessRuleCheck_CompanyNameMinimum3Letters )); } /// <summary> /// Validates all business rules for this instance. /// </summary> /// <returns></returns> private bool Validate() { // if every business rule is valid we return true if (_BusinessRules.TrueForAll(X4UBusinessRule.IsRuleValid)) return true; // no ? // show a warning to the user and StringBuilder message = new StringBuilder(500); message.AppendLine("You can't save this Item, because the following requirements are not met:"); foreach (X4UBusinessRule rule in _BusinessRules) { if (!rule.IsValid()) message.AppendLine(rule.Description); } // display a message to the user what's wrong. MessageBox.Show(message.ToString()); return false; } /// <summary> /// This businessrule is useless, but will show how it works... /// </summary> /// <returns>returns true, when the lastname of this contact is written in uppercase.</returns> public bool BusinessRuleCheck_LastNameUppercase() { bool isValid = (_Item.LastName == _Item.LastName.ToUpper()); return isValid; } /// <summary> /// This businessrule is useless, but will show how it works... /// </summary> /// <returns>returns true, when the companyname has a minimum length of 3 letters.</returns> public bool BusinessRuleCheck_CompanyNameMinimum3Letters() { bool isValid = false; if (_Item.CompanyName != null) { isValid = (_Item.CompanyName.Length > 2); } return isValid; } /// <summary> /// Gets the inspector. /// </summary> /// <returns>The inspector for this item.</returns> public Outlook.Inspector GetInspector { get { return _Item.GetInspector; } } #endregion } } ------- end of X4UContactItem.cs --------------- ------- X4UContactInspector.cs ----------------- using System; using System.Collections.Generic; using System.Text; // Outlook specific using Outlook = Microsoft.Office.Interop.Outlook; using Office = Microsoft.Office.Core; using System.Windows.Forms; namespace BusinessRules { public delegate void InspectorCloseDelegate(Guid inspectorId); /// <summary> /// /// </summary> class X4UContactInspector { /// <summary> /// a unique id for this inspector item. /// </summary> private Guid _InspectorId = Guid.NewGuid(); /// <summary> /// Gets the id. /// </summary> /// <value>The id.</value> public Guid Id { get { return _InspectorId; } } /// <summary> /// declares an event to notify the application when the inspector has closed. /// </summary> public event InspectorCloseDelegate Close; /// <summary> /// The Outlook INspector behind the contact item. /// </summary> private Outlook.InspectorClass _Inspector = null; /// <summary> /// The ContactItem that we monitor. /// </summary> private X4UContactItem _Item = null; /// <summary> /// Initializes a new instance of the <see cref="T:X4UContactInspector"/> class. /// </summary> /// <param name="contact">The contact.</param> public X4UContactInspector(Outlook.ContactItem contact) { // register for the open event. _Item = new X4UContactItem (contact); _Item.Open += new EventHandler(_Item_Open); } // this event is called when the item is shown up. // we get the Inspector now and register for the close event. void _Item_Open(object sender, EventArgs e) { _Inspector = _Item.GetInspector as Outlook.InspectorClass; _Inspector.InspectorEvents_10_Event_Close += new Microsoft.Office.Interop.Outlook.InspectorEvents_10_CloseEventHandler(_Inspector_InspectorEvents_10_Event_Close); } /// <summary> /// this event occures when the inspector has been closed. /// </summary> void _Inspector_InspectorEvents_10_Event_Close() { // release inspector from memory. _Inspector = null; // notify application to release us from memory. if (Close != null) Close(_InspectorId); } } } ------ end of X4UContactInspector.cs --------------------- ----------- X4UBussinessRule.cs --------------- using System; using System.Collections.Generic; using System.Text; namespace BusinessRules { /// <summary> /// The <b>BusinessRuleCheck</b> delegate declares the funtion signature that is called /// when for validation checks. /// </summary> /// <returns>The function should return true when the requirement has been sucessfully met.</returns> public delegate bool BusinessRuleCheckMethod(); /// <summary> /// The <b>X4UBusinessRule</b> class can be used to check and declare businessrules in applications. /// </summary> public class X4UBusinessRule { /// <summary> /// The anonymous method that is called from this BusinessRule instance when the IsValid check should performed. /// </summary> BusinessRuleCheckMethod _IsValid; /// <summary> /// The anonymous method that is called from this BusinessRule instance when the IsValid check should performed. /// </summary> public BusinessRuleCheckMethod IsValid { get { return _IsValid; } } /// <summary> /// The <b>Construtor</b> takes the name, description and a pointer to the validation method as parameter. /// </summary> /// <param name="name">The Name of the</param> /// <param name="description">The description.</param> /// <param name="ruleValidator">The rule validator method.</param> public X4UBusinessRule(string name, string description, BusinessRuleCheckMethod ruleValidator) { _IsValid = ruleValidator; _Name = name; _Description = description; } /// <summary> /// Determines whether [is rule valid] [the specified rule]. /// </summary> /// <param name="rule">The business rule rule.</param> /// <returns> /// <c>true</c> if [is rule valid] [the specified rule]; otherwise, <c>false</c>. /// </returns> public static bool IsRuleValid(X4UBusinessRule rule) { return (bool)rule.IsValid(); } /// <summary> /// The name of the business rule. /// </summary> string _Name = string.Empty; /// <summary> /// Gets the name of the business rule. /// </summary> /// <value>The name.</value> public string Name { get { return _Name; } } /// <summary> /// The description of the business rule. /// </summary> string _Description = string.Empty; /// <summary> /// Gets the description of the business rule. /// </summary> /// <value>The description.</value> public string Description { get { return _Description; } } } } -------- End of X4UBusinessRule.cs -------------
All 3comments

	Page [ 1 ]
	Mike DellaPietra 19-Sep-2006 12:53 While running this code in debug mode, I came across a flaw. The error that I'm wondering about might be more of a glitch in Outlook though. If you run this code and go to the "Contacts" folder, then in the pane on the right-side, edit a contact so that the CompanyName is less than 3 characters. You will receive the error alert [as you should], however, Outlook leaves the newly typed [bad] CompanyName in the field until the user exits the Contact folder and goes back in. Is there a way to avoid this "glitch"? I am trying to write a program so that the user cannot edit the contact from the "listview" grid in Outlook pane. Any help would be greatly appreciated!
	Helmut Obertanner 28-Sep-2006 16:16 Hello Mike, Sorry I didn't know a way how to prevent an user to edit an outlook item directly in the listview. No Idea. Maybe with the SelectionChanged event discar the changes or something. Greets, Helmut
	Pascal Groulx 12-Jun-2007 13:44 This works very well, but I'd like to know how it is possible to catch the selection of category ? When I select an appointment its okay, but when I select the entire category, the Explorer.Selection collection is empty. Any ideas ?
	Page [ 1 ]

name email