IT War Room - Technical Stuff

Sharepoint webparts

How Web Parts Work

• User Controls   These controls consist of two parts:
  • A file that has an .ascx file name extension, and that contains sample HTML.
  • The program code that executes on the Web server. This code, plus the code for all other ASP.NET pages and user controls in the same application, is usually compiled into a single DLL that resides in the application's bin folder. However, it can also reside in source form, within the .ascx file.
  Most developers find user controls fairly easy to create. This is because the developer (or even a Web designer) can use a visual designer to create the sample HTML, and because programming a user control is very much like programming an ordinary ASP.NET page.
  User controls, however, can be difficult to deploy widely. When a change occurs, someone must:
  
  1. Identify each Web site that uses the control.
  2. Install the new .ascx and source code files in each Web site.
  3. Recompile all the source code in each Web site.
  4. Copy the revised .ascx file and the recompiled code to each production Web site.
  If Web Parts were user controls, deploying a new Web Part (or upgrading one) would require recompiling and reinstalling the program code for every SharePoint site that uses the Web Part. That's why Web Parts aren't user controls.
• Custom Controls   These controls consist entirely of program code. There's no HTML template like the .ascx file for a user control, and consequently no way of using a WYSIWYG editor to design its HTML. A programmer must write code that emits each scrap of HTML that the control needs in order to display output.The advantage of custom controls lies in deployment. Each custom control (or, if you choose, each logical group of custom controls) has its own DLL, and at your option you can install this once per physical server or once per virtual Web server. This is the model that Web Parts use. All Web Parts are, in fact, ASP.NET custom controls.

class WebPart1 : Microsoft.SharePoint.WebPartPages.WebPart 
{
// Your custom code goes here. 
}

• CreateChildControls   The WebPart class calls this method to create child server controls that the Web Part will later convert to HTML.
• RenderWebPart   The WebPart class calls this method to render (that is, create) the HTML that the Web Part will display.

Note   If you've ever written ASP.NET custom controls that aren't Web Parts, you're probably accustomed to overriding the Render method rather than the RenderWebPart method. In a Web Part, however, the Render method creates only the chrome (the Web Part's title bar and border, for example). The RenderWebPart method creates the HTML that appears in the body of the Web Part.

class WebPart1 : Microsoft.SharePoint.WebPartPages.WebPart 
{ 
//  Global declarations go here.
protected override void CreateChildControls ()
    {
//      Code to create a list of Web or HTML server 
//      controls goes here
    }
protected override void RenderWebPart(HtmlTextWriter output) 
    {
//      Code to render the list of Web or HTML server 
//      controls goes here
    }
}

• Page_Load normally fires when ASP.NET finishes loading the page's server controls into memory. In a Web Part, however, ASP.NET doesn't load the server controls; your own CreateChildControls method does that. So, you may as well put your code in the CreateChildControls method, or call it from within that method.
• Within a Page_Load event handler, programmers normally use the IsPostBack property to differentiate between the initial display of a page and a subsequent submission. But in the case of Web Parts, a postback also occurs when a team member uses a browser to add, remove, or reconfigure any Web Part on the page.This makes sense if you stop and think about it. There are many times—such as when you use a browser to add a Web Part to a page—when a round trip to the server clearly occurs. However, these aren't normal form submissions, and you shouldn't process any data that form fields might contain.

Starting a New Web Part Project

1. If you're not going to run Visual Studio on the SharePoint server, copy the Microsoft.SharePoint.dll file from the server to the Visual Studio machine. By default, this file resides at:C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\ISAPI
   You can copy this file to any folder you like on the Visual Studio machine; just remember its location and don't delete it by accident.
2. On the machine where Visual Studio is installed, browse http://www.microsoft.com/technet/downloads/sharepnt.mspx.
3. When the Downloads for SharePoint Products and Technologies page appears, click the hyperlink titled SharePoint Products And Technologies Templates: Web Part Templates For Visual Studio .NET.
4. When the Download Details page appears, click the Download button and save the resulting file (WebPartTemplatesforVSNetSample2.exe) to a temporary location.
5. Run the file you downloaded in step 4. When the WinZip Self-Extractor dialog box appears, choose a folder for the unzipped setup files and then clickUnzip.
6. Open the folder you specified in step 5 and run the setup.exe program.
7. Click Next on the opening page of the setup wizard, and then I Agree and Next on the License Agreement page.
8. On the third wizard page, select the check box for each set of templates you want to install. The choices are Visual C and Visual Basic .NET. The examples in this book are all in C, but feel free to install both.
9. If the wizard page shown in Figure 19-1 appears, enter the folder location where you saved the Microsoft.SharePoint.dll file you copied in step 1.
10. Click Next and Finish to perform the installation.

1. Start Visual Studio, choose New from the File menu, and then choose Project.
2. When the New Project dialog box shown in Figure 19-2 appears, apply the following settings and then click OK:
   • Project Types   Select either Visual Basic Projects or Visual C Projects. This presumes, of course, that you installed the corresponding templates in the previous procedure. The examples in this book are all in C.
   • Templates   Choose Web Part Library.
   • Name   Specify the name of the Visual Studio project. By default, this will also be the name of the DLL that deploys your Web Part. Visual Studio will also create a solution having this name.
   • Location   Specify a folder where the Visual Studio project and solution will reside.
   
   
   Figure 19-2. The Web Part library template initializes a project for creating Web Parts.
3. Visual Studio will create the new project and open the class file for a Web Part named WebPart1. Figure 19-3 illustrates this result.
   
   Figure 19-3. This new Web Part project is ready to receive custom code.
4. Unless you want your Web Part to be named WebPart1:
   1. Choose Find And Replace from the Edit menu, and then choose Replace.
   2. When the Replace dialog box appears, set Find What to WebPart1, Replace With to the name you want, and then click Replace All.
   3. Click the close box in the Replace dialog box, and then in the WebPart1.cs file. When Visual Studio prompts Save Changes To The Following Items?, click Yes.
   4. Right-click the WebPart1.cs file in Solution Explorer, choose Rename from the shortcut menu, and change the file name base to the name you assigned in step 4.2.

      Tip   If the Solution Explorer window isn't visible, press CTRL+ALT+L or choose Solution Explorer from the View menu.

Writing Web Part Output

protected override void RenderWebPart(HtmlTextWriter output)
{
}

• You can call the Write method of the HtmlTextWriter object named output. (Note that the RenderWebPart method receives a pointer to this object as an argument.) For example, to write a paragraph that displays the value of a variable named strMsg, you would code:
  
  

  output.Write("<p>" + SPEncode.HtmlEncode(strMsg) + "</p>");
  

  SPEncode.HtmlEncode is a method that converts reserved HTML characters to character entity references. For example, it converts < to &lt; and > to &gt;.
• You can call the RenderChildren method, specifying the HtmlTextWriter object named output as a parameter. Here's an example:
  
  

  RenderChildren(output);
  

• Each tag you code runat="server" creates a corresponding object in the Controls collection.
• Any content that appears between tags coded runat="server" appears in the Controls collection as a single System.Web.UI.LiteralControl object.

HtmlGenericControl prgMsg;             // Declare variable. 
prgMsg = new HtmlGenericControl("p");  // Create object. 
prgMsg.InnerText = strMsg;             // Set value inside <p>
                                       // and </p>. 
Controls.Add(prgMsg);                  // Add to Controls 
                                       // collection.

Adding Layout Controls and Content

• System.Web.UI.HtmlControls   These controls correspond very closely to standard HTML elements. For a complete list, see System.Web.UI.HtmlControls.To use these controls, the source code for your Web Part should contain this statement:
  
  
  

  using System.Web.UI.HtmlControls;
  

  Otherwise, you'll need to type the entire namespace every time you refer to one of its class names.
• System.Web.UI.WebControls   Controls in this group are either:
  • Enhanced versions of HTML server controls. Unlike the HtmlSelect control, for example, the ListBox Web server control can trigger immediate postbacks.
  • Entirely new elements, such as a calendar, an ad rotator, and the ubiquitous DataGrid control.
  For a list of these controls, see System.Web.UI.WebControls.
  To use these controls, the source code for your Web Part should contain this statement:
  
  
  

  using System.Web.UI.WebControls;
  

HtmlGenericControl prgMsg;
prgMsg = new HtmlGenericControl("p");
prgMsg.InnerText = strMsg;
Controls.Add(prgMsg);

protected override void CreateChildControls ()
   {
prgMsg = new HtmlGenericControl("p");
Controls.Add(prgMsg);     
   }

HtmlGenericControl prgMsg; 
 
public void MsgLoad(object sender, EventArgs e) 
{ 
    string strMsg; 
    strMsg = "Help! I'm a prisoner in a Web Part!"; 
    EnsureChildControls(); 
    prgMsg.InnerText = strMsg; 
} 
protected override void CreateChildControls () 
{ 
    prgMsg = new HtmlGenericControl("p"); 
    prgMsg.Load += new EventHandler(MsgLoad); 
    Controls.Add(prgMsg); 
}

• The statement on line 13 establishes MsgLoad as an onLoad event handler for the prgMsg object. This means that the MsgLoad method on line 3 will run as soon as the prgMsg object finishes loading.
• The EnsureChildControls method on line 7 ensures that the CreateChildControls method has finished executing. If not, it waits for that method to complete. This avoids the embarrassing moments that occur when a method tries to manipulate an object that CreateChildControls hasn't created yet.
• The assignment statement on line 8 stores a value into the paragraph control created on line 12.
• The declaration of the prgMsg variable appears on line 1, which is outside both the MsgLoad method and the CreateChildControls method. This makes theprgMsg available within both of those methods.

Manipulating SharePoint Objects

• SharePoint.SPSite   Represents a SharePoint site collection. Its properties and methods provide access to the collection's subsites, templates, cross-site groups, and so forth.Remember: an SPSite object doesn't represent a site. Its properties and methods pertain to an entire site collection, and not to any one Web site.
• SharePoint SPWeb   Represents an individual SharePoint site: either a top-level Web site or a subsite. It provides access to all of the site's lists, files, folders, Web Parts, and other objects.
• SharePoint.SPList   Represents a SharePoint list. The term list, in this context, is very broad. It includes not only generic lists, but also surveys, discussion boards, document libraries, picture libraries, and form libraries.

SPWeb spwCurr = SPControl.GetContextWeb(Context);

SPSite spsColl = SPControl.GetContextSite(Context);

• spwCurr.CurrentUser.LoginName   Returns the current team member's login name, such as interlacken\karen.M
• spwCurr.CurrentUser.Name   Returns the current team member's personal name, such as Karen Archer.
• spwCurr.Name   Gets or sets the name of the current site.
• spwCurr.Lists   Returns a collection of SPList objects, one for each list in the site.
• spwCurr.Delete()   Deletes the current site.

(SPList splCurr in spwCurr.Lists) {
// splCurr will point to a different list during each iteration 
}

SPList splNrTwo = spwCurr.Lists[1];

SPList splSharedDocs = spwCurr.Lists["Shared Documents"];

spwCurr.Lists.Add("Swamp Dwellers",
"Ducks, Frogs, Gators, and other creepy critters", 
SPListTemplateType.Contacts);

Using the ASP.NET Event Model

Protected override void OnLoad(EventArgs e) 
{
// Your code goes here
base.OnLoad(e); 
}

lstPriority = new DropDownList();
lstPriority.SelectedIndexChanged
    += new EventHandler(Priority_Change);
lstPriority.AutoPostBack = true;

private void Priority_Change(object sender, EventArgs e) 
{
// Your code goes here. 
}

• The Load and PreRender event handlers display simple messages, and fire for each execution.
• The following code creates the drop-down list:
  
  

  lstPriority = new DropDownList();
  lstPriority.SelectedIndexChanged
      += new EventHandler(Priority_Change);
  lstPriority.AutoPostBack = true;
  
  

  And this code populates the list items:
  
  
  

  (lstPriority.Items.Count < 1) 
  {
      lstPriority.Items.Add(new ListItem("High","1"));
      lstPriority.Items.Add(new ListItem("Medium","2"));
      lstPriority.Items.Add(new ListItem("Low","3"));
      litMsgs.Text += "<br>"
         + DateTime.Now.ToLongTimeString()
         + " Priority List Loaded."; 
  }
  
  

  The message Priority List Loaded appears only once in Figure 19-5 because the ASP.NET ViewState mechanism persists the items (and the current selection) from one execution to another.
  The messages Priority Is Now 2 and Priority Is Now 3 appear because the team member changed the selection in the drop-down list box, and this caused an autopostback.
• The message Submit Button Clicked appears because the team member clicked the Submit button. The following code creates this button and specifies aClick event handler named Submit_Click.
  
  

  btnSubmit = new Button();
  btnSubmit.Text = "Submit";
  btnSubmit.Click += new EventHandler (Submit_Click);
  
  

  Here's the code for the event handler:
  
  
  

  Private void Submit_Click(object sender, EventArgs e) 
  {
      EnsureChildControls();
      litMsgs.Text += "<br>"
            + DateTime.Now.ToLongTimeString()
            + " Submit Button Clicked."; 
  }
  
  

• Every time the team member clicks the browser's Refresh button.
• Every time the team member clicks a Submit button or otherwise creates a postback from another Web Part.
• Every time the team members use browser-based design features such as:
  • Switching from shared view to personal view.
  • Entering, using, or exiting browser-based Design mode.
  • Displaying the Add Web Parts task pane.
  • Scrolling through multiple pages in a Web Part gallery.
  • Modifying a Web Part.

Exposing Custom Properties

private const string defaultText = "";
private string text = defaultText;  
[Browsable(true),
    Category("Miscellaneous"),
    DefaultValue(defaultText),
    WebPartStorage(Storage.Personal),
    FriendlyName("Text"),
    Description("Text Property")]
public string Text 
{
    get { return text; }
    set { text = value; } 
}

• Raise an exception in the property's set method. This approach is simple and normally works as you want in both the SharePoint browser interface and in FrontPage. Instead of closing, the property sheet will display the error message from your exception.If, however, your exception occurs when the Web Part's property sheet isn't visible, then the whole page may fail. This can occur, for example, when another control tries to set the property pragmatically.
• Use a Web Part Tool Part, as the next section describes.

Using Web Part Tool Parts

public override ToolPart[] GetToolParts() 
{
    ToolPart[] toolparts = new ToolPart[3];
    toolparts[0] = new CustomPropertyToolPart();
    toolparts[1] = new WebPartToolPart();
    toolparts[2] = new WebPartLibrary2.ToolPart1();
    return toolparts; 
}

• The first is a standard CustomPropertyToolPart object, which displays any custom properties just as the previous section described. If you overrideGetToolParts and omit this entry, no controls for custom properties will appear.
• The second is a WebPartToolPart object, which displays the standard Appearance, Layouts, and Advanced sections of the Web Part's property pane. If you omit this entry, these sections won't appear.
• The third (and each subsequent) is a custom class that you develop separately in the same project, and that inherits theMicrosoft.SharePoint.WebPartPages.ToolPart class.

Providing a Design Time HTML Provider

• To signify that your Web Part class supports the IDesignTimeHtmlProvider interface, append a comma and the interface name to the class declaration. For example, change:
  
  

  public class SimpleWebPart : 
     Microsoft.SharePoint.WebPartPages.WebPart  
  {}
  
  

  to:
  
  
  

  public class SimpleWebPart : 
     Microsoft.SharePoint.WebPartPages.WebPart,
     IDesignTimeHtmlProvider 
  {}
  
  

• Add a public method such as the following to your class:
  
  

  public string GetDesignTimeHtml() 
  {
  return "<p>Any HTML</p>";
  }
  
  

Assigning a Strong Name

1. Identify the folder that contains your Visual Studio Web Part project. The following is a typical path, where <user>is your windows logon ID and <project> is the name of your Visual Studio project.
   
   

   C:\Documents and Settings\<user>\My Documents\Visual Studio 
   Projects\<project>
   

2. On the machine running Visual Studio, open a command prompt.
3. Change to the directory containing the sn.exe file. This is usually one of the following:
   
   

   C:\Program Files\Microsoft Visual Studio .NET\FrameworkSDK\Bin\
   C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin\
   

4. Create a key pair file by running the following command:
   
   

   sn.exe –k "<path>\<project>.snk"
   

   where <path> is the path to your Visual Studio project (from step 1) and <project> is the name of your Visual Studio project.
5. Open your Visual Studio project, and then choose Add Existing Item from the File menu.
6. When the Add Existing Item dialog box appears, find and select the file you created in step 4, and then click Open.
7. In Video Studio, open the AssemblyInfo.cs file for your project.
8. Scroll to the bottom of the file, and change the line
   
   

   [assembly: AssemblyKeyFile("")]
   

   to:
   
   
   

   [assembly: AssemblyKeyFile("..\\..\\<project>.snk")]
   

   where <project> is the name of your Visual Studio project.
   As usual in C literals, a single backslash is an escape character. For example, \n means new line, not a backslash followed by an n. To get a backslash in the literal's value, you have to code two backslashes.
   The path ..\..\ is necessary because the strong name key file resides two directory levels closer to the root than the DLL file Visual Studio creates when it builds your project.
9. Scroll about halfway up the AssemblyInfo.cs file and look for a line like:
   
   

   [assembly: AssemblyVersion("1.0.0.0")]
   

   If this line contains any asterisks, replace them with digits. This will avoid creating a new version number every time you compile the Web Part.
10. Choose Rebuild Solution from the Build menu. This (and every subsequent build) will create a strongly named assembly.

Tip   Whenever the name, version number, or digital signature of a Web Part changes, you have to reinstall the Web Part on each SharePoint server that uses it, and reconfigure each Web Part page that uses it. as a result, most programmers avoid changing these properties.

Deploying Custom Web Parts

• The SharePoint server's Global Assembly Cache (GAC)   This makes the Web Part available to all virtual servers on the same computer, with maximum privileges. However, the assembly must have a strong name. (You must have compiled it with a key pair file.)To install a Web Part this way, drag its .dll file into the C:\Windows\Assembly folder, where C:\Windows is the server's system folder.
• The bin folder of one or more virtual servers   This makes the Web Part available only on those virtual servers where you install it. Assemblies you install this way don't need strong names, but strongly naming your assemblies is always a good idea.Unfortunately, at least through windows SharePoint Services Service Pack 1, this method doesn't work properly on computers running more than one SharePoint content server.

• Install the Web Part manually.   To do this:
  1. Create your own .dwp file.
  2. Copy this .dwp file into the wpcatalog folder at the virtual server's physical root.
  3. Copy the Web Part's .dll into the bin folder at the virtual server's physical root.
  4. Update the <SafeControls> section of the virtual server's web.config file.
• Create and install a Web Part Package.   To take this approach, create a Windows CAB file (with a .wpp file name extension) that contains:
  • A mainfest.xml file describing each file you need to install.
  • Each file you need to install.
• Then, run the following command to install the package:
  
  

  stsadm.exe –o addwppack –filename <filename> –globalinstall -force
  

  where <filename> is the name of the .cab file.
• Use the InstallAssemblies tool.   This tool examines your .dll file, creates the required .dwp file and Web Part Package, and then runs stsadm.exe –o addwppack, all from a graphical interface. In almost every case, this is the easiest, most accurate, and overall best approach.

<trust level="WSS_Minimal" originUrl="" />

• Creating a Basic Web Part
• A Developer's Introduction to Web Parts
• Best Practices for Developing Web Parts for SharePoint Products and Technologies