Part 1: Developing a Real Outlook Social Connector Provider by Using a Proxy Library

Summary:  Learn how to create an Outlook Social Connector provider by using the Outlook Social Connector Provider Proxy Library framework.

Applies to: Office 2007 | Office 2010 | Outlook | Outlook 2007 | Outlook 2010 | Visual Studio

Published:  January 2011

Provided by:  Michael Case, iSoftStone | Angela Chu-Hatoun, Microsoft Corporation | Patrick Creehan, Microsoft Corporation

The Microsoft Outlook Social Connector (OSC) provides a communication hub for personal and professional communications. Just by selecting an Outlook item such as an email or meeting request and clicking the sender or a recipient of that item, users can see, in the People Pane, activities, photos, and status updates for the person on their favorite social networks. The OSC obtains social network data by calling an OSC provider, which behaves like a translation layer between Outlook and the social network. The OSC provider model is open, and you can develop a custom OSC provider by implementing the required OSC provider extensibility interfaces. To retrieve social network data, the OSC makes calls to the OSC provider through these interface members. The OSC provider communicates with the social network and returns the social network data to the OSC as a string or as XML that conforms to the Outlook Social Connector XML schema. Figure 1 shows the various components of the sample OfficeTalk OSC provider reviewed in this Visual How To. Figure 1. Relationships of the sample OfficeTalk OSC provider with related components This Visual How To shows the procedures to create a custom OSC provider for OfficeTalk. OfficeTalk is not publicly available and is being used as an example of the kind of social network you might want to develop a custom OSC provider for. You can use the procedures for creating the OSC provider for OfficeTalk to create a custom OSC provider for any social network. The OfficeTalk provider uses the Outlook Social Connector Provider Proxy Library to simplify the implementation of the OSC provider extensibility interfaces. The OSC Provider Proxy Library implements all of the OSC provider extensibility interface members. These interface members, in turn, call a consolidated set of abstract and virtual methods that provide the social network data that the OSC requires. To create a custom OSC provider that uses the OSC Provider Proxy Library, a developer overrides these abstract and virtual methods with the business logic to communicate with the social network. The sample solution for this article includes all of the code for a custom OSC provider for OfficeTalk. However, this Visual How To does not show all of the code in the sample solution. Instead, it focuses on creating a custom OSC provider by using the OSC Provider Proxy Library. The sample solution contains two projects: OSCProvider—This project is an unmodified version of the OSC Provider Proxy Library that is used to simplify the creation of the OfficeTalk OSC provider. OfficeTalkOSCProvider—This project includes the source code files that are specific to the OfficeTalk OSC provider. The OfficeTalkOSCProvider project includes the following source code files: OfficeTalkHelper—This class contains helper methods that are used throughout the sample solution. OTProvider—This is a partial class that contains the OSC Provider Proxy Library override methods that return information about the OSC provider, information about the social network, and information for the current user. OTProvider_Activities—This is a partial class that contains the OSC Provider Proxy Library override methods that return activity information. OTProvider_Friends—This is a partial class that contains the OSC Provider Proxy Library override methods that return friends information. Creating the OfficeTalk OSC Provider Solution The following sections show the procedures to create the OfficeTalk OSC provider sample solution, and add OSC Provider Proxy Library override methods to return information about the OSC provider, the social network, and the current user. You must create the OSC provider as a class library. For this Visual How To, the solution was created with a name of OfficeTalkOSCProvider. Adding the OSC Provider Proxy Library Project You must download the Outlook Social Connector Provider Proxy Library from MSDN Code Gallery, and then extract it to the local computer. To add the OSC Provider Proxy Library to the OfficeTalkOSCProvider solution Copy the OSCProvider project to the OfficeTalkOSCProvider directory. On the File menu in Visual Studio 2010, point to Add, and then click Existing Project. Select the OSCPRovider.csproj project that you copied in Step 1. Adding References Add the following references to the OfficeTalkOSCProvider: Outlook Social Provider COM component. The name in the COM tab is Microsoft Outlook Social Provider Extensibility. If there are multiple versions, select TypeLib Version 1.1. System.Drawing Adding Social Network Specific References and Files Add other appropriate references and files for the social network. The sample solution does not include the OfficeTalk API assembly. To support the social network for which you are developing an OSC provider, replace the OfficeTalk API references and files with the references and files that are specific to your social network. The sample solution for OfficeTalk contains the following references and files: The OfficeTalk API assembly. The OfficeTalk icon file. Creating a Subclass of the OSC Provider Proxy Library OSCProvider Use the OSC Provider Proxy Library to create a subclass of the OSCProvider class, OTProvider, which represents the sample OSC provider. Add a class named OTProvider to the OfficeTalkOSCProvider project. OTProvider is defined as a partial class so that logic for OSC provider core methods, friends, and activities can be defined in separate source code files. Replace the class definition with the code in the following section. The code example starts with the using statements for the OSC Provider Proxy Library and OfficeTalk API. The OTProvider partial class then inherits from the OSCProvider class. Note that the OTProvider class has the ComVisible attribute so that the Outlook Social Connector can call it. using System; using System.Globalization; using System.Collections.Generic; using System.IO; using System.Reflection; using System.Drawing; using System.Drawing.Imaging; // Using statements for the OSC Provider Proxy Library. using OSCProvider; using OSCProvider.Schema; // Using statements for the social network. using OfficeTalkAPI; namespace OfficeTalkOSCProvider { // SubClass of the OSC Provider Proxy Library OSCProvider // used to create a custom OSC provider. [System.Runtime.InteropServices.ComVisible(true)] public partial class OTProvider : OSCProvider.OSCProvider { ... After the OTProvider class is defined, add the following code for constants used throughout the OfficeTalkOSCProvider solution. // Constants for the OfficeTalk OSC provider. internal static string NETWORK_NAME = @"OfficeTalk"; internal static string NETWORK_GUID = @"YourNetworkGuid"; internal static string API_VERSION = @"YourApiVersion"; internal static string API_URL = @"YourApiUrl"; internal static OSCProvider.ProviderSchemaVersion SCHEMA_VERSION = ProviderSchemaVersion.v1_1; Allowing for Debugging To debug the OfficeTalkOSCProvider, you must modify the OfficeTalkOSCProvider project to start using Outlook and register the OfficeTalkOSCProvider as an Outlook Social Connector. To set up the OfficeTalkOSCProvider project for debugging Right-click the OfficeTalkOSCProvider project, and then click Properties. Select the Debug tab. Under Start Action, select Start External Program. Specify the full path to the version of Outlook that is installed on your computer. The default path for 32-bit Outlook on 32-bit Windows is C:\Program Files\Microsoft Office\Office14\OUTLOOK.EXE. The Outlook Social Connector will not call the OfficeTalkOSCProvider until it is registered as an OSC provider. The sample solution includes a file named RegisterProvider.reg that updates the registry with the entries that are required to register the OfficeTalkOSCProvider as an OSC provider. You can update the registry by opening the RegistryProvider.reg file in Windows Explorer. The RegisterProvider.reg file assumes that the sample solution is located in the C:\temp directory. If the sample solution is located in a different directory, update the CodeBase entry in the RegisterProvider.reg file to point to the correct location. Adding Helper Methods The OfficeTalkHelper class contains helper methods, including the GetOfficeTalkClient and ConvertUserToPerson methods, that are used throughout the sample solution. The following GetOfficeTalkClient method returns an OfficeTalkClient object that is used to communicate with OfficeTalk. If the OfficeTalkClient has not been initialized, GetOfficeTalkClient creates and configures a new OfficeTalkClient by using the API_URL and API_VERSION constants that are defined in OTProvider. // Returns a reference to the OfficeTalk client. private static OfficeTalkClient officeTalkClient = null; internal static OfficeTalkClient GetOfficeTalkClient() { if (officeTalkClient == null) { officeTalkClient = new OfficeTalkClient(OTProvider.API_URL); OfficeTalkClient.UserAgent = @"OfficeTalkOSC/" + OTProvider.API_VERSION; } return officeTalkClient; } The ConvertUserToPerson method converts an OfficeTalk User object to an OSC Provider Proxy Library Person object that is usable within the OSC Provider Proxy Library. The ConvertUserToPerson method creates a new OSC Provider Proxy Library Person and then maps the User properties to the related Person properties. // Converts an Office Talk User to an OSC Provider Proxy Library Person. internal static Person ConvertUserToPerson(OfficeTalkAPI.OTUser user) { // Create the OSC Provider Proxy Library Person. Person person = new Person(); // Map the User properties to the Person properties. person.FullName = user.name; person.Email = user.email; person.Company = user.department; person.UserID = user.id.ToString(CultureInfo.InvariantCulture); person.Title = user.title; person.CreationTime = user.created_atAsDateTime; // FriendStatus is based on whether the user is being followed // by the currently logged-on user. person.FriendStatus = user.following ? FriendStatus.friend : FriendStatus.notfriend; // Set the PictureUrl if a profile picture is loaded in OfficeTalk. if (user.image_url != null) { person.PictureUrl = new Uri(OTProvider.API_URL + user.image_url); } // WebProfilePage is set to the user's home page in OfficeTalk. person.WebProfilePage = OTProvider.API_URL + @"/Home/index/" + user.alias + "#User"; return person; } Overriding the GetProviderData Method The OSC ISocialProvider interface contains members that return information about the OSC provider. This includes the capabilities of the social network, how to communicate with the social network, and general information about the social network. The OSC Provider Proxy Library provides the GetProviderData abstract method, which you can override to return OSC provider information. The GetProviderData abstract method returns the OSC Provider Proxy Library ProviderData object, which encapsulates the provider information. The following section of the GetProviderData override method initializes a ProviderData object and sets the properties for the OfficeTalk provider. // The ProviderData contains information about the social network and is // used by the OSC ISocialProvider members to return information. ProviderData providerData = new ProviderData(); // Friendly name of the social network to display in Outlook. providerData.NetworkName = NETWORK_NAME; // GUID that represents the social network. // This GUID should not change between versions. providerData.NetworkGuid = new Guid(NETWORK_GUID); // Version of the social network provider. providerData.Version = API_VERSION; // Array of URLs that the social network provider uses. // The default URL should be the first item in the array. providerData.Urls = new string[] { API_URL }; // The icon of the social network to display in Outlook. Byte[] icon = null; Assembly assembly = Assembly.GetExecutingAssembly(); using (Stream imageStream = assembly.GetManifestResourceStream("OfficeTalkOSCProvider.OTIcon16.bmp")) { using (MemoryStream memoryStream = new MemoryStream()) { using (Image socialNetworkIcon = Image.FromStream(imageStream)) { socialNetworkIcon.Save(memoryStream, ImageFormat.Bmp); icon = memoryStream.ToArray(); } } } providerData.Icon = icon; The following section of the GetProviderData override method uses the Proxy Library Capabilities class to identify the capabilities and requirements for the OfficeTalk OSC provider. The Capabilities class defines capabilities by setting the CapabilityFlags property. The CapabiltiesFlag property uses a bitmask and is set by using the bitwise OR operator to combine constants that the OSC Provider Proxy Library has defined for each capability. // Define the capabilities for the provider. // The Capabilities object will generate the appropriate XML string. Capabilities capabilities = new Capabilities(SCHEMA_VERSION); capabilities.CapabilityFlags = // OSC should call the GetAutoConfiguredSession method to get a // configured session for the user. Capabilities.CAP_SUPPORTSAUTOCONFIGURE | // OSC should hide all links in the Account configuration dialog box. Capabilities.CAP_HIDEHYPERLINKS | Capabilities.CAP_HIDEREMEMBERMYPASSWORD | // The following activity settings identify that Activities uses // hybrid synchronization. // OSC will store activities for friends in a hidden folder and // activities for non-friends in memory. Capabilities.CAP_GETACTIVITIES | Capabilities.CAP_DYNAMICACTIVITIESLOOKUP | Capabilities.CAP_DYNAMICACTIVITIESLOOKUPEX | Capabilities.CAP_CACHEACTIVITIES | // The following Friends settings identify that friend information // uses hybrid synchronization. // OSC will call the GetPeopleDetails method every time the People Pane // is refreshed to ensure the latest user information is displayed. Capabilities.CAP_GETFRIENDS | Capabilities.CAP_DYNAMICCONTACTSLOOKUP | Capabilities.CAP_CACHEFRIENDS | // The following Friends settings identify that OfficeTalks supports // the FollowPerson and UnFollowPerson calls. Capabilities.CAP_DONOTFOLLOWPERSON | Capabilities.CAP_FOLLOWPERSON; // Set the email HashFunction. // Setting the EmailHashFunction is required if CAP_DYNAMICCONTACTSLOOKUP // or CAP_DYNAMICACTIVITIESLOOKUPEX are set. capabilities.EmailHashFunction = HashFunction.SHA1; // Set the capabilities property on the providerData object. providerData.ProviderCapabilities = capabilities; The capabilities and requirements defined in the preceding code example are specific to OfficeTalk. A custom OSC provider that is developed for a different social network must define a set of capabilities and requirements that are specific to that social network. The following list shows the CapabilityFlag constants that are available in the OSC Provider Proxy Library Capabilities class. CAP_SUPPORTSAUTOCONFIGURE The provider supports calling the ISocialProvider.GetAutoConfiguredSession method to attempt automatic configuration of the network for the user. CAP_GETFRIENDS The provider supports the ISocialPerson.GetFriendsAndColleagues or ISocialSession2.GetPeopleDetails method. The OSC uses the CAP_CACHEFRIENDS and CAP_DYNAMICCONTACTSLOOKUP settings to determine whether friends are stored as Outlook contact items or are stored in memory. CAP_CACHEFRIENDS The provider supports storing friends as Outlook contact items in a social-network-specific contacts folder. CAP_DYNAMICCONTACTSLOOKUP The provider supports the ISocialSession2.GetPeopleDetails method for on-demand synchronization of friends and non-friends. If CAP_DYNAMICCONTACTSLOOKUP is set, the OSC calls the ISocialSession2.GetPeopleDetails method every time the People Pane is refreshed. CAP_SHOWONDEMANDCONTACTSWHENMINIMIZED Indicates that the OSC should carry out on-demand synchronization for friends and non-friends when the People Pane is minimized. CAP_FOLLOWPERSON The provider supports the ISocialSession.FollowPerson method for adding the person as a friend on the social network. CAP_DONOTFOLLOWPERSON The provider supports the ISocialSession.UnFollowPerson method for removing the person as a friend on the social network. CAP_GETACTIVITIES The provider supports the ISocialPerson.GetActivities or ISocialSession2.GetActivitiesEx method. The OSC uses the CAP_CACHEACTIVITIES and CAP_DYNAMICACTIVITIESLOOKUPEX settings to determine whether activities are stored as Outlook RSS items or are stored in memory. CAP_CACHEACTIVITIES The provider supports storing activities as Outlook RSS items in a hidden News Feed folder. To support cached synchronization of activities CAP_CACHEACTIVITIES should be set and CAP_DYNAMICACTIVITIESLOOKUPEX should not be set. With cached synchronization of activities, the OSC stores all activities as Outlook RSS items in a hidden News Feed folder. To support hybrid synchronization of activities, both CAP_CACHEACTIVITIES and CAP_DYNAMICACTIVITIESLOOKUPEX should be set. With hybrid synchronization of activities, the OSC stores activities for friends as Outlook RSS items in a hidden News Feed folder and caches activities for non-friends in memory. To support on-demand synchronization of activities, CAP_CACHEACTIVITIES should not be set and CAP_DYNAMICACTIVITIESLOOKUPEX should be set. With on-demand synchronization of activities, the OSC caches all activities in memory. CAP_DYNAMICACTIVITIESLOOKUP Deprecated in OSC 1.1. Use the CAP_DYNAMICACTIVITIESLOOKUPEX setting instead. CAP_DYNAMICACTIVITIESLOOKUPEX The provider supports the ISocialSession2.GetActivitiesEx method for on-demand or hybrid synchronization of activities. To support on-demand synchronization of activities, CAP_DYNAMICACTIVITIESLOOKUPEX should be set and CAP_CACHEACTIVITIES should not be set. With on-demand synchronization of activities, the OSC calls ISocialSession2.GetActivitiesEx every time the People Pane is refreshed. To support hybrid synchronization of activities, both CAP_DYNAMICACTIVITIESLOOKUPEX and CAP_CACHEACTIVITIES should be set. With hybrid synchronization of activities, the OSC calls ISocialSession2.GetActivitiesEx every 30 minutes to refresh activities information. When CAP_DYNAMICACTIVITIESLOOKUPEX is not set, the OSC does not call ISocialSession2.GetActivitiesEx. CAP_SHOWONDEMANDACTIVITIESWHENMINIMIZED Indicates that the OSC should carry out on-demand synchronization for activities when the People Pane is minimized. CAP_DISPLAYURL Indicates that the OSC should display the network URL in the account configuration dialog box. CAP_HIDEHYPERLINKS Indicates that the OSC should hide the "Click here to create an account" and the "Forgot your password?" hyperlinks in the account configuration dialog box. CAP_HIDEREMEMBERMYPASSWORD Indicates that the OSC should hide the Remember my password check box in the account configuration dialog box. CAP_USELOGONWEBAUTH Indicates that the OSC should use forms-based authentication. When CAP_USELOGONWEBAUTH is set, the OSC uses forms-based authentication and calls the ISocialSession.LogonWeb method. When CAP_USELOGONWEBAUTH is not set, the OSC uses basic authentication and calls the ISocialSession.Logon method. CAP_USELOGONCACHED The provider supports the ISocialSession2.LogonCached method to log on with cached credentials. When CAP_USELOGONCACHED is set, the OSC ignores the CAP_USELOGONWEBAUTH setting and calls ISocialSession2.LogonCached for authentication. Overriding the GetMe Method Many of the OSC interface members and OSC Provider Proxy Library override methods require information about the current user. The OSC Provider Proxy Library provides the GetMe abstract method, which you can override to return information about the current user from the social network. The GetMe abstract method returns a Person object, which contains all social network data for the current user. The GetMe override method shown in the following example gets an OfficeTalkClient object to communicate with OfficeTalk. The GetMe override method then calls the OfficeTalk GetUser method by using the user name that is used to log on to Windows. After obtaining the OfficeTalk User, the GetMe override method calls the OfficeTalkHelper ConvertUserToPerson method to convert the OfficeTalk User to a Person that can be used within the OSC Provider Proxy Library. After the conversion is complete, the GetMe override method sets the Person.UserName property for the ISocialSession.LoggedOnUserName interface member. Only the GetMe override method sets the Person.UserName property when it returns information about the current user. // OSC Proxy Library override method used to return information // for the current user. public override Person GetMe() { // Get a reference to the OfficeTalk client. OfficeTalkClient officeTalkClient = OfficeTalkHelper.GetOfficeTalkClient(); // Look up the user based on credentials used to log on to Windows. OTUser user = officeTalkClient.GetUser(System.Environment.UserName, Format.JSON); // Convert the OfficeTalk User to an OSC Provider Proxy Person. Person p = OfficeTalkHelper.ConvertUserToPerson(user); // Set the UserName property. // This is used only by the Person that the GetMe method returns to // support the OSC ISocialSession.LoggedOnUserName property. p.UserName = System.Environment.UserName; return p; } Overriding OSC Provider Proxy Library Friends Methods A custom OSC provider that uses the OSC Provider Proxy Library must override the abstract and virtual methods for returning friends social network data. In the sample solution, the overrides for these OTProvider methods are located in the OTProvider_Friends source file. The abstract and virtual methods for friends are as follows: GetPeopleDetails—Returns detailed user information for the email addresses that are passed into the method. GetFriends—Returns a list of friends for the current user. FollowPersonEx—Adds the person who is identified by the email address as a friend on the social network. UnFollowPerson—Removes the person who is identified by the user ID as a friend on the social network. Reviewing these methods is outside of the scope of this Visual How To. For more information about returning friends social network data, see Part 2: Getting Friends Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility. Overriding OSC Provider Proxy Library Activity Methods A custom OSC provider that uses the OSC Provider Proxy Library must override the abstract and virtual methods for returning activity social network data. In the sample solution, the overrides for these OTProvider methods are located in the OTProvider_Activities source file. There is only one method to override for activities: GetActivities—Returns activities for all users who are identified by the email addresses that are passed into the method. Covering these methods in detail is outside of the scope of this Visual How To. For more information about returning activities social network data, see Part 3: Getting Activities Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility Visual How To. Creating a custom Outlook Social Connector (OSC) provider for a social network is a straightforward process of implementing the OSC Provider extensibility interfaces to return social network data. The OSC Provider Proxy Library simplifies this process by removing the requirement to implement each individual interface member. Instead the OSC Provider Proxy Library defines a consolidated set of abstract and virtual methods to provide social network data. The developer of the OSC provider can focus on overriding these methods with the business logic required to interface with the social network API. The sample solution for this article includes all of the code required for a custom OSC provider for OfficeTalk. This Visual How To does not cover all of the code in the sample solution. This Visual How To focuses on creating a custom OSC provider solution, and returning information about the OSC provider, the social network capabilities, and the current user. The social network data that the OfficeTalk provider returns is shown in Figure 2. Figure 2. OSC showing OfficeTalk social network data in the People Pane For more information about returning friends social network data, see Part 2: Getting Friends Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility. For more information about returning activities social network data, see Part 3: Getting Activities Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility.

Watch the video > [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/b10d7dfb-c7d0-4d5c-b948-71c7b5c1be21] Length: 15:24 Grab the Code Part 2: Getting Friends Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility Part 3: Getting Activities Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility Part 4: Building an Installation Package for a Real Outlook Social Connector Provider Outlook Social Connector 1.1 Provider Reference Getting Started with Developing an Outlook Social Connector Provider XML for Capabilities Capabilities XML Elements Outlook Social Connector Provider Proxy Library OfficeTalk Outlook Sample: Outlook Social Connector Provider Outlook Developer Center