我的Office Outlook插件開發之旅（一）

目的開發一款可以同步Outlook郵件通訊錄信息的插件。方案 VSTO 外接程式 COM 載入項 VSTO 外接程式對Outlook的支持，是從2010版本之後開始的。 VSTO 4.0 支持Outlook 2010以後的版本，所以編寫一次代碼，就可以在不同的版本上運行。 COM 載入項十分依賴 ...

目的

開發一款可以同步Outlook郵件通訊錄信息的插件。

方案

VSTO 外接程式
COM 載入項

VSTO 外接程式對Outlook的支持，是從2010版本之後開始的。
VSTO 4.0 支持Outlook 2010以後的版本，所以編寫一次代碼，就可以在不同的版本上運行。

COM 載入項十分依賴於.NET Framework框架和Office的版本，之後講到的時候你就明白。

VSTO 外接程式

VSTO，全稱是Visual Studio Tools for Office，在微軟的Visual Studio平臺中進行Office專業開發。VSTO是VBA的替代產品，使用該工具包使開發Office應用程式變得更簡單，VSTO還能使用Visual Studio開發環境中的眾多功能。
VSTO依賴於.NET Framework框架，並且不能在.net core或者.net 5+以上的平臺運行。

創建VSTO程式

使用Visual Studio 2013的新建項目，如果你使用更新版本的話，那麼你大概率找不到。因為被移除了。比如Visual Studio 2019最低創建的Outlook 2013 外接程式

Office/SharePoint -> .Net Framework 4 -> Outlook 2010 外接程式

之後我們會得到，這樣的項目結構

打開ThisAddIn.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml.Linq;
using Outlook = Microsoft.Office.Interop.Outlook;
using Office = Microsoft.Office.Core;
using Microsoft.Office.Interop.Outlook;
using System.Windows.Forms;
using System.Data;
using System.Data.SqlClient;
using System.IO;
using System.Threading;
using System.Collections;

namespace ContactsSynchronization
{
    public partial class ThisAddIn
    {
        
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
            // Outlook啟動時執行
            MessageBox.Show("Hello VSTO!");
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
            // Outlook關閉時執行
        }

        #region VSTO 生成的代碼

        /// <summary>
        /// 設計器支持所需的方法 - 不要
        /// 使用代碼編輯器修改此方法的內容。
        /// </summary>
        private void InternalStartup()
        {
            // 綁定聲明周期函數
            this.Startup += new System.EventHandler(ThisAddIn_Startup);
            this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
        }

        #endregion
    }
}

啟動試試看

到這裡我們就已經把項目搭建起來了，但在寫代碼之前不如再認識認識Outlook的個個對象吧。

認識VSTO中常用對象

微軟文檔
https://learn.microsoft.com/zh-cn/dotnet/api/microsoft.office.interop.outlook.application?view=outlook-pia

常用類型

MAPIFolder表示Outlook中的一個文件夾
ContactItem 表示一個聯繫人
DistListItem 表示一個聯繫人文件夾中的群組
OlDefaultFolders 獲取預設文件類型的枚舉
OlItemType 獲取文件夾子項類型的枚舉

全局實例Application上掛載了我們用到大多數函數和屬性。

Application.Session;// 會話實例
Application.Version;// DLL動態鏈接庫版本
Application.Name;// 應用名稱

Application.Session會話實例，可以獲取Outlook的大多數狀態，數據。如文件夾、聯繫人、郵件等。

Outlook文件夾結構

Outlook 按照郵件賬號區分用戶數據，即每個郵件賬號都有獨立的收件箱，聯繫人等。

Outlook 預設情況下的文件夾結構

獲取第一個郵箱賬號的預設聯繫人文件夾

Application.Session.Stores.Cast<Outlook.Store()>.First().GetDefaultFolder(OlDefaultFolders.olFolderContacts);

獲取Outlook的狀態信息

獲取聯繫人信息

MAPIFolder folder = Application.Session.GetDefaultFolder(OlDefaultFolders.olFolderContacts);//獲取預設的通訊錄文件夾
IEnumerable<ContactItem> contactItems = folder.Items.OfType<ContactItem>(); // 獲取文件夾下的子項，OfType<ContactItem>只拿聯繫人的
foreach (ContactItem it in contactItems)
{
    // 拿聯繫人的各種信息
    string fullName = it.FullName;
    // 註意在此處修改聯繫人信息，再Save()是不生效的
}

添加聯繫人

MAPIFolder folder = Application.Session.GetDefaultFolder(OlDefaultFolders.olFolderContacts);// 獲取預設的聯繫人文件夾
ContactItem contact = folder.Items.Add(OlItemType.olContactItem);// 新增聯繫人子項
// 設置各種信息
contact.FirstName = "三";
contact.LastName = "張";
contact.Email1Address = "[email protected]";
// 存儲聯繫人
contact.Save();

刪除聯繫人

Microsoft.Office.Interop.Outlook.MAPIFolder deletedFolder = application.Session.GetDefaultFolder(OlDefaultFolders.olFolderDeletedItems);// 預設的聯繫人文件夾
int count = deletedFolder.Items.Count;// 獲取子項數，包含聯繫人和群組
for (int i = count; i > 0; i--)// 遍歷刪除
{
    deletedFolder.Items.Remove(i);
}

成品代碼

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml.Linq;
using Outlook = Microsoft.Office.Interop.Outlook;
using Office = Microsoft.Office.Core;
using Microsoft.Office.Interop.Outlook;
using System.Windows.Forms;
using System.Data;
using System.Data.SqlClient;
using System.IO;
using System.Threading;
using System.Collections;

namespace ContactsSynchronization
{
    public partial class ThisAddIn
    {
        

        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
            OperatorContact operatorInstance = new OperatorContact(this.Application);
            operatorInstance.Task();
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
        }

        #region VSTO 生成的代碼

        /// <summary>
        /// 設計器支持所需的方法 - 不要
        /// 使用代碼編輯器修改此方法的內容。
        /// </summary>
        private void InternalStartup()
        {
            this.Startup += new System.EventHandler(ThisAddIn_Startup);
            this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
        }

        #endregion
    }

    class OperatorContact
    {
        public OperatorContact(Microsoft.Office.Interop.Outlook.Application application)
        {
            this.application = application;
        }

        Microsoft.Office.Interop.Outlook.Application application = null; // outlook程式實例

        private static string addressBookName = "湯石集團通訊錄";// 通訊錄名稱

        private Microsoft.Office.Interop.Outlook.MAPIFolder addressBookFolder = null; // 通訊錄文件夾實例

        public void Task()
        {
            new Thread(Run).Start();
        }

        /// <summary>
        /// 開個新線程執行任務，不要堵塞原來的線程
        /// </summary>
        private void Run()
        {
            try
            {
                if (NeedUpdate())
                {
                    addressBookFolder = getAddressBookFolder();// 覆蓋式創建通訊錄
                    List<Contact> remoteContacts = readRemoteContacts();// 讀取遠程郵箱通訊錄
                    if (remoteContacts == null) return;
                    Adjust(remoteContacts);// 調整聯繫人和群組
                    updateClientVersion();// 更新本地通訊錄版本號
                } 
            }
            catch (System.Exception ex)
            {
                const string path = @"C:\TONS\email-plugin-error.log";
                FileInfo fileInfo = new FileInfo(path);
                long length = 0;
                if (fileInfo.Exists && fileInfo.Length != 0) length = fileInfo.Length / 1024 / 1024;
                if (length <= 3) File.AppendAllText(path, ex.Message + "\r\n");
                else File.WriteAllText(path, ex.Message + "\r\n");
            }
        }

        /// <summary>
        /// 覆蓋式創建通訊錄
        /// </summary>
        /// <returns>通訊錄文件夾實例</returns>
        private Microsoft.Office.Interop.Outlook.MAPIFolder getAddressBookFolder()
        {
            // 獲取用戶第一個PST檔的通訊錄文件夾的枚舉器
            IEnumerator en = application.Session.Stores.Cast<Outlook.Store>().First()
                .GetDefaultFolder(OlDefaultFolders.olFolderContacts)
                .Folders.GetEnumerator();
            bool exits = false;
            Microsoft.Office.Interop.Outlook.MAPIFolder folder = null;

            // 遍歷文件夾
            while (en.MoveNext()) {
                Microsoft.Office.Interop.Outlook.MAPIFolder current = (Microsoft.Office.Interop.Outlook.MAPIFolder)en.Current;
                if (current.Name == addressBookName) {
                    exits = true;
                    folder = current;
                }
            }

            if (!exits)
             {
                 // 創建湯石集團通訊錄,並映射成通訊錄格式
                 Microsoft.Office.Interop.Outlook.MAPIFolder newFolder = application.Session.Stores.Cast<Outlook.Store>().First()
                          .GetDefaultFolder(OlDefaultFolders.olFolderContacts)
                          .Folders.Add(addressBookName);
                 newFolder.ShowAsOutlookAB = true;// 設置成“聯繫人”文件夾
                 return newFolder;
             }
             else {
                // 返回已經存在的同時集團通訊錄文件夾,並刪除裡面的內容
                int count = folder.Items.Count;
                for (int i = count; i > 0; i--)
                {
                    folder.Items.Remove(i);
                }
                Microsoft.Office.Interop.Outlook.MAPIFolder deletedFolder = application.Session.GetDefaultFolder(OlDefaultFolders.olFolderDeletedItems);
                count = deletedFolder.Items.Count;
                for (int i = count; i > 0; i--)
                {
                    deletedFolder.Items.Remove(i);
                }
                return folder;
             }
        }



        /// <summary>
        /// 更新本地的銅須錄版本
        /// </summary>
        private void updateClientVersion()
        {
            String path = @"C:\TONS\email-plugin-version.conf";
            string version = getRemoteVersion();
            if (!File.Exists(path))
            {
                File.WriteAllText(path,version);
            }
            else {
                File.WriteAllText(path, version);
            }
        }

        /// <summary>
        /// 判斷是否需要更新
        /// </summary>
        /// <returns>boolean值</returns>
        private bool NeedUpdate()
        {
            string remoteVersion = getRemoteVersion();
            if (remoteVersion == null) return false;
            string clientVersion = getClientVersion();
            return !(clientVersion == remoteVersion);
        }

        /// <summary>
        /// 讀取伺服器的通訊錄版本
        /// </summary>
        /// <returns>通訊錄版本</returns>
        private string getRemoteVersion()
        {
            List<Dictionary<string, object>> items = SelectList(
                "SELECT TOP(1) [version] FROM TonsOfficeA..VersionControl WHERE applicationID = N'EmailContact'"
                , "Server=192.168.2.1;Database=TonsOfficeA;uid=sa;pwd=dsc");
            if (items == null) return null;
            return items[0]["version"].ToString();
        }

        /// <summary>
        /// 獲取本地的通訊錄版本
        /// </summary>
        /// <returns>通訊錄版本</returns>
        private string getClientVersion()
        {
            String path = @"C:\TONS\email-plugin-version.conf";
            if (!File.Exists(path)) return null;
            return File.ReadAllText(path);
        }

        /// <summary>
        /// 讀取遠程的通訊錄
        /// </summary>
        /// <returns>聯繫人實例集合</returns>
        private List<Contact> readRemoteContacts()
        {
            List<Contact> remoteContacts = new List<Contact>();
            List<Dictionary<string, object>> items =
                SelectList(
                    "select [emailAddress],[firstName],[lastName],[companyName],[department],[_group] as 'group',[jobTitle] from [TonsOfficeA].[dbo].[EmailContacts]",
                    "Server=192.168.2.1;Database=TonsOfficeA;uid=sa;pwd=dsc");
            items.ForEach(it =>
            {
                Contact contact = new Contact();
                contact.email1Address = it["emailAddress"].ToString();
                contact.firstName = it["firstName"].ToString();
                contact.lastName = it["lastName"].ToString();
                contact.companyName = it["companyName"].ToString();
                contact.department = it["department"].ToString();
                if (it["jobTitle"] != null) contact.jobTitle = it["jobTitle"].ToString();
                contact.groups = it["group"].ToString().Split(',').ToList();
                remoteContacts.Add(contact);
            });
            return remoteContacts;
        }

        /// <summary>
        /// 執行select語句
        /// </summary>
        /// <param name="sql">select語句</param>
        /// <param name="connection">資料庫鏈接語句</param>
        /// <returns>List<Dictionary<string, object>>結果</returns>
        /// <exception cref="System.Exception"></exception>
        public List<Dictionary<string, object>> SelectList(string sql, string connection)
        {
            if (sql == null || connection == null || sql == "" || connection == "")
                throw new System.Exception("未傳入SQL語句或者Connection鏈接語句");
            List<Dictionary<string, object>> list = new List<Dictionary<string, object>>();
            SqlConnection conn = new SqlConnection(connection);
            SqlCommand cmd = new SqlCommand(sql, conn);
            try
            {
                conn.Open();
                SqlDataReader sqlDataReader = cmd.ExecuteReader(CommandBehavior.CloseConnection);
                if (sqlDataReader == null) return null;
                while (sqlDataReader.Read())
                {
                    int count = sqlDataReader.FieldCount;
                    if (count <= 0) continue;
                    Dictionary<string, object> map = new Dictionary<string, object>();
                    for (int i = 0; i < count; i++)
                    {
                        string name = sqlDataReader.GetName(i);
                        object value = sqlDataReader.GetValue(i);
                        map.Add(name, value);
                    }
                    list.Add(map);
                }

                conn.Close();
                return list;
            }
            catch (System.Exception)
            {
                conn.Close();
                return null;
            }
        }

        /// <summary>
        /// 調整通訊錄聯繫人
        /// </summary>
        /// <param name="remoteContacts">資料庫導入的聯繫人信息的源</param>
        private void Adjust(List<Contact> remoteContacts)
        {            
            // copy一份以來做群組
            List<Contact> distListItems = new List<Contact>();
            Contact[] tempItems = new Contact[remoteContacts.Count];
            remoteContacts.CopyTo(tempItems);
            tempItems.ToList().ForEach(it =>
            {
                it.groups.ForEach(g =>
                {
                    Contact con = new Contact
                    {
                        firstName = it.firstName,
                        lastName = it.lastName,
                        email1Address = it.email1Address,
                        companyName = it.companyName,
                        department = it.department,
                        group = g
                    };
                    distListItems.Add(con);
                });
            });
           
            // 添加聯繫人
            remoteContacts.ForEach(it =>
            {

                ContactItem contact = addressBookFolder.Items.Add();
                contact.FirstName = it.firstName;
                contact.LastName = it.lastName;
                contact.Email1Address = it.email1Address;
                contact.CompanyName = it.companyName;
                contact.Department = it.department;
                if (it.jobTitle != null) contact.JobTitle = it.jobTitle;
                contact.Save();
            });

            // 按群組分組，並創建群組保存
            List<ContactStore> contactStores = distListItems
                .GroupBy(it => it.group)
                .Select(it => new ContactStore { group = it.Key, contacts = it.ToList() })
                .ToList();
            contactStores.ForEach(it =>
            {
                DistListItem myItem = addressBookFolder.Items.Add(OlItemType.olDistributionListItem);
                it.contacts.ForEach(contact =>
                {
                    string id = String.Format("{0}{1}({2})", contact.lastName, contact.firstName,
                        contact.email1Address);
                    Recipient recipient = application.Session.CreateRecipient(id);
                    recipient.Resolve();
                    myItem.AddMember(recipient);
                });
                myItem.DLName = it.group;
                myItem.Save();
            });
        }

        struct Contact
        {
            public string email1Address; // 郵箱
            public string firstName; // 姓氏
            public string lastName; // 姓名
            public string companyName; // 公司名稱
            public string department; // 部門名稱
            public List<string> groups; // 分組集合
            public string group; // 分組
            public string jobTitle; // 職稱
        }

        struct ContactStore
        {
            public string group;
            public List<Contact> contacts;
        }
    }
}

打包、安裝和卸載

右鍵項目 -> 發佈

發佈後你會看到這樣的結構

點擊setup.exe即可安裝了
卸載需要使用VSTOInstaller.exe

"C:\Program Files (x86)\Common Files\microsoft shared\VSTO\10.0\VSTOInstaller.exe" /u "你的.vsto文件目錄"