2. Introduction

HOL402: Packaging and Deploying Microsoft SharePoint Products and Technologies 2007 Solutions 
 

3. Technologies Highlighted

Microsoft Windows® SharePoint® Services 3.0

4. Audience

Developer – 400 level

5. Scenario

In this lab, you will work with a Visual Studio project to write, deploy and test custom application pages that run out of the virtual _layouts directory. This will demonstrate a few ways to use custom application pages and also give you a sense for what it's like to develop them for a WSS solution. Integrating these custom application pages into the user interface of a WSS site will also require you to develop a feature to add custom menu items to the site actions menu. At the end of the lab, you will combine all these elements including feature files, custom application pages and an assembly DLL into a WSS solution package to automate deploying these components as a complete WSS solution in a staging environment or a production environment.

6. Purpose of Hands-on Lab

This lab teaches participants how to package Microsoft® Windows® SharePoint® Services 3.0 components such as Features, application pages and assemblies into a Solution Package in order to take advantages of the new enhanced deployment infrastructure offered by Windows SharePoint Services 3.0.

• Login using the following credentials:
  • Username: LuisB
  • Password: pass@word1
  • Log on to: LITWAREINC
• Wait for the Warmup Script to complete and the popup window to close
• Launch the WSS Central Administration Web site by using the command in the Windows Start menu. You can find the command at Start >>All Programs >> Administrative Tools >> SharePoint 3.0 Central Administration.
• Once the home page of the WSS Central Administration Web site appears, click on the Application Management tab at the top of the page to get to the Application Management page. Under the SharePoint Site Management section, click the link with the caption Create site collection. This will take you to the page where you can create a new site collection and a new top-level site.  On the Create Site Collection page, fill in the required information (see below for instructions) to create a new site collection.
  • Make sure the Web Application used for site creation is the one that is accessible through the URL http://moss.litwareinc.com.
  • Enter a title such as Lab 2 Test Site.
  • Create the new site collection so that its URL is http://moss.litwareinc.com/sites/Lab2.
  • Under the Template Selection section, look at all the sites templates that are available. Choose Blank Site from the Collaboration tab as the site template for the new top-level site that is automatically created.
  • Assign the primary site collection owner as LITWAREINC\Administrator.
  • Leave the Quota Template with the default setting of No Quota
  • Click OK to create the new site collection and top-level site. Once you see that page that confirms that everything has been created, navigate to the top-level site using the browser
• Once you have created and navigated to this new site collection, you can go on to the next exercise.

• Launch Visual Studio. Open the project named Lab2.sln located inside the C:\HOL\SharePointSolutions\Lab directory. This project contains a custom application page named SiteInfo.aspx and various other source files required to deploy and integrate it into a custom business solution. Use the Solution Explorer to get an idea of the project's directory structure as well as what source files are included as part of this project.
• Open SiteInfo.aspx and look inside. You should be able to see that this ASP.NET page is defined to inherit from a class defined inside SiteInfo.cs named Lab2.SiteInfo. You should notice that this page file contains no code; only HTML mark up and a server control tag to create an instance of the SPGridView control named grdSiteProperties.
• Open SiteInfo.cs and find the class named SiteInfo in the Lab2 namespace. Note that this code-behind class defines a control field using the same name and type that was used in the server control tag in SiteInfo.aspx. This technique is what allows method implementation inside the code-behind class SiteInfo.cs to access the SPGridView control named grdSiteProperties.
• Examine the Feature that is defined in feature.xml and elements.xml. You should be able to see that this Feature defines a single CustomAction element to add a custom menu item to the SiteActions menu that will allow a user to navigate SiteInfo.aspx.
• Build the project. This will recompile the project's output assembly Lab2.dll and then use a post build event to run install.bat which contains commands to install Lab2.dll in the GAC, to copy the Feature files into the WSS FEATURES directory and to install (or reinstall) the Feature itself. At this point, the Feature should be installed and ready for activation in any site within the current farm.
• Navigate to the site you create in the first exercise at http://moss.litwareinc.com/sites/lab2. Open the Site Actions menu and click Site Settings and then click the Site Feature management link. You should be able to see the Feature for this lab with a title of Lab 2 - Working with Application Pages. Activate this Feature.
• Open the Site Actions menu. You should be able to see a menu item with the title of Get Site Info. Select that menu item to navigate to SiteInfo.aspx. The page SiteInfo.aspx should render and display an SPGridView control with one row of test data.. 
   
  
• Now return to Visual Studio and look at the OnLoad event handler method for the page within SiteInfo.cs. You should see that this code works with a utility class named PropertyCollectionBinder to populate the SPGridView control named grdSiteProperties.
• Inspect the PropertyCollectionBinder class defined inside PropertyCollectionBinder.cs in order to get an understanding of how this utility class encapsulates creating a DataTable and binding to any SPGridView control.
• Now, go back to the OnLoad method of page class and locate the following line of code.

// remove the next line and begin your work here

binder.AddProperty("Test Property", "Test Value");

• Remove that line of code and replace it with code which also uses the AddProperty method to programs against the WSS object model to populate the SPGirdView control with name value pairs which display information about the current site collection and the current site. You should be able to rebuild the project and then refresh the browser to test your work. When you are done, the resulting SPGridView control should look like the one below. You should use IntelliSense and the Visual Studio object browser to find what you need in the WSS object model. If you get stuck, you can take a peek at the lab solution. 
   
  

• Now it's time to create a new application page. The project already includes a new page file named DocumentInfo.aspx in the same location as SiteInfo.aspx. Also there is a code-behind class file named DocumentInfo.cs in the same location as SiteInfo.cs. Open these two files and look inside.
• This new page named DocumentInfo.aspx will be used to display information about a specific document. Therefore, it makes sense to add a new custom ECB menu item to documents within a document library so that users can use this page to get information about a specific document upon request. Go to the elements.xml file and add the following element.

<CustomAction

  Id="DocumentInfo"

  RegistrationType="List"

  RegistrationId="101"

  ImageUrl="/_layouts/images/GORTL.GIF"

  Location="EditControlBlock"

  Sequence="10"

  Title="Get Document Info (Lab 2)" >

  <UrlAction Url= "~site/_layouts/Lab2/DocumentInfo.aspx?ItemId={ItemId}&amp;ListId={ListId}" />

</CustomAction>

When a user redirects to DocumentInfo.aspx, your code will need query string parameters to get information about the specific list and item.

• Now rebuild the project. This should copy the updated version of the Feature files into the FEATURES directory, reinstall the new updated Feature definition and then run an IISRESET operation.
• Now it's time to check your work and make sure the ECB menu appears as it should. Return to the test site and create a new document library. Once you have created the document library, add a new document or upload an existing document. When you drop down the ECB menu for this document, you should see the new custom ECB menu item that was added by our Feature. When you select this custom ECB menu item, you should be redirected to DocumentInfo.aspx. However, the code behind this application has not yet been updated to show any information about the current document.
• Update the OnLoad event handler method inside DocumentInfo.cs to fetch the query string parameters named ItemId and ListId. Use these values to create an SPList object for the document library and an SPListItem object for the document. Now, program against the WSS object model to get the information required to make the SPGridView control on DocumentInfo.aspx look like the screenshot below. 
   
  
• When you are done, close all aspx files, rebuild the project and refresh the browser to test your work.

• Now it is time to create a solution package to move this entire solution of WSS components from your development machine into a staging environment or a production environment. The first thing you need to do uninstall and remove all the components from your development machine. Start up a command prompt and run the following batch file to reverse everything that was done by Install.bat.

C:\HOL\SharePointSolutions\Lab\Uninstall.bat

• Once you have run Uninstall.bat, you should be able to verify that the Lab2 feature is no longer activated or installed. You can do this by going to the Site Feature management page (/_layouts/ManageFeatures.aspx) and verifying that the Lab2 feature is not available for activation.
• Now look at the files inside the Solution folder of the current Visual Studio project and locate the two files named manifest.xml and cab.ddf. You will not be modifying these files in this exercise, but just looking at them. Once you have seen what is inside, you will then run batch files to build and deploy the solution package.
• First, look at the manifest.xml that will be added into the solution package.

<Solution

      SolutionId="42262980-404A-4e1c-916A-FD72B031AEDF"

      xmlns="http://schemas.microsoft.com/sharepoint/"> 
 

  <FeatureManifests>

    <FeatureManifest Location="Lab2\feature.xml" />

  </FeatureManifests> 
 

<TemplateFiles>

    <TemplateFile Location="LAYOUTS\Lab2\DocumentInfo.aspx"/>

    <TemplateFile Location="LAYOUTS\Lab2\SiteInfo.aspx"/>

    <TemplateFile Location="IMAGES\TPG\PithHelmet.gif"/>

  </TemplateFiles> 
 

  <Assemblies>

    <Assembly Location="Lab2.dll"

              DeploymentTarget="GlobalAssemblyCache" />

  </Assemblies>   
 

</Solution>

• Next, look at what is inside the cab.ddf file.

.OPTION EXPLICIT  ; Generate errors

.Set CabinetNameTemplate=Lab2.wsp    

.set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory

.Set CompressionType=MSZIP;** All files are compressed in cabinet files

.Set UniqueFiles="ON"

.Set Cabinet=on

.Set DiskDirectory1=Package 
 

Solution\manifest.xml manifest.xml

TEMPLATE\FEATURES\Lab2\feature.xml Lab2\feature.xml

TEMPLATE\FEATURES\Lab2\elements.xml Lab2\elements.xml 
 

TEMPLATE\LAYOUTS\Lab2\SiteInfo.aspx LAYOUTS\Lab2\SiteInfo.aspx

TEMPLATE\LAYOUTS\Lab2\DocumentInfo.aspx LAYOUTS\Lab2\DocumentInfo.aspx 
 

TEMPLATE\IMAGES\TPG\PithHelmet.gif IMAGES\TPG\PithHelmet.gif 
 

bin\Debug\Lab2.dll Lab2.dll 
 

;*** <the end>

• Now you have seen the two main files used to build a solution package. The cab.ddf file is used as input to MAKECAB.EXE to create a solution package named Lab2.wsp. The manifest.xml file is included inside the solution package and this file acts as the main manifest used by the WSS installer during solution package deployment.
• Bring up a command prompt navigate to the following directory.

C:\HOL\SharePointSolutions\Lab\Package

• Run the batch file named CreateSolutionPackage.cmd to build Lab2.wsp. The contents of this batch file looks like this.

if EXIST Lab2.wsp del Lab2.wsp

cd ..

makecab /f Solution\cab.ddf

cd package

• Run the batch file named InstallSolutionPackage.cmd to install Lab2.wsp into the farm-scoped solution package store. The contents of this batch file looks like this.

@SET SPDIR="c:\program files\common files\microsoft shared\web server extensions\12"

%SPDIR%\bin\stsadm -o addsolution -filename Lab2.wsp

• Run the batch file named DeploySolutionPackage.cmd to deploy the solution package. The contents of this batch file looks like this.

@SET SPDIR="c:\program files\common files\microsoft shared\web server extensions\12"

%SPDIR%\bin\stsadm -o addsolution -filename Lab2.wsp

%SPDIR%\bin\stsadm -o deploysolution -name Lab2.wsp -immediate -allowGacDeployment -force

%SPDIR%\bin\stsadm -o execadmsvcjob

• Now, it’s time to make sure everything has been installed correctly and that your solution works after the solution package has been deployed. Navigate to Site Feature management page (/_layouts/ManageFeatures.aspx). Ensure you Lab2 feature is there and can be activated. Once you have activated it, test out the menu items and custom application pages to make sure they work.
• If you are interested, go through the steps of retracting the solution package as well. Start by deactivating the Lab2 feature in the current site and then run the batch file named DeploySolutionPackage.cmd which contains the follow command-line instructions.

@SET SPDIR="c:\program files\common files\microsoft shared\web server extensions\12" 
 

%SPDIR%\bin\stsadm -o retractsolution -name Lab2.wsp -immediate

%SPDIR%\bin\stsadm -o execadmsvcjobs

%SPDIR%\bin\stsadm -o deletesolution -name Lab2.wsp 
 

1. Conclusion

In this lab, you learned the fundamentals of working with deploying and packaging Windows SharePoint Services solutions.