The sample solutions are packaged as IExpress files. When you double-click the IExpress package, you are prompted for a folder location for the files.

The sample solution for deploying Electronic Business Cards by using a Office SharePoint Server 2007 site is EBC Templates on SharePoint Deployment Example. The sample solution for deploying business cards by using a .NET solution is EBC Templates on .NET Deployment Example.

The following files and folders are included in the SharePoint sample solution package (EBCSharePoint.exe):

The following files and folders are included in the .NET sample solution package, EBCNet.exe:

The steps for working with the SharePoint sample solution are outlined here. For detailed descriptions that reference the sample code, see Using a SharePoint site for distributing business cards later in this topic.

Install and configure the following environment to work with the SharePoint sample solution:

• Office SharePoint Server 2007 must be installed on a local computer running Microsoft Windows Server 2003 or later.

• An Office SharePoint Server 2007 site must be available, configured with user profiles.

With the requirements in place, follow these steps to install and configure the solution for your organization's environment. First, configure the Web.Config file.

1. Open Web.Config from the download package in an editor and set SiteURL to the URL for your SharePoint site (for example, YourSharePointURL).

2. Open the Web.Config file for your SharePoint site in an editor, and copy the appSettings section of the download package's Web.Config file to the appSettings section of the SharePoint site's Web.Config file. The site's Web.Config file is located in SharePoint's home directory.

3. Save the Web.Config files and exit the editors.

Follow these directions to locate the Web.Config file for your SharePoint site.

To locate the home directory of a SharePoint site

After configuring the Web.Config file, you compile the solution and place required files in the correct folders.

To compile the solution

You might need to change the permissions for EBCDeploymentExample.aspx to copy this file.

Navigate to http://YourSharePointURL/_layouts/EBCDeploymentExample.aspx to explore the sample solution.

When users click a card image, they see a dialog box similar to the following example:

When users click Open, the business card is added to Contacts in Outlook, and the card is personalized with their contact information.

The steps for working with the .NET sample solution are outlined here. For detailed descriptions that reference the sample code, see Using a .NET 2.0 internal Web site for distributing business cards later in this topic.

To work with the .NET sample solution, Microsoft Visual Studio 2005 must be installed on your local computer. It is also helpful to use a local Web site when you work with the sample solution.

Configure the environment to use the sample solution.

1. In Visual Studio, open an existing Web site and select the example folder.

2. On the Website menu, click Add Reference..., and select System.DirectoryServices.

3. On the Website menu, click Add Reference..., and select System.Drawing.

4. In Solution Explorer, right-click EBCDeploymentExample.aspx and select Set As Start Page.

5. Edit Web.Config from the download package in an editor and set userName and password to a valid username and password on your domain.

   Note:
   Including a plain text username and password in a file is not a secure solution. See the following articles for information about creating a more secure solution: How to use the ASP.NET utility to encrypt credentials and session state connection strings and .NET Framework Developer's Guide: ASP.NET Impersonation.

6. In Web.Config, set ADPath to point to a valid Active Directory on your network.

7. Save the Web.Config file and exit the editor.

After you complete these configuration steps, you can see the sample solution by clicking Run to run the Web site in Visual Studio.

When users click a card image, they see a dialog box similar to the following example:

When they click Open, the business card is added to Contacts in Outlook, and the card is personalized with their contact information.

The first step in providing an Electronic Business Card for users to download is designing a business card to use as a template. You do this by creating a business card in a new Outlook contact.

To create an Electronic Business Card in Outlook

1. On the File menu, point to New, and click Contact.

2. Type a name for the contact (for example, Sample Card).

3. Enter information on the business cards. For example, you might want to include:

   • Full Name

   • Job Title

   • Company

   • Business Phone

   • Business Fax

   • E-mail Address

Include all the items that you want to appear on the business card. Items specific to each person will populate with that person's personal information when the business card downloads. Other items, such as the Business Fax number, might be the same for everyone in the organization.

Once the business card is created with sample information, click Business Card in the contact item Ribbon to open the Electronic Business Card (EBC) editor.

In the editor, design the business card to include the layout and features. For example, you can import a corporate logo by clicking Change in the Card Design area. Adjust the image layout, area, and alignment until your logo appears in the right place on the card.

Adjust the text fields so that text appears in the desired order and is the correct size and color. You can also change the background color.

Click Save and Close to save your changes.

Next you save the card as a file on the Web server that provides the Web site where people preview and download business cards.

To save an Electronic Business Card as a file on the Web server

1. Click the contact you created to select it.

2. On the File menu, click Save As.

3. In the Save in list, browse to a folder on your Web server where your templates will reside.

4. In the File name box, type a descriptive name for the file, such as office.vcf.

5. In the Save as type list, click vCard Files.

If you have more than one business card design, you can help people decide which card to download by providing a preview image of the business card templates.

To provide a preview image of a business card template

1. In Outlook, open the Contact item that contains the business card you designed and that you want to use as a template.

2. Right-click the business card image in the open Contact item.

3. In the context menu, click Copy Image.

4. In Microsoft Paint, on the Tools menu, click Edit.

5. Click Paste to paste the preview image.

6. On the Tools menu, click File.

7. Click Save and select the folder where you saved your vCard earlier.

By creating a Class Library, your project is configured to compile to an assembly. The compiled assembly can later be copied to the Global Assembly Cache (GAC). In order for EBCDeploymentExample.aspx and EBCDeploymentExample.aspx.cs to work together in SharePoint, EBCDeploymentExample.aspx must reference an assembly in the GAC that contains the compiled C# code from EBCDeploymentExample.aspx.cs.

To create a new C# assembly project in Visual Studio

1. In Visual Studio, in the File menu, click New, and click Project.

2. On the New Project dialog, in the Project types: area, click Visual C#.

3. In the Templates: area, click Class Library.

4. In the Name: field, type a name for the project (for example, EBCDeploymentExample) and specify a location or use the default location.

5. Click OK.

   

In order for the compiled assembly to be trusted in SharePoint, it must be signed with a strong name key. You can sign the compiled assembly by using the strong name key provided with the sample solution in the ExampleAssembly.snk file, or you can create your own strong name key.

To sign a compiled assembly with the strong name key provided in the sample

1. In Visual Studio, go to Solution Explorer.

2. Right-click EBCDeploymentExample, and click Properties.

3. On the Signing tab, select the Sign the assembly check box.

4. In the Choose a strong name key file: drop-down list, click <Browse...>.

5. In the Open File dialog box, browse to the ExampleAssembly.snk file and click Open.

6. In the File menu, click Save to save the change.

   

For more information about strong name keys and signing assemblies, see the following resources: .NET Framework Developer's Guide: Creating Assemblies and .NET Framework Developer's Guide - How to: Sign an Assembly with a Strong Name.

To customize the example solution to work in your environment, you must provide the server code with the following information:

• The location of the templates to display on the Electronic Business Cards page.

• The format of the thumbnail images that correspond to each business card. This format is the extension you used when saving the business card previews; for example, .jpg.

• The URL of the SharePoint site on which this solution will run.

The SharePoint Web.Config file is a convenient way to make this information available to the server code. The Web.Config is located in the SharePoint site's Home directory. To find a SharePoint site's Home directory, follow the procedure earlier in this topic, To locate the home directory of a SharePoint site, in the section Working with the SharePoint sample solution: overview.

Copy the parameters in the Web.Config file included in the sample solution you downloaded to the appSettings block in your SharePoint Web.Config file. Change the value of siteURL to the URL of your local SharePoint site. If necessary, update values for the templatePath and templateFormat settings.

<configuration>

...

</appSettings>

<add key="templatePath" value="~/_layouts/Templates" />

<add key="templateFormat" value="jpg" />

<add key="siteURL" value="http://example" />

...

</appSettings>

...

</configuration>

In order for the sample solution to work correctly, you must add certain references to the solution. Add the following references to your solution in Visual Studio by right-clicking the EBCDeploymentExample project and clicking Add reference…:

• System

• System.Configuration

• System.Drawing

• System.Web

• Microsoft.SharePoint

• Microsoft.Office.Server

The sample solution uses SharePoint User Profiles as the data source for employee contact information. The following section provides detailed information about using User Profiles in the sample application. Working with User Profiles is more convenient if you include specific references in the code. Add the following to EBCDeploymentExample.aspx.cs:

using System;

...

using Microsoft.SharePoint;

using Microsoft.Office.Server.UserProfiles;

SharePoint User Profiles provide a consistent application programming interface (API) for accessing SharePoint user data, regardless of the original data source (for example, Active Directory or an LDAP directory). In the sample solution, User Profiles provide the employee contact information for completing a business card.

Perform the following steps to retrieve the employee contact information and populate a business card:

1. Locate the SharePoint User Profile for the employee who has chosen a business card to download.

2. Create properties for each item (name, job title, and so on).

3. Extract the value for each item in the UserProfile.

First, find the user's SharePoint profile. See the PopulateCard() function in the sample solution.

// Obtain the location of this SharePoint site.

String siteURL = ConfigurationManager.AppSettings["siteURL"];

// Create a Profile Manager for this site.

UserProfileManager profileManager = new UserProfileManager(Microsoft.Office.Server.ServerContext.GetContext(new SPSite(siteURL)));

// Find the identity of the user accessing this page.

string sAccount = this.User.Identity.Name;

// Get the SharePoint profile for the user with the given identity.

UserProfile user = profileManager.GetUserProfile(sAccount);

Next, create the properties for each item.

UserProfileValueCollection givenName = null;

UserProfileValueCollection lastName = null;

UserProfileValueCollection jobTitle = null;

UserProfileValueCollection email = null;

UserProfileValueCollection phone = null;

UserProfileValueCollection company = null;

Retrieve the values for the properties from the UserProfile. Properties that are not included in UserProfiles by default can be included in UserProfiles when SharePoint synchronizes with the source of the user data. For example, "company" is not a default UserProfile property. In this code sample, "company" is mapped to the Company field in the directory that provides SharePoint with employee contact data.

givenName = user[PropertyConstants.FirstName];

lastName = user[PropertyConstants.LastName];

jobTitle = user[PropertyConstants.Title];

email = user[PropertyConstants.WorkEmail];

phone = user[PropertyConstants.WorkPhone];

company = user["company"];

For more information about defining additional SharePoint UserProfile properties, see Personalization Services in SharePoint Products and Technologies.

It is straightforward to configure new pages hosted on a SharePoint site to follow the look and feel of the site. By specifying a Master Page File and then adding asp:Content sections for the header, footer, and any other panes common to pages on your SharePoint site, the new page fits seamlessly with the rest of the site.

Note that in order for a page hosted by SharePoint to access a compiled assembly (such as EBCDeploymentExample.aspx), the page must reference the name, version, and public key token for the assembly. You specify these values by using the Inherits parameter, as shown in the following example.

Both the Master Page File and Inherits parameters are set in the Page tag at the top of EBCDeploymentExample.aspx.

<%@ Page Language="C#" MasterPageFile="~/_layouts/simple.master" ValidateRequest="False" Inherits="EBCDeployment.Example, EBCDeploymentExample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0bac7bedd8e30aa1" %>

The content sections specify which standard SharePoint components follow a SharePoint site template. The following content section illustrates how you can follow the site template.

<asp:Content ID="PageTitle" ContentPlaceHolderId="PlaceHolderPageTitle" runat="server">

<SharePoint:EncodedLiteral ID="EncodedLiteral1" runat="server" text="Electronic Business Cards" EncodeMethod='HtmlEncode'/>

</asp:Content>

To host the new page in SharePoint, you place the page in the SharePoint LAYOUTS virtual directory. To do this, copy the EBCDeploymentExample.aspx file to the following folder:

1. <SystemDrive> :\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS

   Now users can access the page at the following location:

2. http:// example /_layouts/EBCDeploymentExample.html.

   Where example is the name of your SharePoint site.

The last steps in implementing the SharePoint sample solution are to compile the assembly, then copy the assembly to the Global Assembly Cache (GAC), where EBCDeploymentExample is configured to access it. Copy the compiled assembly—EBCDeploymentExample.dll—from <project folder> \bin\debug to the GAC, which is located in <SystemDrive> :\windows\assembly. If you compile in release mode, the folder will be bin\release instead of \bin\debug.

To copy your assembly to the new folder, open both folders in Windows Explorer and drag the .dll file from \debug folder to the GAC folder.

Now you can navigate to http://YourSharePointURL/_layouts/EBCDeploymentExample.aspx to explore the sample solution.

To begin working with the sample .NET solution provided in the download package, open a local Web site in Microsoft Visual Studio (VS) 5.0 and navigate to the folder that contains the sample solution. When you open an existing Web site in VS, the VS project recognizes the relationship between the EBCDeploymentExample.aspx and EBCDeploymentExample.aspx.cs files. The Web site's configuration is automatically imported from the sample solution's Web.config file.

To use an existing Web site with the sample solution in Visual Studio

To customize the example solution to work in your environment, you must provide the server code with the following information:

• The location of the templates to display on the Electronic Business Cards page.

• The format of the thumbnail images that correspond to each business card. This format is the extension you used when saving the business card previews; for example, .jpg.

• The folder path of the Active Directory that provides the employee data for personalizing the business card templates.

• The method of authentication; for example, Windows authentication.

• Credentials for impersonation.

You also might choose to provide assembly references for the Visual Studio compiler. References required for the sample solution are provided in the "Adding required references" instructions in a later section.

The Web.Config file of the Web site is a convenient way to make this information available to the server code. Open the Web.Config file in the sample solution to set the parameter values for your configuration.

<configuration>

<appSettings>

<add key="templatePath" value="~/Templates"/>

<add key="templateFormat" value="jpg"/>

<add key="ADPath" value="LDAP://ServerName.exchange.yourdomain.com/DC=exchange, DC=yourdomain,DC=com "/>

</appSettings>

<system.web>

<authentication mode="Windows"/>

<identity impersonate="true" userName="username"password="password"/>

</system.web>

</configuration>

It is important to specify a valid Active Directory for the ADPath parameter. The userName and password parameters represent the username and password for the Web site's service account. A more secure way to provide credentials is to encrypt the values instead of leaving them as clear text. For more information about encrypting credentials, see How to use the ASP.NET utility to encrypt credentials and session state connection strings.

You must add specific references to the solution to enable the sample solution to work correctly. In Visual Studio, right-click EBCDeploymentExample project and click Add reference… to add each of the following references to your solution.

• System

• System.Configuration

• System.DirectoryServices

• System.Web

The System.DirectoryServices reference is required for connecting to and querying Active Directory.

Working with Active Directory is more convenient if you include specific references in the code. Add the following reference to EBCDeploymentExample.aspx.cs:

...

Using System.DirectoryServices;

To connect to Active Directory, create a DirectoryEntry parameter that includes the Active Directory path variable ( ADPath ):

DirectoryEntry de = new DirectoryEntry(ConfigurationManager.AppSettings["ADPath"]);

You use the DirectorySearcher function to query Active Directory for employee contact information. Create the function using the DirectoryEntry created in the previous section.

DirectorySearcher ds = new DirectorySearcher(de);

Next, determine the identity of the user visiting the Web site. Remove the domain from the user's identity, and ensure that data for only the user with the correct alias is retrieved. This example assumes that the e-mail address format in your organization is alias@yourdomain.com.

string longAlias = this.User.Identity.Name;

int start = longAlias.IndexOf("\\"); // Parse away the domain name.

int end = longAlias.Length; // Get the length of the alias.

string alias = longAlias.Substring(start + 1, (end - (start + 1)));

ds.Filter = "(mailnickname=" + alias + ")";

Next, specify the properties of the Outlook contact (vCard) that will be retrieved, so it can be updated later.

ds.PropertiesToLoad.Add("givenName"); // Get the given name.

ds.PropertiesToLoad.Add("sn"); // Get the surname.

ds.PropertiesToLoad.Add("title"); // Get the job title.

ds.PropertiesToLoad.Add("mail"); // Get the email address.

ds.PropertiesToLoad.Add("telephoneNumber"); // Get the phone number.

ds.PropertiesToLoad.Add("company"); // Get the company name.

Search the directory for the user with the specified alias and store the results in a SearchResultCollection.

SearchResultCollection data = ds.FindAll();

After you retrieve the contact information from Active Directory, you use the information to personalize the employee business card.

To access contact information in Active Directory query results, first create properties for the contact information.

PropertyValueCollection givenName = null;

PropertyValueCollection lastName = null;

PropertyValueCollection jobTitle = null;

PropertyValueCollection email = null;

PropertyValueCollection phone = null;

PropertyValueCollection company = null;

Then find the values for the properties in the result set.

// In case invalid data was returned, try...

try

{

// Get the properties needed for the EBC.

DirectoryEntry resultEntry = data[0].GetDirectoryEntry();

givenName = resultEntry.Properties["givenName"];

lastName = resultEntry.Properties["sn"];

jobTitle = resultEntry.Properties["title"];

email = resultEntry.Properties["mail"];

phone = resultEntry.Properties["telephoneNumber"];

company = resultEntry.Properties["company"];

}

catch (Exception)

{

// Create a writer for error output.

StreamWriter sw = new StreamWriter(Response.OutputStream);

sw.WriteLine("Error updating template!");

sw.Close();

}

When the employee downloads the business card, it is now populated with the employee's contact information.