We will perform
the following actions, broken into document parts:
·
Build a Web Part by hand (as opposed to using templates)
·
Build a simple web user control
·
Load the web user control in the SharePoint Web Part via code
·
Deploy the web user control by placing the development location
in the SharePoint site
·
Deploy the Web Part by compiling it to the bin directory of the SharePoint
site
·
Add a safe-control entry in to the Web.config and modify the
security settings
·
Modify the Web Part Gallery to display the Web Part for testing
and debugging
Part 1: Starting the Required Projects
1.
Create a directory under the root of the SP web called /usercontrols. It
may help to drag and copy the existing /bin directory and clear out the
contents. This ensures the proper file based permissions are added to your
project.
2.
Open Visual Studio 2005 and start a new file system based C# website
project. Make sure the location is your new /usercontrol directory. Remove the
initial aspx page.
3.
Add a new C# based windows library project to the solution. Name it appropriate to the fact that this will be your Web Part project.
4.
Open the Web Part project properties and change the compile output location
to the /bin directory of your SP web, not the /bin directory of your user control
project.
Part 2: Developing the User Control
1.
In the usercontrol project add a new user control, naming it appropriate
to your needs. In this case we will call it the HelloControl. This, of course,
adds the HelloControl.ascx file and the HelloControl.cs files.
2.
Open the ascx file, switch to Design mode and add a Textbox control.
3.
Use F7 to switch to the C# code view and in the Page_Load event add code
that changes the text output of the Textbox control, for example:
Listing 1
protected void Page_Load(object sender, EventArgs e)
{
this.TextBoxHello.Text = @"Hello Control World!!!";
}Part 3: Developing the Web Part
1.
Open the Web Part control project and change the name of the cs file
appropriate to your needs, for example HelloLibrary, which will change the name
of the class declaration inside the code file.
2.
Open the class file and change the using statements to reflect the
following listing.
Listing 2
using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls.WebParts;
3.
Change the class declaration to ensure the class inherits from the Web Part
class.
Listing 3
public class HelloLibrary:WebPart
4.
Add a Control object that will represent the usercontrol.
5.
Override the CreateChildControls to load your control with the Page
object LoadControl method that will load the HelloControl control from the file
system.
6.
The LoadControl method has two overloads. The method we will use expects
a string representing the virtual location of the usercontrol on disk. This
will point to the virtual location by using the "~" and the path. The
"~" represents the location of the code that is running. As such, the
path "~/usercontrols/HelloControl.ascx" means, start from where I am
running and consider that the root of this path, then locate the file to use.
7.
Follow this up by adding this loaded control to the page controls
collection.
Listing 4
Control control;
protected override void CreateChildControls()
{
this.control = this.Page.LoadControl(@"~/usercontrols/HelloControl.ascx");
this.Controls.Add(this.control);
}Part 4: Adapting the Web.Config
1.
Now, two changes need to be made to the web.config. Locate and open it
from the root of your SP website.
2.
One change needed is to adjust the security settings. The discussion of
SP application security is beyond the scope of this article, but we will cover
the change needed for this application. A search of the internet will cover the
fact that there are other ways to adapt security than what we will use, but
this will work for our needs.
3.
Locate the line in the web.config that reads:
Listing 5
<trust level="WSS_Minimal" originUrl="" />
Change it to
read:
Listing 6
<trust level="Full" originUrl="" />
By doing this we
are granting full access to this SP site, which is needed to allow file IO
access and to load the usercontrol from a disk.
4.
Next, locate the SafeControls block. Make a copy of the last line and
replace the information with your project information. If we were using a GAC
installed assembly, our SafeControl line would look more like the line you cut
and paste. But because we are putting the assembly in the bin directory, we can
keep it simpler.
Listing 7
<SafeControl Assembly="HelloSmartPart"
Namespace="HelloSmartPart" TypeName="*" Safe="True" />
·
The Assembly tag refers to the physical name of the assembly
without the .dll extension.
·
The NameSpace is the same as the assembly namespace.
·
The TypeName denotes the safe methods, in this case * indicates
all methods are safe.
Part 5: Deployment and Testing
1.
Open your website. At this point your new Web Part is not yet an option
to be selected and must be enabled for use.
2.
Open the Site Settings.
3.
Under Galleries, click the Web Parts link.
4.
Web Parts are controlled by XML files. But in this case, we did not
craft an XML file for this Web Part. The act of enabling this Web Part for use
will assist with this need.
5.
Click New, which causes SharePoint to read
the Web.config file. It reads the config and uses reflection to build the
information needed to allow you to use the Web Part.
6.
You should now see the webpart. Click the Populate
Web Part option.
7.
Now back in the main Web Part Gallery page, take a minute to review the Web
Part properties by clicking on the Edit link button. Click on the View Xml link. You may find this bare-bones config file
useful in other development tasks.
8.
Now go to the main page. Click on Site Settings,
and edit page. In the middle, click on Add A Web Part
and locate the Hello webpart.
9.
Your Web Part should now be displayed. The labor of your efforts should
now be realized in the fact that you have crafted a user control that is loaded
into a Web Part. If you were using the Web Part only method (without a
usercontrol), all of your code would need to be built by hand. This means that
the creation of all controls, event wire-ups and such would need to be written
into the Web Part by way of the html render code. With this method you use the Web
Part as the container for one or more usercontrols that do all of the heavy
lifting. And one more great aspect to this method is that you do not even need
to compile the usercontrol. You simply edit the usercontrol code-behind and IIS
and .NET take care of the rest.
