Building and Hosting PDS Web Applications for Project Server 2003
Jim Corbin
Microsoft Corporation
September 2004
Applies to:
Microsoft Office Project Server 2003
Microsoft Office Project Web Access 2003
Microsoft Office Project Professional 2003
Microsoft Windows SharePoint Services
Microsoft Office SharePoint Portal Server 2003
Microsoft Visual Studio .NET 2003
Summary: The Project Data Service (PDS) provides an extensible architecture for accessing and modifying data in Project Server 2003. Learn how to develop, deploy, and use an ASP.NET application that creates XML requests and processes replies of PDS methods and extensions. Understand how to host the Web application on a server with Microsoft SharePoint Products and Technologies, and how to use the Web application within Project Web Access and Project Professional. (39 printed pages)
Download pj11HostingPDSApplications.exe.
Contents
Using the Project Data Service
Configuring Web Sites for PDS Applications
Installing and Running the Sample Code
Creating an ASP.NET Application with the PDS Web Service
Using the Web Application in Project Web Access
Using the Web Application in Project Professional
Conclusion
Additional Resources
Files in the Download
Using the Project Data Service
The Project Data Service (PDS) is the primary API for Microsoft Office Project Server 2003. The PDS enables other applications and software components to interact with Project Server through an XML-based API. The PDS is extensible to allow access to project data that is not directly accessible by using the built-in PDS methods.
In this article, we show you the following:
- How to use Microsoft Visual Studio .NET and ASP.NET to develop and deploy a Web application that uses a PDS extension through the PDS Web service.
- How to use the PDS Web application in Web Parts for shared documents on Microsoft Windows SharePoint Services and Microsoft Office SharePoint Portal Server.
- How to use the Web application in Project Web Access and as a custom view within Project Professional.
The download includes the source code for an ASP.NET application that uses the Project Renamer PDS extension, plus a sample Web Part and custom view that hosts the Web application.
To use the sample application, you also need to download the Project Renamer PDS Extender and install it for each Project Server virtual directory you intend to access. For instructions, see Installing and Registering the Project Renamer PDS Extender.
Accessing Project Server Data
In addition to using the PDS, you can access and modify Project Server data in other ways. For example, you can use the Project OLE DB Provider or use SQL scripts to directly access the Project Server tables in Microsoft SQL Server. However, the PDS is the preferred way to programmatically interact with Project Server. The built-in PDS methods are designed to safely modify data in the complex Project Server tables. If you directly access SQL project data, you could make changes that would corrupt the tables or damage referential integrity. Of course, you must write PDS extensions carefully to avoid causing problems.
Advantages of the PDS
The PDS includes a built-in Web service interface. PDS extensions act the way native PDS methods do, which are accessible as XML requests through the Web service using SOAP or the HTTP POST protocol. The PDS also uses the Project Server security architecture. Logon security for the PDS can use Project Server or Windows authentication, and the PDS takes advantage of the extensive Project Server permission structure. For example, the Project Renamer PDS extension blocks a user who does not have both the New Project and Manage Enterprise Features permissions. In that case Project Renamer returns Security Access Denied (status code 50) that indicates insufficient permissions.
You can develop Windows client applications, Web applications, and software components that use PDS methods and extensions in many ways. The advantages of PDS Web applications include remote access and better integration with Project Professional and Project Web Access.
Development with SOAP
Most PDS applications developed with Microsoft Visual Basic 6.0 or classic Active Server Pages (ASP) have used the Microsoft SOAP Toolkit, which is deprecated by the Microsoft .NET Framework. The .NET Framework provides built-in support for SOAP and Web services, along with many other advantages.
Note The SOAP Toolkit is currently available. For more information, see SOAP Toolkit 3.0. For alternatives to using the SOAP Toolkit for Visual Basic 6.0 and classic ASP applications, see Integrating Web Services and COM Components and Migrating from the SOAP Toolkit to Web Services.
Configuring Web Sites for PDS Applications
You should use this article and sample code with Visual Studio .NET 2003, with the .NET Framework 1.1. If you have Visual Studio .NET 2002, which uses the .NET Framework 1.0, you can create a new project and import the sample code files. If you have a later version of Visual Studio .NET, it automatically updates the project and related files. For a list of files, see Files in the Download.
You can develop and test a PDS Web application on one computer and then install it by creating a virtual directory with Internet Information Services (IIS) on the Project Server computer that is available to the organization. Users can access the Web application directly through a browser. You can create Web Parts that use the application through Windows SharePoint Services or SharePoint Portal Server 2003. You or authorized users can then easily create Web Part Pages as shared documents or add the Web application to views within Project Web Access. You can also use the PDS Web application within custom views in Project Professional 2003.
Your development environment should include one of the following combinations, where all computers have the current Windows service pack and security patches installed from Windows Update. For a typical example where you can develop and test on one computer and deploy on a target Web server, see Figure 1.
- Development computer: Windows XP SP1 or later, with IIS installed. Windows XP uses IIS version 5. If the development computer is running Windows Server 2003, it can also have Windows SharePoint Services, SharePoint Portal Server, or Project Server installed. Windows Server 2003 uses IIS version 6.
- Target Web server: Windows Server 2003 or later. The target Web server includes Project Server and can also have Windows SharePoint Services or SharePoint Portal Server installed. Windows SharePoint Services may be provisioned by Project Server, but that is not required.
You can use the sample code on a development computer that is separate from the target Web server, or develop directly on a Web server that is available for test applications. In this article, we show you how to install the Web application on a Project Server computer with Windows SharePoint Services.
Figure 1. Example of development and target computers
If the target Web server is not running Project Server, access from other computers within the intranet requires configuration of the Kerberos protocol security delegation. For more information, see Windows Authentication Issues.
Important Because direct development on a production Web server can create security issues, it is not recommended. You should develop, deploy, and test the Web application with a test server before installing it on a production Web server.
Creating a Web Site
When the target server is running Windows SharePoint Services, you need to configure the Web site so that the virtual directory is excluded from management by Windows SharePoint Services. If you are developing directly on a Windows SharePoint Services or a SharePoint Portal Server computer, you first need to create and exclude the development Web site from Windows SharePoint Services.
If you create a Visual Studio .NET Web Setup project to install the completed application, the Windows Installer uses the setup.msi file from the compiled Web Setup project to create the virtual directory for the Web site. You must then exclude that Web site from Windows SharePoint Services management.
The following procedures explain how to set up a Web site for PDS applications.
To create a Web site for development or deployment:
- In Internet Information Services (IIS) Manager, right-click Default Web Site, click New, and then click Virtual Directory.
- Use the Virtual Directory Creation Wizard to create a development Web site. For example, type HostPDS in the Alias field for the Virtual Directory Alias.
- For the Web Site Content Directory, type the path or browse to the directory where you want the content to be created. The content directory can be located anywhere on the computer, for example
C:\Project\HostPDS. It is usually advantageous for development and testing to put a content directory somewhere other than in
C:\Inetpub\wwwroot, so that you can easily distinguish between test sites and completed sites.
- Accept the default settings for the Virtual Directory Access Permissions, and complete the wizard.
- In IIS Manager, right-click the HostPDS virtual directory, click Properties, and then click the Directory Security tab.
In Authentication and access control, click Edit. Make sure Enable anonymous access is not selected, and Integrated Windows authentication is selected. Do not select any other access methods.
Note In the Windows 2000 IIS Manager, the frame caption is Anonymous Access and authentication control.
Because you use Windows Integrated authentication within a domain or a set of trusted domains on an intranet, make sure the virtual directory does not allow anonymous access. In Windows XP, the IIS Virtual Directory Creation Wizard selects Anonymous access by default; you must clear the check box. In Windows Server 2003, Anonymous access is not selected by default.
If you are developing on Windows XP or Windows Server 2003 without Windows SharePoint Services, after you create the Web site skip to Installing and Running the Sample Code. After you develop the application, if you deploy it to a Windows SharePoint Services computer, you need to exclude the site from Windows SharePoint Services management.
To exclude the Web site from SharePoint Services management:
Note Perform the following steps only if the Web site is on a Window s SharePoint Services computer.
- In Administrative Tools, start SharePoint Central Administration. On the Central Administration page, click Configure virtual server settings.
- On the Virtual Server List page, click Default Web Site.
- On the Virtual Server Settings page, in Virtual Server Management, click Define managed paths.
On the Define Managed Paths page, in Add a New Path, type your new Web site name in Path. For example, type hostpds (the Web site name is not case-sensitive).
Configuration error You receive the following error when you try to browse the sample PDS Web application if it is not excluded from Windows SharePoint Services management.
HTTP error 403: You are not authorized to view this page.
Installing and Running the Sample Code
Execute the download pj11HostingPDSApplications.exe to install files on the development computer. For a list of installed files, see Files in the Download. Before you execute Setup.exe to install the HostPDS sample application, you should create the HostPDS virtual directory for the development Web site in IIS, as described in Creating a Web Site. In the following examples, the local path for the test Web site is
C:\Project\HostPDS.
If your development computer is separate from the Project Server computer, the four main steps you take to install the HostPDS application are as follows:
- Install a Test Web Site. Install the HostPDS sample code in a test Web site on the development computer, and modify the source code for your Project Server.
- Test the HostPDS Application. Make sure the Web application works before deploying to the Project Server computer.
- Create the deployment project. Create a Web Setup Project in Visual Studio that includes only the primary output and content files of the HostPDS application, and compile the setup project.
- Deploy the Web application. Copy your setup application to the Project Server computer and install HostPDS. This installation does not include source code.
For information about authentication and authorization problems with the HostPDS Web application, see Windows Authentication Issues.
Installing a Test Web Site
When you install the download in a test Web site, you must first replace the name of the Project Server computer in the source code and project files. You also must configure IIS and the web.config file in the HostPDS application correctly for your computer, and update the Web reference that uses the PDS Web service.
To install the HostPDS sample code in a test Web site:
- In the SetupHostPDS directory installed by pj11PDSExtensions.exe, execute Setup.exe. In the HostPDS Setup Wizard, on the Select Installation Address page, accept the default name HostPDS for the Virtual Directory, click Next, and then click Next again on the Confirm Installation page. The Installation Complete page appears after installation succeeds.
- In all files, replace the text ServerName with the name of your computer where Project Server is installed. Start Visual Studio .NET 2003, and close any open solution; do not open the HostPDS.sln file yet. On the Edit menu, click Find and Replace, and then click Replace in Files. Check Look in subfolders, and type *.* in the File types field to search all files. Figure 2 shows the Replace in Files dialog box.
Figure 2. Replacing all occurrences of ServerName
The operation replaces ServerName in three files: Default.aspx, HostPDS.csproj, and WebReferences\PDSWebSvc\Reference.cs.
Note If you open HostPDS.sln and use only the Replace operation, the operation does not work on the HostPDS.csproj file.
- Open the HostPDS solution. On the File menu, click Open, and then click Project. Navigate to the directory you created for the Web site, for example
C:\Project\HostPDS, and open the file HostPDS.sln.
Note If your virtual directory name is not HostPDS, you must edit the HostPDS.sln file to specify the virtual directory name. For example, if your virtual directory name is MyTestWeb, open HostPDS.sln with Notepad or another text editor and change the Web address from "" to "".
- If your development computer does NOT have Windows SharePoint Services installed, modify the file web.config for execution on the local computer, as follows:
- On the View menu, click Solution Explorer. Expand the HostPDS project and double-click Web.config.
- If Windows SharePoint Services is not installed on the local computer, comment out the httpHandlers, trust, and httpModules elements. Leave the pages element active.
<!-- The following is necessary to coexist" /> <!-- End coexist with WSS -->
Note If you later deploy the Web application to a Project Server computer with Windows SharePoint Services, you must uncomment the httpHandlers, trust and httpModules elements in web.config to allow your Web application to work.
- Set the PDS Web service reference to the correct virtual directory and PDS Web Services Description Language (WSDL) file name for the Project Server computer. The default Web reference follows.
If you want to use a different Project Server virtual directory and pds.wsdl file, you must change the reference. For example, if you installed the default Project Server sample database and created a pdsSample.wsdl file to match, your PDS Web service reference would be the following.
Note Perform the following steps only if you are not using the default Project Server virtual directory. For more information about creating PDS WSDL files for multiple Project Server virtual directories, see Using the PDS with Multiple Project Server Sites.
- Press Ctrl+F in Visual Studio and find all of the locations for pds.wsdl in the current project. In the Reference.cs file (WebReferences\PDSWebSvc), change the PDS class constructor to the following (for example):
- In the file Default.aspx.cs, change the value of the WSDL constant to match.
- Update the Web reference. In Solution Explorer, expand the Web References folder. If you click Show All Files in the Solution Explorer toolbar, you see that the PDS.wsdl and Reference.map files are missing under the PDSWebSvc node. To create the files, right-click PDSWebSvc, and then click Update Web Reference.
Note The Visual Studio Task List shows the following build error: Custom tool warning: At least one optional import ServiceDescriptionFormatExtension has been ignored. The warning results from a SOAP Toolkit extension in the WSDL file. Because the .NET Framework includes SOAP functionality, it ignores the older SOAP Toolkit extension used by the PDS Web Reference.
You should now see the following files in the subdirectory WebReferences\PDSWebSvc\:
- Reference.cs contains the code that defines where to look for the PDS Web service, and was installed with the other source files.
- PDS.wsdl is created when you update the Web Service. It contains a local copy of the WSDL file that Reference.cs points to.
- Reference.map is an XML file that links the network Web Service with the local WSDL file.
- Build the HostPDS solution. Click Save All, and then on the Build menu, click Build HostPDS.
Testing the HostPDS Application
After you successfully build the HostPDS Web application, you need to test it in several cases. You should run it from the development computer, and from a remote computer to see how Web application security works in your environment.
- In Visual Studio, run the HostPDS Web application. Press F5 to run the application in the debugger.
- In the Project Renamer browser window, make sure Project Server URL is correct.
- Use Project Server authentication to log on with a user name that has Project Server administrator privileges.
- Click Get Project List to see a list of all projects and versions with the Project ID, and then click a project in the list you want to rename. The XML Results box shows the formatted XML reply from the PDS request ProjectsStatus. The application populates the list box from data in the PDS reply.
- Click one of the projects in the list box, and then type a new name in the New project base name box.
- Click Rename all Versions. You see a confirmation dialog box with the question Rename all versions of the project: [project name] ? Click OK. The XML Results box shows the PDS ProjectRename request and the PDS reply, as in Figure 3.
- If the reply values for HRESULT and STATUS are both 0, you have succeeded. You can click Get Project List again to confirm the name was changed.
Figure 3. The Project Renamer application
- In Internet Explorer on your development computer, browse to the HostPDS application directly. You can enter the URL as either.
If Project Server is set up to use your Windows account, use Windows authentication. The log on should succeed.
- From a remote computer in the same domain where you are logged on as the same user, browse to the HostPDS test site. Make sure Internet Explorer on the remote computer trusts your development computer. On the Tools menu, click Internet Options, click Security, click Trusted sites, and then click Sites. Add your development site to the list. For example, type.
If the HostPDS test site is on a computer different from the one with Project Server installed, you get the following results when you click Get Project List in the HostPDS application:
If the HostPDS test site is on the Project Server computer, the application should work for Project Server authentication, but Windows authentication fails, as shown in Figure 4. The XML Results text box shows the following error:
The PDS Reference Error Codes page describes status 5003 as follows: No user security context was detected (for integrated security only).
Figure 4. Windows authentication fails with remote access through HTTP
When you browse to the HostPDS application from a remote computer, the authorization problems you can experience depend on whether HostPDS is installed on the Project Server computer or on a separate development computer. These problems are related to the way HTTP handles Windows credentials. For more information, see Windows Authentication Issues.
Creating the Deployment Project
For use throughout your organization, the compiled HostPDS application and content should be installed without the source code on the Project Server computer. To do that, you can create a deployment project in Visual Studio and then install the compiled application.
To create a deployment project:
- In Visual Studio, open Solution Explorer, right-click Solution 'HostPDS', click Add, and then click New Project.
- In the Add New Project dialog box, click Setup and Deployment Projects, and then click Web Setup Project. In the Name field, type HostPDSSetup, and then click OK.
- Click the HostPDSSetup project in Solution Explorer, and then open the Properties Window. Set the properties listed in the following table.
Table 1. Properties to set for HostPDSSetup
- In File System on Target Machine, right-click Web Application Folder, click Add, and then click Project Output. In the Add Project Output Group dialog box, press CTRL and click to select both Primary output and Content Files, and then click OK.
- In the Properties window of the Web Application Folder, select properties for the installer in the Properties window of the Web Application Folder. The following table describes the properties.
Table 2. Properties to set for the installer
- Build the deployment project: On the Build menu, click Build HostPDSSetup. Figure 5 shows the results of the build and some of the properties settings for the HostPDSSetup project.
Figure 5. Building the Web deployment project
Deploying the Web Application to Project Server
After you test the HostPDS application and build the HostPDSSetup Web deployment project, you can install HostPDS on the Project Server computer. You could install it on any Web server in the intranet, but you would be limited to accessing HostPDS only from that computer unless you configure Kerberos authentication as noted in Windows Authentication Issues.
You can let Windows Installer create the default HostPDS subdirectory in
C:\Inetpub\wwwroot, or you can first use IIS to create a HostPDS virtual directory at another location on the Project Server computer.
If the Project Server computer is also running Windows SharePoint Services, after you install the HostPDS application you must also reconfigure web.config in the application's directory and exclude the virtual directory from Windows SharePoint Services.
To deploy the HostPDS application on the target Project Server computer:
- Copy the three files from the HostPDSSetup build directory on your development computer (for example,
C:\Project\HostPDS\HostPDSSetup\Debug) to a directory on the target Project Server computer. The files created by building the HostPDSSetup project are Setup.exe, Setup.ini, and HostPDSSetup.msi.
- Optional. If you want the physical directory of the Web site located somewhere other than
C:\Inetpub\wwwroot, create the Web site on the target Project Server computer. For the procedure, see Creating a Web Site.
- Run Setup.Exe to install the HostPDS application. You can choose a different virtual directory name, and even a different port, as shown in Figure 6. For example, if you created the virtual directory RenameProject in IIS for the HostPDS application previously, change the Virtual Directory name to be the same.
Figure 6. Installing HostPDS on a Project Server computer
- Test the HostPDS application. For example, if your Project Server computer name is myProjectServer and you used the HostPDS virtual directory name, browse to both the local and a remote computer.
If the browser shows an error such as the one in Figure 7, and Windows SharePoint Services is installed on the Project Server computer, check the Windows SharePoint Services compatibility settings in web.config. The standard ASP.NET error page explains how to add a custom error page, so your users see a friendlier message.
Figure 7. ASP.NET error for incompatible web.config settings
As previously described, when the HostPDS application is installed on a Project Server computer, it works with Project Server authentication but not with Windows authentication. Figure 4 shows the results for remote access.
Windows Authentication Issues
In Windows (NTLM) authentication, when you browse to the HostPDS site from a remote computer, IIS does not pass Windows credentials more than one hop (see Figure 8). IIS on the remote computer cannot pass the credentials to a back-end server such as a SQL Server database on another computer for authentication, or through a SOAP request to the PDS Web service. The browser client passes your Windows credentials in an HTTP request to IIS on the Web server. IIS authenticates your credentials and grants a Windows access token that it passes to ASP.NET, which in turn creates a SOAP packet that contains the Project Server logon cookie.
Figure 8 shows that the logon request is in an HTTP request, and access to the PDS Web service is in a SOAP request. If the logon fails, no Project Server logon cookie is available to pass in the SOAP packet.
Figure 8. IIS blocks Windows logon credentials in HTTP packets over more than one hop
When the ASP.NET application is on the local computer, the HTTP packet header contains the Windows credentials. When the ASP.NET application is on a remote computer, one hop is used between the client and the server with the NTLM challenge/response process. The SOAP envelope is passed in an HTTP packet. ASP.NET does not include the Windows credentials in the HTTP packet on the remote computer because the HTTP request to the Project Server logon page or the PDS Web service is a second hop.
The recommended way to solve the problem is to configure Kerberos network authentication to allow delegation of a Kerberos security ticket. Windows Integrated authentication uses the Kerberos security ticket if it is available. Both Windows 2000 Server and Windows Server 2003 implement Kerberos security. The domain controller and your Web server must be running the same operating system, and you must be an administrator on the domain controller to configure Kerberos delegation.
Kerberos security delegation is unconstrained in Windows 2000 Server; that is, a server can impersonate the client when connecting to any other computer. Windows Server 2003 can be more secure because it enables finer-grained control with constrained delegation. You can configure a specific server so that it can delegate only to another specified server.
For more information, see Accessing Secured Web Services from Windows SharePoint Services Applications. You can also search for Kerberos delegation in Windows Server 2003 Help.
Encrypted Credentials
You can also encrypt a user's credentials in the registry of the target Web server with the aspnet_setreg.exe application, available from the Microsoft Download Center. For example, type the following in a Command Prompt window:
You have created the registry key HKLM\SOFTWARE\HostPDS\identity\ASPNET_SETREG with encrypted values for user name and password. You also need to grant read permission for the key HKLM\SOFTWARE\HostPDS and its children to that user, using the Registry Editor. You can access the credentials in web.config as follows:
The disadvantage is that your PDS application is limited to the Project Server permissions available to that one user; or, to put it another way, all users of your application gain the permissions of the impersonated user. For more information, see Microsoft Knowledge Base Article – 329290: How To Use the ASP.NET Utility to Encrypt Credentials and Session State Connection Strings.
Creating an ASP.NET Application with the PDS Web Service
When you create a virtual directory in IIS and then generate a new ASP.NET application, Visual Studio .NET 2003 generates a generic Web application in the local path you specified in IIS. General information on developing ASP.NET applications is available in many places. The following topics discuss the basic steps and typical issues for using the PDS in an ASP.NET application.
- Modify the default web.config file. See Modifying Web.config.
- Set a reference to the PDS Web service, get a logon cookie, and send an XML request to the PDS object. See Using the PDS Web Service.
Modifying Web.config
The web.config file for your application can usually override or add settings to the root web.config file for the default Web site.
Note The system administrator can modify the machine.config file to disallow some application-level changes. This is not usually an issue on a development or test computer, but can be when you install the application on a production Project Server. The machine.config file for .NET Framework 1.1 applications on Windows Server 2003 is located in the following directory:
To develop a PDS application, you generally need to do three things to the web.config file that ASP.NET generates:
- Add HTTP handlers and modules that let the PDS application coexist with Windows SharePoint Services.
- Disable validation for HTTP requests in .aspx pages.
- Add impersonation for Windows authentication.
Coexist with Windows SharePoint Services
As previously described in Installing a Test Web Site, if the development computer includes Windows SharePoint Services, you must add the following elements within the <system.web> section of web.config for the PDS application. You can comment out the <httpHandlers>, <trust>, and <httpModules> sections to use on computers that do not" />
The <httpHandlers> section clears the existing handlers for .aspx pages and adds the default for ASP.NET. In the add element, all of the type attribute must be on one line. You can specify full trust within the intranet, because Project Server manages the logon and security for PDS requests. You also need to add the session module in the <httpModules> section, if it is not already added in Windows SharePoint Services.
View state allows ASP.NET to maintain the state of server controls such as text and list boxes after an HTTP post-back from the server. You can enable view state for all pages in the PDS application, as shown in the pages element. However, not all of the pages in your application need to maintain view state. You can also enable view state on a page-by-page basis in the @page directive in each .aspx file.
You do not need to enable message authentication code (MAC) validation if there is only minor or nonsensitive information that is returned in the view state, because the extra encryption step impacts performance. Following is an example @page directive for Default.aspx.
Disable Validation
You should disable validateRequest globally for pages in a PDS application; otherwise, ASP.NET throws an HttpRequestValidationException error because it categorizes PDS requests as potentially dangerous.
Authentication with Impersonation
You can enable impersonation with the identity element in web.config. A PDS application should use Windows authentication in the intranet. When IIS authenticates a user, it passes a token to ASP.NET that can impersonate the user to other resources such as servers and file shares. Because identity is related to authentication, it is helpful to put the two elements near each other.
You should not add the username and password attributes to the identity element, for two reasons:
- Web.config would contain the password in clear text. Even though ASP.NET does not allow a Web application to see web.config, other people who have file system access to the server could see it.
- All users would impersonate the same user, thereby bypassing the built-in permissions and security in Project Server.
Note You could encrypt the user password and store it in a secure registry key. However, that would still bypass Project Server security. For other kinds of Web applications that need to impersonate a specific user or group, see Microsoft Knowledge Base Article – 329290: How To Use the ASP.NET Utility to Encrypt Credentials and Session State Connection Strings.
Authorization
ASP.NET includes extensive support for authorization, which determines whether the authenticated user is allowed to access specific resources. The sample HostPDS application does not include authorization code. Following are three forms of authorization that work with Windows authentication:
- Access control list (ACL)-based for file access.
- URL-based, as specified in the <authorization> section of web.config.
- Programmatic authorization, where a page or action can be modified at run time based on a user's role. For example, in the Page_Load event handler, you can hide or show controls when the page is initialized.
For more information on web.config and related topics, see ASP.NET Configuration and @Page.
Using the PDS Web Service
You take three general steps to use the PDS Web service:
- Add the PDS Web reference.
- Get a Project Server logon cookie.
- Send an XML request to the PDS object.
Add the PDS Web Reference
The PDS Web service is defined by pds.wsdl in the IIS Virtual Root directory of the Project Server installation. You can add a reference to the PDS Web service from the local computer, if it has Project Server installed, or add a reference to the PDS Web service on a remote computer.
After you add the PDS Web reference, you can easily access it in code through its namespace.
To add the PDS Web service as a Web reference:
- Add System.Web.Services as a reference for your project. Right-click References in Solution Explorer and then click Add Reference. On the .NET tab of the dialog box, click System.Web.Services.dll, click Select, and then click OK.
- Add the PDS Web reference on the local or remote computer. If you have installed the sample database with the site name Sample, and you have created the pdsSample.wsdl file as described in Using the PDS with Multiple Project Server Sites, pick the PDS Web service for the Project Server site you want.
- If Project Server is on the local computer, in the Add Web Reference dialog box, click Web services on the local machine. When you scroll through the list of Web services, there may be several PDS entries, as shown in the following table.
Table 3. PDS Web services
Note If the sample database is installed, the list of PDS services is repeated because the ProjectServer and Sample virtual directories both point to the same local directory. That is, you can see the same pds.wsdl file in Serverand in. To be consistent, you should pick the pds service in the Project Server site or the pdsSample service in the Sample site.
- If Project Server is installed on a remote computer, in the Add Web Reference dialog box, type the URL of the PDS WSDL file, and then click Go. For example, type:
Or, you can access a different Project Server virtual directory. For example, type:
- Type a name in the Web reference name field and then click Add Reference, as shown in Figure 9. For example, type PDSWebSvc. The name cannot have spaces or other non-alphanumeric characters because it is used as a namespace in the code you write.
Figure 9. Adding a Web reference to the PDS
You can see in the Add Web Reference dialog box that the primary public method is SoapXMLRequest. Visual Studio .NET adds the Web reference to the project, and creates the Web References directory with a subdirectory for each Web reference added to the project. You can add more than one Web reference. For example, you could add references to two different Project Server sites. Figure 10 shows two Web references PDSWebSvc and PDSProjSvr2.
Get a Project Server Logon Cookie
The logon routine in the HostPDS sample application is in a separate class in the Utilities.cs file, so the LogonProjectServer method and other utilities are easier to reuse for other applications. Following are the key parts of the click event handler for the Get Project List button.
private static string psLogonURL; //ASP page for Project Server logon private Utilities utils = new Utilities(); . . . private void btnGetProjectList_Click(object sender, System.EventArgs e) { if (radWindows.Checked) psLogonURL = txtURL.Text + "/LgnIntAu.asp"; else { . . . psLogonURL = txtURL.Text + "/LgnPsAu.asp" + "?un=" + txtUserName.Text + "&pwd=" + pwd; } try { string textInReply = txtReturn.Text; if (utils.LogonProjectServer(psLogonURL, ref psCookie, ref textInReply)) { //Logon is OK GetProjectList(); } . . . txtReturn.Text += textInReply; } catch(Exception ex) { . . . } }
The psLogonURL variable is set with the ASP page and URL options for logon to Project Server. For example, the value of psLogonURL for Project Server authentication on a default Project Server site is the following:
The value for Windows authentication on the same site uses a different ASP page and does not need any URL options:
Note The.
The LogonProjectServer method creates the object httpRequest that sends information to the URL in psLogonURL, and the object httpResponse that stores the response from the Project Server ASP logon page. The HTTP header in the request carries the user's Windows credentials. The Project Server ASP page requires a cookie container in the SOAP request, in which to store the Project Server logon cookie. A successful logon to Project Server returns a cookie string well over 10 bytes long. If the httpRequest cookie container is null, Project Server logon fails and returns the PDS status 5011 (no session cookie). Following are the key parts of LogonProjectServer.
public class Utilities { . . . internal bool LogonProjectServer(string logonUrl, ref string psCookie, ref string textInReply) { HttpWebRequest httpRequest = (HttpWebRequest)WebRequest.Create(logonUrl); HttpWebResponse httpResponse = null; CookieContainer conCookie = new CookieContainer(); httpRequest.CookieContainer = conCookie; httpRequest.Credentials = CredentialCache.DefaultCredentials; try //Return the response. { httpResponse = (HttpWebResponse)httpRequest.GetResponse(); XmlDocument xmlDoc = new XmlDocument(); xmlDoc.Load(httpResponse.GetResponseStream()); psCookie = GetLogonStatus(xmlDoc); if(psCookie.Length < 10) { textInReply = "Project Server logon failed.\nLogon Status = " + psCookie; psCookie = ""; return false; } return true; } catch(WebException ex) { . . . return false; } finally { // Close the response to free resources. If (null != httpResponse) httpResponse.Close(); } } }
LogonProjectServer extracts the text in httpResponse and stores it in the XmlDocument object xmlDoc. Following is an example of the reply from Project Server (the cookie value would be all on one line). The logon status HRESULT of 0 indicates success.
GetLogonStatus then extracts the logon cookie value from xmlDoc. If the logon is not successful, HRESULT is not 0, and LogonProjectServer returns an error message with the logon status that GetLogonStatus extracts.
You can use a successful Project Server logon cookie throughout a PDS Web application to send XML requests to the PDS. If your application accesses more than one Project Server site you need to store one logon cookie for each site.
The HostPDS application allows the user to change the Project Server URL, and stores the logon cookie in a static string member of the RenameProject class. You could alternately store the logon cookie in an ASP.NET session variable. A static boolean variable urlReset flag shows when the logon cookie must be renewed.
Send an XML Request to the PDS Object
You can learn a great deal about the object model of the PDS Web reference by viewing it in the Visual Studio Object Browser. Expand the Web References node in Solution Explorer, double-click the Web reference name such as PDSWebSvc, and then expand the object tree in the Object Browser. You can see the PDS class methods and all of the inherited base classes and interfaces. In Figure 10, the PDS class in the HostPDS.PDSWebSvc namespace shows four public methods: SoapXMLRequest, the PDS class constructor, BeginSoapXMLRequest, and EndSoapXMLRequest.
Figure 10. Object model of the PDS class
The sample HostPDS project shows a typical way to use a PDS Web reference. In Solution Explorer, click the Default.aspx file and then click View Code. To see the GetProjectList method, expand the region Get and show list of projects.
//Class variables Private static string psCookie; //Logon cookie from Project Server private static bool resetPDS; //Flag to initalize the PDS Web service . . . /*1*/ private static PDSWebSvc.PDS webSvc = new HostPDS.PDSWebSvc.PDS(); . . . private void GetProjectList() { string reply; projectSelected = false; try { /*2*/ If (resetPDS) { // Initialize the PDS Web service /*3*/ webSvc.Url = txtURL.Text + WSDL; /*4*/ webSvc.Credentials = CredentialCache.DefaultCredentials; resetPDS = false; } /*5*/ reply = webSvc.SoapXMLRequest(psCookie, PROJECTSSTATUS); . . . } catch(WebException ex) { . . . } }
To program with the PDS Web reference:
Note The following steps match the numbered lines in GetProjectList.
- Create an instance of a PDS object as a static class variable, for example webSvc. The static variable webSvc allows you to reuse the object in multiple calls to the PDS and pass it to other methods without reinitializing.
Figure 11 shows that if you have created the PDS reference within your project namespace (HostPDS in the sample), Visual Studio IntelliSense provides the correct namespace path and the PDS class constructor. If your PDS reference is within a different namespace, you must add the correct parent path to the type specification PDSWebSvc.PDS.
Figure 11. IntelliSense completion for the PDS class constructor
- Initialize the PDS object. The resetPDS variable is set to true in the Page_Load event handler; it is also set to true if the user changes the Project Server URL.
- Set the Url property of the PDS object to the path of the pds.wsdl file you want. If you set a breakpoint on the line indicated by step 2 and run the sample HostPDS application, you can see that line is equivalent to the following code for a default Project Server installation:
- Set the Credentials property to the default Windows credentials of the user. The SOAP header includes the Windows credentials.
- Call SoapXMLRequest of the PDS object and get the reply string. You can see in the Object Browser (Figure 10), or with IntelliSense (Figure 11) while you are writing the code that SoapXMLRequest takes two string parameters called sCookie and sXML. In the HostPDS sample the call passes a valid Project Server logon cookie, and the XML request string constant for the PDS method ProjectsStatus.
The reply string is the XML reply from the PDS. You can then process the reply using the many built-in methods in the System.XML namespace of the .NET Framework. The following methods in the HostPDS sample show examples of XML processing:
- FormatXML in Utilities.cs shows how to format an XML reply string from the PDS using StringReader, StringWriter, XmlTextReader, XmlTextWriter, and XmlDocument objects.
- RenameProject in Extenders.cs shows how to build an XML request for the Project Renamer PDS extension using StringBuilder, StringWriter, and XMLTextWriter. RenameProject processes the XML reply using XmlDocument, similar to the way LogonProjectServer processes the reply from Project Server.
Following are several other methods in the HostPDS sample that can be useful in Web applications. For the code, see the download that contains the sample (pj11HostingPDSApplications.exe).
- ShowMessage uses the methods RegisterStartupScript and RegisterClientScriptBlock to dynamically generate an ECMAScript (Microsoft JScript, JavaScript code) alert and confirmation messages in a page post-back. The script runs on the client, so it does not require a round trip to the server. After you select a project to rename in HostPDS, right-click an empty area in the browser and then click View Source. You can see the script that ShowMessage generates based on your selection, and the click event handler it attaches to btnRename.
Following is an example of a confirmation script in the HTML page the server sends to the browser.
- The Page_Load event handler checks if the browser supports client-side cookies. If so, Page_Load retrieves a cookie named ProjectServerURL from the user's computer, or sets a flag to create a persistent cookie that lasts a specified number of days.
Your production environment might have browser security restrictions on client-side cookies and ECMAScript (JScript, JavaScript) scripts. You can persist user variables in a database instead of using client-side cookies, although that is a little more work and impacts performance slightly. You can throw an exception or just show a different page for confirmation and alert messages instead of using ECMAScript (JScript, JavaScript).
In any case, HostPDS is a sample application that is not designed for deployment to a production Web server. Changes you should consider include adding custom error pages and removing unnecessary parts of the user interface such as the XML reply text box.
Using the Web Application in Project Web Access
One of the advantages of creating a Web application instead of a Windows client application is that you can quickly integrate a Web application with Project Web Access or with Project Professional, as well as with Windows SharePoint Services. You can use the HostPDS Web application in Project Web Access in two easy ways:
- Add a custom menu in Project Web Access that links directly to the Web application.
- Create a Web Part Page for Windows SharePoint Services or SharePoint Portal Server.
You can create a Web Part for HostPDS, add it to a Web Part Page, and access the Web Part Page with a custom menu or as a global or project-specific shared document within Project Web Access.
The following procedure shows how to add a submenu named Rename Projects to the Projects center.
To add a custom menu for a Web application link in Project Web Access:
- Click the Admin center, click Server configuration in the action pane, and then under Configuration options, click Menus.
- In the Name column, click Projects, and then click Add Custom Menu.
- In Add Custom Menu – Web Page Dialog, click Add a submenu. Type the submenu name Rename Projects, and then type the submenu URL. For example, if you installed the modified HostPDS application in the HostPDS virtual directory on the Project Server computer named Myserver, type the following URL.
- Restart Project Web Access, and test the Rename Projects link in the action pane of the Projects center.
Creating and using a Web Part
You can use a PDS-based Web application such as HostPDS in a Web Part, and add the Web Part to a Web Part Page for a shared document. For detailed information about creating and using Project Server Web Parts on Windows SharePoint Services and SharePoint Portal Server, see Project Server Web Parts and URL Options. The following procedures summarize one way to use the HostPDS sample application in a Web Part Page.
Note The procedures require that Project Server is integrated with Wi ndows SharePoint Services and that HostPDS is installed on your Project Server computer.
To create a Web Part with the HostPDS application:
- In the WebPart directory of the download, use any text editor to edit the file RenameProject.dwp. In the <script> section, change Servername to the name of your server. If you installed the HostPDS application in a different virtual directory, change the HostPDS name.
Note Place all of the string parameter for document.write on one line.
- In Project Web Access, click the Admin center, and then click Manage Windows SharePoint Services. In Enter information on the web server running Windows SharePoint Services, click the test URL for the public documents site. Following is an example:
- On the Project Workspace Home page, click the menu center Site Settings, and then click Go to Site Administration. In the Top-level Site Administration page, under Site Collection Galleries, click Manage Web Part Gallery.
- In the Web Part Gallery page, click Upload Web Part. Browse to the file you modified in step 1. In the Group section, click Default Web Parts in the drop-down list, and then click Save and Close.
You can click the new RenameProject.dwp Web Part to test it in the Web Part Gallery.
To create a Web Part Page using the RenameProject Web Part:
- In Project Web Access, click Documents, scroll to the bottom of the list, and then click Public Documents. Create a Web Part Page document library, if you don't already have one; for example, create a document library named Web Parts Pages. Make sure the Document Template in the shared library is Web Part Page.
- Click the Web Part Pages document library, and then click New Document. Type a name for the page, for example, type Rename Project. In the Layout section, click Full Page, Vertical, and then click Create.
- In the new Rename Project page, find Rename a Project in the Web Part List of the pane Add Web Parts. Click and drag Rename a Project to the Full Page area. The HostPDS application appears in the area, as shown in Figure 12.
Figure 12. Adding a Web Part to a shared document
You can use the Rename Project Web Part Page as a shared document in Project Web Access or in Windows SharePoint Services. You can also import the same Web Part into SharePoint Portal Server, and use a PDS Web application in shared documents throughout your organization.
You can add other Web Parts to the document and then use the modified page in a custom submenu in another part of Project Web Access. Following is the URL of the example Web Part Page for a submenu.
Using the Web Application in Project Professional
Project Standard and Project Professional can integrate any URL into a custom view. A custom view should operate seamlessly with or without the Project Guide showing, and should not interfere with operation of the Project Guide. It makes more sense to integrate HostPDS with Project Professional, because you can use Project Professional with Project Server and see the changed project names.
The sample files in the Custom Views subdirectory of the download include a modified version of the Task Form custom view sample in the Project 2003 SDK. For detailed information about developing and distributing custom views, and the original sample Task Form custom view, see Custom Views and the LoadWebBrowserControl Method.
New files in the HostPDS custom view sample are ProjectRenamerFrameWrapper.js, ProjectRenamerFrameWrapper.htm, and ProjectRenamerFrame.htm. The mainpage.htm file is unchanged from the original Task Form custom view sample, and includes Microsoft JScript functions as follows:
Project 2003 references the mainpage.js file using the custom pgmainpage:// protocol, which uses the network path of the custom Project Guide mainpage.htm specified in Project options. Project references the file util.js using the custom gbui:// protocol, which specifies the location of a compressed file in the Project installation that contains all of the default Project Guide files. Most of the mainpage.htm content and mainpage.js functions deal with the default Project Guide; they are slightly modified versions of the default Project Guide files.
The following procedure summarizes how the sample files are modified to add a custom view for the HostPDS application. Changes in the mainpage.js file are marked with the following comment: // AddedCV.
To add a custom view for the HostPDS application:
- In mainpage.js, define variables for the custom view frame wrapper and custom view frame content URLs, using the pgmainpage:// protocol. In the following code, the variables constProjectRenamerContentPage and constProjectRenamerWrapper refer to the new custom view content.
- Add a function that waits until the custom view frame wrapper is loaded.
// AddedCV. // This function gets called when the wrapper for the custom view // is loaded. It spins until the wrapper's load finishes. // ------------------------------------------------------ function loadFrameWrapperContentRenameCV() { var rFrame = rscript(); if (rFrame.document.readyState != "complete") { nUpdateCounter++; if (null != pageLoadTimer) { window.clearTimeout(pageLoadTimer); pageLoadTimer = null; } pageLoadTimer = window.setTimeout("loadFrameWrapperContentRenameCV()", constWaitTimeOut); return; } nUpdateCounter = 0; rFrame.viewFrame.location.replace(constProjectRenamerContentPage); }
- In the LoadWebPage event handler, add a case that loads the frame wrapper for each custom view. The custom view target page name is the target page specified in the Project Visual Basic for Applications (VBA) method LoadWebBrowserControl. The target page name can be any string except the reserved numeric strings "0" through "999". In the following code, ProjectRenamer1001 refers to the custom view for HostPDS.
function handle_LoadWebPage(targetPage) { . . . // AddedCV. // First, see if we're going to a page in the custom targetPage values. switch(targetPage) { . . . case "ProjectRenamer1001": var rFrame = rscript(); rFrame.location.href = constProjectRenamerWrapper; loadFrameWrapperContentRenameCV(); return; break; } . . .
You have made all the changes that you need in the mainpage.js file. The new frame wrapper ProjectRenamerFrameWrapper.htm file provides content that wraps the custom view, such as the following HTML anchor.
ProjectRenamerFrameWrapper.htm uses the related JScript file, ProjectRenamerFrameWrapper.js, to add its own LoadWebPage event handler and functions such as closeCustomView.
The ProjectRenamerFrame.htm file includes the actual HostPDS Web page URL in an <iframe> tag.
The next step is to set Project to use the custom mainpage.htm and make the custom view available from a toolbar button.
To add the custom view to Project Professional:
- In Project Professional, on the Tools menu, click Options, and then click the Interface tab.
- In the Project Guide Functionality and Layout Page section, click Use a custom page, and then browse to the URL of custom mainpage.htm. In the Options dialog box, click OK.
Because the mainpage.htm and related mainpage.js simply adds custom views to the default Project Guide, you can see no difference so far.
- Right-click the Project toolbar, and click Customize. In the Customize dialog box, scroll down the Categories list and click All Commands. Scroll down the Commands list, click LoadWebBrowserControl, and then drag it to a location you want in one of the toolbars.
- Right-click the LoadWebBrowserControl button you just added to the toolbar, and then click Assign Macro. In the Customize Tool dialog box, in the Name field, type Rename Project. Type a description if you want to see a ToolTip for the button.
- In the Command field, type the following command (all on one line).
The LoadWebBrowserControl parameters are targetPage and wrapperPage (for details, see LoadWebBrowserControl Method in the Project VBA Language Reference).
Note The targetPage parameter is the string specified for the Project Renamer case in the LoadWebPage event handlers, and wrapperPage uses the pgmainpage:// custom protocol to locate the frame wrapper content file.
- In the Customize Tool dialog box, click OK, and then click Close in the Customize dialog box for the toolbar.
You can now use the Rename Project button in the toolbar to load the HostPDS custom view. Figure 13 shows that the Project Renamer custom view does not interfere with the Project Guide.
Figure 13. HostPDS application in a custom view
You can also add custom Project Guide tasks and wizards that use PDS-based Web Part Pages. For information on developing custom Project Guides, see Project Guide 101.
Conclusion
The HostPDS application is a sample that shows how to access the PDS Web service and use PDS methods and extensions with ASP.NET. You can experience many advantages to using the PDS in an ASP.NET Web application, as follows:
- Use the productivity of the Visual Studio .NET development environment, the features of the .NET Framework such as built-in SOAP support, and the efficiency of ASP.NET.
- Access the Project Server API through a browser.
- Integrate PDS functions with Web Parts for Windows SharePoint Services and SharePoint Portal Server.
- Easily add PDS applications to extend Project Web Access.
- Extend Project Professional 2003 with PDS applications in custom views and Project Guides.
A limitation of HTTP messaging is that Windows authentication does not work across more than one hop to a Web application unless the domain server has Kerberos authentication configured. However, remote logon using HTTP messaging and Project Server authentication works if the PDS-based Web application is installed on the Project Server computer.
Additional Resources
- Getting Started: Developing with Project 2003 provides an overview of development technologies for Project clients and Project Server.
- Project Server 2003 PDS Reference is available online, and also as a separate download. It includes HTML Help topics that document all of the built-in PDS methods, the Service for Enterprise Data Maintenance, error codes, a sample application and PDS extension that use Visual Basic 6.0, and a PDS test tool with the Microsoft Visual C# source code.
- Project 2003 Software Development Kit is also available online and as a download. It includes the PDS Reference, along with Solution Starters and other sample applications that use the PDS.
- Project Renamer PDS Extender includes the PDS extension necessary for the HostPDS sample application.
- Project Server Web Parts and URL Options shows how to modify Project Web Access views and how to create and install custom Web Parts.
- Project Guide 101 includes information about Custom Views and the LoadWebBrowserControl Method.
- Creating a Managed Code PDS Extension for Project Server 2003 shows how to use Visual C# to build a PDS extension. The sample code includes a base class that encapsulates common methods for developing PDS extensions.
- SharePoint Products and Technologies Developer Center includes the SharePoint Products and Technologies 2003 SDK, and articles and resources for working with Windows SharePoint Services and SharePoint Portal Server 2003.
- Web Services Developer Center includes information about Web Services Enhancements 2.0 that helps development and deployment of secure Web services.
- Accessing Secured Web Services from Windows SharePoint Services Applications explains how to set up Kerberos security for Windows authentication over multiple hops.
Other Useful Resources
- Integrating Web Services and COM Components.
- Migrating from the SOAP Toolkit to Web Services.
- An Overview of Managed/Unmanaged Code Interoperability.
- Building Secure ASP.NET Applications: Authentication, Authorization, and Secure Communication.
- Building Secure Web Services.
- How To Implement Kerberos Delegation for Windows 2000.
- Microsoft Knowledge Base Article – 329290: How To Use the ASP.NET Utility to Encrypt Credentials and Session State Connection Strings.
Files in the Download
When you execute the download file pj11HostingPDSApplications.exe, it installs the following files in the default path
[Program Files]\Microsoft Office 2003 SDKs\Microsoft Office Project 2003 SDK\PDS Reference\HostingPDS.
Table 4. Files included in the pj11HostingPDSApplications.exe download