Building Block: Web Parts
Applies to: SharePoint Foundation 2010
Web Parts are server-side controls that run inside the context of Microsoft SharePoint Foundation site pages. You can use them to customize the user interface (UI) and to edit the content of a site page. Microsoft SharePoint Foundation includes default Web Parts as well as the ability to build custom Web Parts. There are two supported types of Web Parts in SharePoint Foundation. They are referred to as SharePoint and ASP.NET Web Parts. ASP.NET Web Parts use the System.Web.UI.WebControls.WebParts.WebPart base class while SharePoint Web Parts use the Microsoft.SharePoint.WebPartPages.WebPart base class. Both types are supported but the ASP.NET Web Part is recommended for all new projects.
The following sections provide an overview of the different types of Web Parts and the XML that is used with them, and includes links to more in-depth information and walkthroughs.
Object Model for Web Parts
Web Parts in SharePoint Foundation are based on the Microsoft ASP.NET Web Part infrastructure. To create Web Parts for applications that target SharePoint Foundation, you should build custom Web Parts on top of the ASP.NET Web Part infrastructure. However, in a very few cases, you may have to create Web Parts that support SharePoint Foundation features that are not available in the ASP.NET Web Part infrastructure.
ASP.NET Web Parts
The ASP.NET Web Part infrastructure is based on a WebPartManager class that manages the lifetime of Web Part instances at run time.
Each ASP.NET page that uses Web Part controls must contain the following objects in order to support personalization:
Exactly one WebPartManager object that tracks which Web Parts have been added to each particular zone and that stores and retrieves data about how each Web Part has been customized and personalized.
One or more WebPartZone objects, into which Web Parts are placed.
To run SharePoint Foundation Web Parts in an ASP.NET application, you must create an .aspx page that contains exactly one instance of the WebPartManager control and one or more WebPartZone controls. The WebPartManager is responsible for serializing Web Part-related data as well as storing and retrieving it from the database.
The SPWebPartManager and WebPartZone controls manage the serialization of data associated with Web Parts into the appropriate SharePoint Foundation content database. To be able to persist data, your ASP.NET Web Parts must be placed on a page with these two controls.
Because these SharePoint Foundation-specific controls are required on pages that contain Web Parts, you cannot simply copy your ASP.NET page into a SharePoint Foundation site. To move ASP.NET Web Parts from an ASP.NET application to a SharePoint Foundation application, export them from ASP.NET as .webpart files and import them into a SharePoint Foundation site.
SharePoint Web Parts
The SharePoint Foundation Web Part infrastructure uses many of the controls in the ASP.NET Web Part control set, and introduces several of its own controls that inherit from base classes supplied by the ASP.NET Web Parts control set.
For example, site pages for a SharePoint Foundation site do not use the standard ASP.NET WebPartManager class. Instead, they use the SharePoint Foundation-specific SPWebPartManager class that inherits from the ASP.NET WebPartManager.
Note
The default master page that is provided with SharePoint Foundation includes an instance of SPWebPartManager class, so this control is automatically included with all of your SharePoint Foundation content pages.
Similarly, a Web Parts page for a SharePoint Foundation Web site also use a SharePoint Foundation-specific WebPartZone class that inherits from the ASP.NET WebPartZone class.
XML for Web Parts
Web Parts in SharePoint Foundation use multiple sections of XML to configure, deploy, and secure them in a Web site. Some of the XML is beyond the scope of this discussion but links are included at the end of this topic to relevant information
Web Part Definitions
A Web Part definition (.webpart) file is a simple XML file that contains property settings for a single Web Part. To import your Web Part into a Web Part Page, simply upload the .webpart file or add the Web Part to the Web Part gallery. After uploading the Web Part, you can display the Web Part by dragging it into one of the zones of the Web Part page. To display a default name and description for the Web Part after it is imported, you should include the Title and Description properties. If you want to set other Web Part properties during import, you can also define them in a .webpart file. A .webpart file takes the following form.
<?xml version="1.0" encoding="utf-8" ?>
<webParts>
<webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
<metaData>
<type name="TypeName, Version=VersionNumber, Culture=neutral,
PublicKeyToken=PublicKeyToken" />
<importErrorMessage>Cannot import this Web
Part.</importErrorMessage>
</metaData>
<data>
<properties>
<property name="Title" type="string">
WebPartTitle
</property>
<property name="Description" type="string">
WebPartDescription
</property>
</properties>
</data>
</webPart>
</webParts>
SafeControl Entries
To prevent untrusted users from arbitrarily adding server-side code within ASPX pages, SharePoint Foundation provides a SafeControls list. The SafeControls list is a list of approved controls and Web Parts specific to your SharePoint site that you have designated as safe for invocation on any ASPX page within your site. This list is contained in the web.config file in your Web application root. A SafeControl entry is an XML-based declaration of a Web Part that has the following form.
<SafeControl Assembly="AssemblyNameWithoutDLLExtension, Version=AssemblyVersionNumber, Culture=neutral, PublicKeyToken=PublicKeyToken" Namespace="NamespaceOfYourProject" TypeName="*" Safe="True" />
For more information about using Code Access Security, see Deploying Web Parts in SharePoint Foundation.
Code Access Security
Code Access Security (CAS) is a resource-constraints model in SharePoint Foundation that limits the access that an assembly has to protected system resources and operations. SharePoint Foundation has default security policies built on top of the built-in security policies of ASP.NET. By default, SharePoint Foundation uses a set of permissions that allow minimal access to system resources, in order to protect the server and underlying infrastructure from malicious code.
The XML that is used for CAS is beyond the scope of this section. For more information about securing Web Parts, see Securing Web Parts in SharePoint Foundation.