How to Write a Custom Webpart using Service Manager Base Webpart

First published on TECHNET on Feb 07, 2012

This blog post was written up by Martha Amirzadeh, one of the senior developers on the System Center engineering team.  Thanks Martha!

=========================================

Before we start on how to write a custom Webpart let’s find out why would you want to create such a Webpart. Here are few features you will get out of box if you leverage the Service Manager Base Webpart:

• Messaging component between the Webpart and the referenced Silverlight module
• Customizable Webpart with Edit Pane in SharePoint (Optional)
• Configuration component to read Application Settings from SharePoint Web.Config
• Localization pipeline for both the referenced Silverlight module and the Edit Pane
• Detailed logs about rendering of the Webpart, referenced Silverlight module and Edit Pane
• Tracing component with different levels for trouble-shooting
• Enabling QueryString parsing in the referenced Silverlight module

Service Manager ships the Base Webpart as part of this assembly:

Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseWebPart

In order to access this assembly and its related components, you will need to install the Service Manager SharePoint Site. You don't have to use this Service Manager SharePoint site later, it is just needed so you can access required files in the next steps.

After you are done with the installation of the Service Manager SharePoint site, here are the steps to create a custom Webpart using Service Manager Base Webpart:

1. Create your Webpart

a. Add a new SharePoint project using “Empty SharePoint Project” template

b. Add a reference to “Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseWebPart.dll” in your SharePoint project. This assembly is GAC’ed on your machine where you installed Service Manager Portal.

Here is how to copy this assembly from GAC to your local folder. Use below command to create a shortcut to the GAC location on your machine:

SUBST G: C:\WINDOWS\ASSEMBLY

Then navigate to G drive and search for “Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseWebPart.dll”, then copy the file to your local folder.

c. Add a new class to be your Webpart class called “your Webpart.cs”

d. Add these using statements to your Webpart class

using System.Web.UI.WebControls.WebParts;
using Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseWebPart;
using Microsoft.SharePoint.WebPartPages;

e. Derive your Webpart class from Service Manager “BaseWebPart” class in Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseWebPart.dll

f. Override the method below to specify the name of the Silverlight module you want to reference:

protected override String GetXAPName()
{
return "YourSilverlightModule.xap";
}

g. Override the method below if you want to pass parameters to your Silverlight module:

protected override void AddInitialParameters()
{
StringBuilder queryString = new StringBuilder();
queryString.Append(BuildQueryString("PageTitleVisibility", this.PageTitleVisibility));

this.SilverlightCotrol.InitParameters = this.SilverlightCotrol.InitParameters +
queryString.ToString();
}

Note that you will need to add new parameters if you want to leverage Layout Customization explained in the next step.

2) Leverage Layout Customization feature in your Webpart (Optional)

a. Derive your Webpart class from IWebEditable

[ToolboxItemAttribute(false)]
public class KnowledgeArticleWebPart : BaseWebPart.BaseWebPart, IWebEditable

b. Implement IWebEditable members

EditorPartCollection IWebEditable.CreateEditorParts()
{
// add you code here
}
object IWebEditable.WebBrowsableObject
{
get { return this; }
}

c. Add new properties for the fields you want to be shown in the Edit Pane of your Webpart

[WebBrowsable(true), WebPartStorage(Storage.Shared), Localizable(true)]
public String PageTitleVisibility
{
get;set;
}

d. Add a new class called “your Webpart EditorPart.cs”

e. Derive your “WebpartEditorPart” class from Service Manager “BaseWebpartEditorPart” class in Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseWebPart.dll

public class KnowledgeArticleEditorPart : BaseWebPartEditorPart

f. Override the method below in the “WebPartEditorPart” class to add a new Edit Pane property

protected override void CreateAdditionalChildControls(ControlCollection controls)
{
PageTitleEditorPart = new LabelEditorPart(LocalizationManager.GetLocalizedString(“PageTitle”));
controls.Add(PageTitleEditorPart.RootControl);
}

Note that you are using the LocalizationManager class which will look up string resources using the key provided (example above: “PageTitle”. You can add your strings to the StringResources files in AppGlobalResources folder of the parent site of your Sharepoint site.

To find the AppGlobalResources folder location of your SharePoint site’s parent site, explore the parent site in IIS and it should take you to a path like this: “C:\inetpub\wwwroot\wss\VirtualDirectories\(number)\App_GlobalResources”

(Note: the (number) in the path above is a random number generated for the SharePoint site.)

g. Override the method below in the “WebPartEditorPart” class to sync new property

protected override void SyncAdditionalChanges(WebPart webPartToEdit)
{
KnowledgeArticleWebPart knowledgeWebPartToEdit = (KnowledgeArticleWebPart)webPartToEdit;
if (knowledgeWebPartToEdit != null)
{
EditorPartHelper.SetVisibility(PageTitleEditorPart.Visibility, webPartToEdit.PageTitleVisibility);
}
}

h. Override the method below in the “WebPartEditorPart” class to apply changes

protected override void ApplyAdditionalChanges(WebPart webPartToEdit)
{
KnowledgeArticleWebPart knowledgeWebPartToEdit = (KnowledgeArticleWebPart)webPartToEdit;
if (knowledgeWebPartToEdit != null)
{
webPartToEdit.PageTitleVisibility = EditorPartHelper.GetVisibility(PageTitleEditorPart.Visibility);
}
}

3) Configure your Webpart

a. Add your Webpart identification to the SafeControl list in the web.config of the parent site of your SharePoint site.

<SafeControl Assembly="your SharePoint assembly name, Version=7.0.5000.0, Culture=neutral,

PublicKeyToken=your SharePoint assembly public key token” Namespace="Your Webpart Namesspace"

TypeName="your Webpart class name" Safe="True" SafeAgainstScript="True" />

Note: Make sure your SharePoint assembly version and PublicKeyToken match your SharePoint assembly that will be GAC’ed on the machine in later steps.



b. Create a new file webpart definition file called “yourwebpart.webpart” and edit it as shown below to add reference to your compiled assembly:

<?xml version="1.0" encoding="utf-8"?>
<Webparts>
<Webpart xmlns="http://schemas.microsoft.com/Webpart/v3">
<metaData>
<type name="Your Webpart class name, YourWebpartAssemblyName, Version=7.0.5000.0, Culture=neutral, PublicKeyToken= your SharePoint assembly public key token" />
<importErrorMessage>$Resources:core,ImportErrorMessage;</importErrorMessage>
</metaData>
<data>
<properties>
<property name="Title" type="string">Your Webpart</property>
<property name="Description" type="string">Your Description</property>
</properties>
</data>
</Webpart>
</Webparts>

Note: make sure your Sharepoint assembly version and publicKeyToken match your SharePoint assembly that will be GAC’ed on the machine in later steps.

4) Deploy your Webpart

a. Add you compiled SharePoint assembly to GAC following MSDN instructions here: http://msdn.microsoft.com/en-us/library/ex0ss12c.aspx

b. Add your Webpart’s strings to the StringResources files in GlobalResources folder of your SharePoint site's parent site.

To find GlobalResources location of your SharePoint site’s parent site, explore the parent site in IIS and it should take you to a path like this: “C:\inetpub\wwwroot\wss\VirtualDirectories\(number)\App_GlobalResources”

(Note: the (number) in the path above is a random number generated for the SharePoint site.)

c. Deploy your new Webpart to SharePoint site

To deploy your Webpart, navigate to the Webpart Gallery of your SharePoint site’s parent site, first select “Site Actions -> Site Settings” of the parent site and then navigate to “Galleries/Web parts”. Then click on Documents and it should take you here:

Then click on “Upload Document” to add your Webpart “yourWebpart.webpart” to your SharePoint Webpart Gallery. Once you deployed the Webpart, you can then add it to any page on your SharePoint site or SMPortal SharePoint site.

Great! You are done with creating, configuring and deploying a custom Webpart. However, here are few more details on how to create, configure and deploy a new Silverlight module to reference in your Webpart.

5) Create, Configure and deploy a new Silverlight Module

a. Create a new Silverlight project in Visual Studio using “Silverlight Application” Template.

b. Add reference to required assemblies in your project

To find required assemblies navigate to install location of Service Manager Web Content Server: “C:\inetpub\wwwroot\SMPortal\ContentHost\ClientBin\”, then copy below assemblies to a local folder.

• Rename any “.xap” file like “KnowledgeArticleSilverlightModule.xap” to “.zip”, then open the “.zip” file and copy below files:





• ““Microsoft.Practices.Prism.dll”,



• “Microsoft.Practices.Prism.UnityExtensions.dll”,



• “Microsoft.Practicses.ServiceLocation.dll”,



• “Microsoft.Practicses.Unity.Silverlight.dll”,



• “System.Reactive.dll”,



• “System.ServiceModel.dll”,



• “ServiceReferences.ClientConfig”





• Open “Core.zip” and copy “Microsoft.EnterpriseManagement.Presentation.Core.dll”



• Open “DataAccess.zip” and copy “Microsoft.EnterpriseManagement.Presentation.DataAccess.dll”



• Open “Instrumentation.zip” and copy “Microsoft.EnterpriseManagement.Instrumentation.dll”



• Open “BaseSilverlightModule.zip” and copy “Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule.dll”



• Open “BasicResources.zip” and copy “Microsoft.EnterpriseManagement.ServiceManager.Portal.BasicResources.dll”

c. Add reference to test related assembly in your project (Optional)

To find these assemblies navigate to install location of Service Manager Web Content Server: “C:\inetpub\wwwroot\SMPortal\ContentHost\ClientBin\”, then copy below assemblies to a local folder.

Rename any “.xap” file like “KnowledgeArticleSilverlightModule.xap” to “.zip”, then open the “.zip” file and copy “Microsoft.VisualStudio.TestTools.UITest.Extension.SilverlightUIAutomationHelper.dll”

Note that you will need this assembly only if you want to write UI automation test cases for your new Silverlight module.

d. Add a reference to Styles/Custom Controls assemblies (Optional)

To find these assemblies navigate to install location of Service Manager ContentHost: “C:\inetpub\wwwroot\SMPortal\ContentHost\ClientBin\”, then copy below assemblies to a local folder.

• Microsoft.EnterpriseManagement.ServiceManager.Portal.AdvancedResources.dll: open “AdvancedResources.zip” and copy it from there.



• Microsoft.EnterpriseManagement.ServiceManager.Portal.FormControls: open “FormControls.zip” and copy it from there.



• Microsoft.EnterpriseManagement.ServiceManager.Portal.CustomControls: open “CustomControls.zip” and copy it from there.



• Microsoft.EnterpriseManagement.ServiceManager.Portal.ToolkitResources: open “ToolkitResources.zip” and copy it from there.



• Microsoft.EnterpriseManagement.ServiceManager.Portal.WizardResources: open “WizardResources.zip” and copy it from there.



• System.Windows.Controls.Layout.Toolkit.dll: rename any “.xap” file like “KnowledgeArticleSilverlightModule.xap” to “.zip”, then open the “.zip” file and copy it from there.



• System.Windows.Controls.Toolkit.Internals.dll: rename any “.xap” file like “KnowledgeArticleSilverlightModule.xap” to “.zip”, then open the “.zip” file and copy it from there.

Note that you will only need these assemblies if you want to make use of specific custom controls or styles defined by Service Manager UI, the alternative would be create your own specific styles and custom controls.

e. Derive “App” class in your Silverlight project from “BaseApp” class in Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule.dll

f. Edit App.xaml to leverage BaseApp class

<CommonSilverlightModule:BaseApp
xmlns:CommonSilverlightModule="clr-namespace:Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule;assembly=Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule"
x:Class="App"

g. Edit the Startup event in your Silverlight project and call “Base.AppStartup” in Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule.dll

protected void Application_Startup(object sender, StartupEventArgs e)
{
base.AppStartup(sender, e);
}

h. Override “CreateShell” in your Silverlight project to provide the “RootVisual”

protected override void CreateShell()
{
this.RootVisual = new Shell();
}

i. Derive “Shell” class in your Silverlight project from “BaseShell” class in Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule.dll

j. Edit the Shell.xaml class to leverage BaseShell class

<CommonSilverlightModule:BaseShell
xmlns:CommonSilverlightModule="clr-namespace:Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule;assembly=Microsoft.EnterpriseManagement.ServiceManager.Portal.BaseSilverlightModule"
xmlns:local="clr-namespace:Your Silverlight Module Namespace "
x:Class=" Shell"

k. Access parameters that are passed to your Silverlight module by your Webpart, using StartupParameters shown below:

StartupParameters.GetParameter("SearchCriteria");

Note that you can leverage this class to access Layout Customization parameters that are passed from your Webpart to your Silverlight module as well. To learn how to pass parameters to your Silverlight module from your Webpart read step g of part 1.

l. Copy your Silverlight compiled “.xap” file to ClientBin folder of Service Manager portal.

To find the ClientBin folder navigate to install location of Service Manager Web Content Server: “C:\inetpub\wwwroot\SMPortal\ContentHost\ClientBin\”