Create web parts for SharePoint

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

By using web parts, you can modify the content, appearance, and behavior of pages of a SharePoint site by using a browser. Web parts are server-side controls that run inside a web part page: they're the building blocks of pages that appear on a SharePoint site. See Building Block: Web Parts.

You can create and debug web parts on a SharePoint site by using templates from Visual Studio.

Create a web part in Visual Studio

Create a web part by adding a Web Part item to any SharePoint project. You can use a Web Part item in a sandboxed solution or a farm solution.

If you want to design a web part visually by using a designer, create a Visual Web Part project or add Visual Web Part item to any SharePoint project. You can use a Visual Web Part item in a farm solution only.

Web part item

A Web Part item provides files that you can use to design a web part for a SharePoint site. When you add a Web Part item, Visual Studio creates a folder in your project and then adds several files to the folder. The following table describes each file.

File Description
Elements.xml Contains information that the Feature definition file in your project uses to deploy the web part.
.webpart file Provides information that SharePoint needs to display your web part in a web part gallery.
Code File Contains methods that add controls to the web part and that generate custom content within the web part.

For more information, see How to: Create a SharePoint web part.

Visual web part item

A visual web part is a web part that you create by using the Visual Web Developer designer in Visual Studio. A visual web part functions the same as any other web part. To add controls, such as buttons and text boxes, to a web part, you add code to an XML file. However, you add controls to a visual web part by dragging or copying them onto the web part from the Visual Studio Toolbox. The designer then generates the required code in the XML file. See How to: Create SharePoint web part by using a designer.

SharePoint controls

Visual Studio provides some controls for creating SharePoint pages, such as application pages. These controls appear in the Toolbox under SharePoint Controls. The functionality for these controls derives from the Microsoft.SharePoint.WebControls namespace, which contains ASP.NET server controls that are used on SharePoint site and list pages.

Control Name Description
AspMenu Inserts an ASP menu. For more information, see Menu Control Overview.
CssLink Inserts a LINK element into the .aspx page and applies one or more external style sheets defined by CssRegistration.
DateTimeControl Inserts a DateTime control into the .aspx page.
FormDigest Inserts a security validation into the .aspx page
ListProperty Returns a property of a specified list.
ProjectProperty Returns a global property of the current website.
RssLink Inserts a link to an RSS feed into the .aspx page.
ScriptLink Provides properties and methods for registering resources, such as scripts, on a page so that they can be requested when the page is rendered.
Theme Applies a theme to the .aspx page.

Debug a web part

You can debug a SharePoint project that contains a web part just as you would debug other Visual Studio projects. When you start the Visual Studio debugger, Visual Studio opens the SharePoint site.

To start to debug your code, add the web part to a web part page in SharePoint.

For more information about how to debug SharePoint projects, see Troubleshoot SharePoint solutions.

Visual web part limitations

Starting in Visual Studio, you can add visual web parts to sandboxed SharePoint solutions and farm solutions. However, visual web parts have the following limitations:

  • Visual web parts don't support Replaceable parameters. For more information, see Replaceable parameters.

  • User controls or visual web parts can't be dragged and dropped or copied onto visual web parts. This action causes a build error.

  • Visual web parts don't directly support SharePoint server tokens such as $SPUrl. For more information, see "Token Restrictions in Sandboxed Visual Web Parts" in the topic Troubleshoot SharePoint solutions.

  • Visual web parts in a sandboxed solution occasionally get the error, "The sandboxed code execution request was refused because the Sandboxed Code Host Service was too busy to handle the request." For more information about this error, see this post in the SharePoint Developer Team Blog.

  • Server-side JavaScript debugging isn't supported in Visual Studio, but client-side JavaScript debugging is supported.

    Although you can add inline JavaScript to a server-side markup file, debugging isn't supported for breakpoints added to the markup. To debug JavaScript, reference an external JavaScript file in the markup file, and then set the breakpoints in the JavaScript file.

  • Debugging of inline ASP.NET code must be done in the generated code file instead of in the markup file.

  • Visual web parts don't support the use of the <@ Assembly Src= directive.

  • SharePoint web controls and some ASP.NET controls aren't supported in the SharePoint sandboxed environment. If unsupported controls are used on a visual web part in a sandboxed solution, the error, "The type or namespace name 'Theme' does not exist in the namespace 'Microsoft.SharePoint.WebControls'" appears.

    For more information about sandboxed solutions, see Differences between sandboxed and farm solutions.

Create older style SharePoint-based web parts

You can use the templates in Visual Studio to create custom ASP.NET 2.0 web parts for SharePoint. ASP.NET 2.0 web parts are built on top of the ASP.NET web part infrastructure and are the recommended type for new projects.

In very few cases, you might have to create a web part by using the older style SharePoint-based web part. You can use Visual Studio to create these types of web parts, but Visual Studio doesn't provide any templates that are designed specifically to help you create them.

For more information about when you might want to create an older style SharePoint-based web part, see Web Part Infrastructure in Windows SharePoint Services. For more information about how to create a web part by using the older style SharePoint-based web part, see Walkthrough Creating a Basic SharePoint Web Part.

Title Description
How to: Create a SharePoint web part Shows you how to create web parts for SharePoint pages.
How to: Create a SharePoint web part by using a designer Shows you how to create web parts for SharePoint by using a visual design surface.
How to: Create a user control for a SharePoint application page or web part Shows you how to create custom, reusable controls that can be consumed by application pages and web parts that run in SharePoint.
Walkthrough: Create a web part for SharePoint Describes how to design a web part for SharePoint.
Walkthrough: Create a web part for SharePoint by using a designer Describes how to design a web part for SharePoint by dragging controls to a visual design surface.
Walkthrough: Create Silverlight web part that displays OData for SharePoint Describes how to design a web part for SharePoint that hosts a Silverlight application and displays data from SharePoint lists.