Getting Started with Development for Project 2010
Summary: Explore the major features for development and customization of Microsoft Project Server 2010 and the Microsoft Project 2010 client applications. Project Server 2010 includes a dual interface of Windows Communication Foundation (WCF) services and ASMX web services, plus other major new features for customization and development of Project Server extensions.
Applies to: Office 2010 | Project 2010 | Project Server 2010 | SharePoint Server 2010 | VBA | Visual Studio
In this article
Introduction to Project Server 2010
Project Documentation—Where to Find What You Need
Using VBA in Project 2010
Project Server Architecture
Integration with Microsoft SharePoint Server 2010
Project Server Interface
Events in Project Server 2010
EPM Reporting in Project 2010
Checking Errors in Project Server 2010
Conclusion
Additional Resources
Provided by: Jim Corbin, Microsoft Corporation
Contents
Introduction to Project Server 2010
Project Documentation—Where to Find What You Need
Using VBA in Project 2010
Project Server Architecture
Accessing Project Server 2010 Data
Caching, Queuing, Events, and Server-Side Scheduling in Project 2010
Integration with Microsoft SharePoint Server 2010
Project Server Security
Project Server Web Parts
Project Sites
Project Server Workflows
SimpleUI URL Options in Project Web App
Project Server Interface
Dual Interface: ASMX and WCF
Using DataSet Objects in the PSI
Impersonation and Extensions for the PSI
Using Windows PowerShell with the PSI
Events in Project Server 2010
- Using Datasets in Event Handlers
EPM Reporting in Project 2010
Reporting Database and the Report Data Service
Cube Build Service
Checking Errors in Project Server 2010
Conclusion
Additional Resources
This article is an update for Project 2010 of the Project Server 2007: Getting Started with a New Platform for Developers article.
Introduction to Project Server 2010
Microsoft Project Server 2010 is the fourth major release of Project Server, and extends the new development platform that Microsoft Office Project Server 2007 introduced. Project Server 2010 is more deeply integrated with SharePoint and requires Microsoft SharePoint Server 2010 with Enterprise Client Access License. Project Portfolio Services, workflows, authentication, Web Parts, the Project Web App ribbon, a new ECMAScript (JavaScript)–based grid control, project sites for team collaboration, and many other Project Server features build on the SharePoint Server 2010 platform.
This article briefly introduces development for the Project clients and provides a more detailed overview of development for Project Server and use of the Project Server Interface (PSI). Because Project Server 2010 is installed as a service in Microsoft SharePoint Server 2010, Project Server features such as workflow for demand management, the Project Web App ribbon, and project sites are built on SharePoint features.
The PSI adds services for workflow, portfolio analyses, and business drivers, and it extends the other services to support new features. These supported new features include departments, resource delegation, improved timesheet settings and security category management, multiple OLAP cubes, and project synchronization with SharePoint task lists. In the PSI dual interface, the Windows Communication Foundation (WCF) services duplicate the ASMX web services. WCF-based services are the strategic direction for development of distributed applications.
Project Server 2010 is built on the Microsoft .NET Framework 3.5. As the premiere enterprise project management (EPM) system, Project Server 2010 achieves the following goals for programmability:
Great extensibility Project Server 2010 addresses the key areas for extension of features for EPM and integration with Microsoft Office 2010 products, partner solutions, and line-of-business (LOB) applications.
Development platform The set of PSI services, Project Server Events Service, Project Server Queue Service, Project Server workflow system, server-side scheduling engine, Reporting database, and SharePoint features such as a Business Intelligence (BI) Center, custom lists, and Web Parts, create a complete development platform.
Low barrier to entry Developers who are familiar with Microsoft Visual Studio, standard SharePoint Web Parts, or Microsoft SQL Server Reporting Services can take advantage of the related functionality of the Project Server development platform.
Improved developer productivity The PSI services use Microsoft ADO.NET typed DataSet objects. Microsoft IntelliSense in Visual Studio immediately shows the methods, parameters, and fields that are available in a code statement. You can create, install, and test Project Server workflows and Web Parts, and modify many features of Project Web App and project sites, directly within Visual Studio 2010. You can access data such as timephased task information by using the PSI, instead of programming directly against the Project Server databases.
Firewall friendly All Project 2010 client applications, including Project Professional 2010 and Project Web App, communicate with Project Server through the PSI services by using the HTTP protocol, the SOAP protocol, or by using additional protocols through WCF. You can also work securely with Project Server by using a separate Project Web App server in a perimeter network for access across the Internet.
Project Server 2010, along with SharePoint Server 2010, offers many advantages and improvements. This article introduces you to the platform programmability and refers to in-depth conceptual and "how to" articles in the Project 2010 software development kit (SDK).
Project Documentation—Where to Find What You Need
There are four major avenues of Project documentation, each of which is designed for a different audience. Because you are reading this article, you are probably a developer. However, you might often need end-user, administrator, support or Knowledge Base (KB) information, and other Project downloads.
For more information about Project documentation, and places to find other resources, see Finding Project Server 2010 Documentation. For videos on using many of the new features in Project Server 2010, see Train & Learn. For courses with hands-on labs for the primary Microsoft products and technologies such as SharePoint, Silverlight, and SQL Server Business Intelligence, see MSDN Training Courses and SharePoint and Silverlight Training Course.
Developer Documentation for Project 2010
Following are the main parts of the Project 2010 SDK:
The Project Developer Center includes links to the main parts of the Project 2010 SDK and also to pages with developer information for earlier versions. The Videos and Webcasts | Project Development page on the Project Developer Center includes links to multimedia resources for Project 2010. The Project Developer Community page includes links to Project blogs, public forums, and other information about Project partners and Microsoft Most Valued Professionals (MVPs).
The online Project 2010 SDK Documentation includes current conceptual, how-to, and walkthrough topics, plus reference topics for the PSI services, related datasets, and Project Server programming libraries. At the bottom of each page of the online SDK you can find a Community Content section where you can post comments, add short code samples, or correct errors on the page. Community Content is a WIKI for MSDN; for developer discussions and help with questions, you can use the Project Customization and Programming forum.
The Project 2010 SDK download includes the complete SDK with a searchable HTML Help file (Project2010SDK.chm), source code for sample applications, Reporting database schema reference, OLAP Cube reference, XML schemas, updated IntelliSense files, and scripts for creating a WCF-based or ASMX-based proxy assembly for the PSI.
The Project VBA reference and help topics can be accessed from three locations. The topics are online in the Project 2010 Developer Reference, and also online or offline in Visual Basic Help when you are working in the Visual Basic Editor. You can access updated help topics online or offline for VBA if you click the Connection Status menu in the bottom-right of the Project Help window, and then click Show content from Office.com or Show content only from this computer. For example, the VBA object model maps work best in offline help. The MSDN rendering does not include links for the objects, and the online rendering for VBA Help is not optimal.
Many topics in the Project 2007 documentation also apply to Project 2010. For example, see the Project 2007 Technical Articles and Project 2007 Book Excerpts sections. SDK topics such as How to: Use a Filter Parameter with PSI Methods, Walkthrough: Creating a Hierarchical Lookup Table, and How to: Customize E-Mail for Project Server Notifications use general procedures that are the same in Office Project Server 2007 and Project Server 2010.
The online Project 2010 SDK is currently available in English and in Japanese. The Japanese release can lag the English release by several months. For the Japanese version, see https://msdn.microsoft.com/ja-jp/library/ms512767.aspx.
Administrator Documentation for Project 2010
Microsoft Project Server on TechNet is the place to look for information about Project installation, migration, and administration. The TechNet content includes the end-user documentation for Project Web App. The Project Server 2010 technical library is also available in a download; see Microsoft Project Server 2010 Technical Library in Compiled Help Format.
Following are major sections for Project 2010 in TechNet:
Microsoft Project Server 2010 is the website for Project Server on TechNet. Project Server 2010 is the top Project Server section in the TechNet Library. It includes sections for evaluation, planning, deployment, operations, security information, and troubleshooting for Project Server.
Technical Reference for Project Server 2010 includes sections for Windows PowerShell commands for managing Project Server and references for security permissions.
Newly Published Content for Project Server 2010 is updated regularly, and helps you keep up with information for Project Server administrators.
Downloadable Content for Project Server 2010 includes some of the technical library content in Microsoft Word format.
Note
The Project technical library is currently available only in English. For a list of TechNet centers in other countries, see TechNet Worldwide.
For the latest information about administrator documentation for Project Server, see the Enterprise Project Management Content Publishing News blog.
End-User Documentation for Project 2010
Context-sensitive help is available within Project Standard and Project Professional. As with VBA Help, to get updated content, click the Connection Status menu in the bottom-right of the Project Help window, and then click Show content from Office.com. When you are using Project Web App, for context-sensitive help, click the Help icon in the upper-right corner of the page.
For online access to all current Project Help topics, see the following:
Project Help and How-To is for Project Standard and Project Professional, and includes resources for top issues and videos about how to use Project.
Project Server Help and How-To includes the online Project Web App help and many other resources. Links to new topics for Project Server 2010 include information and videos about the Business Intelligence (BI) Center, creating a project proposal, security permissions, and defining phases and stages for a project life cycle.
Project Reference includes the Fields Reference, Project specifications, and a variety of other reference topics.
Note
Project managers often use formulas to calculate values for custom fields or to use with graphical indicators. For descriptions and syntax of the functions that are available for writing formulas, see the Reference section of Help in Project Standard or Project Professional, or see Project Functions for Custom Fields on Office.com. Project 2010 uses the same Jet Expression service for formulas that Microsoft Access 2010 uses. For general examples and more information about formulas and expressions, see Guide to Expression Syntax in the online help for Access and Functions (Category List) in the MSDN Library.
Available Languages for Project End-User Help Online Project help pages show the default language that is set in the Region and Language dialog box in the Control Panel for your computer. For other countries and languages, you can replace the culture name code in the URL for an end-user help topic. For example, the English URL for the Project Server Help and How-To page is https://office.microsoft.com/en-us/project-server-help/. The French URL for the Project Server Help and How-To page is https://office.microsoft.com/fr-fr/project-server-help/. For a list of languages and the culture name codes that Project Server supports, see the PSSupportedLanguages Class topic.
For more information about a wide variety of subjects, see the official blog of the project team: Microsoft Project 2010.
Support Documentation and KB Articles for Project 2010
The Microsoft Customer Service and Support team maintains the Knowledge Base (KB) site with many how-to and troubleshooting articles for Project 2010.
Tip
For a list of topic categories for the KB articles, and links to the search and RSS feed pages, see Support for Microsoft Project.
New KB articles are immediately machine-translated to Japanese, French, Spanish, and German. The Customer Service and Support team has created many new KB articles and updated many legacy KB articles for the release of Project 2010.
The Project support page includes links to find email, online, and phone support from Microsoft.
You can ask questions and find answers to many questions in the Project forums, which have replaced the newsgroups. For general information about the forums, see Welcome to the MSDN Forums. Following are the four public forums for Project:
Project Standard and Professional General Questions and Answers
For Project Server forums, see the following:
Project Server General Questions and Answers This forum is for end-user questions.
Project Server—Setup, Upgrade, Administration and Operation This forum is for Project Server administrators.
Project Customization and Programming This forum addresses programming for Project Standard, Project Professional, and Project Server.
For the latest information about Project support, see the Microsoft Office Project Support Weblog.
Downloads for Project 2010
You can find all downloads for Project by searching the Microsoft Download Center.
To find all downloads for Project 2010
Browse to the Microsoft Download Center.
In the search text box, type Project 2010, and then press Enter.
To filter or sort the list of results, open the Refine Results dialog box, select the filter and sorting parameters, and then click Go.
To find downloads that apply to more than one Office product, type the product names in the search box. For example, search for Project Visio to find the Visio 2007 WBS Modeler.
Documentation for Other Office Products and Technologies
You can integrate Project 2010 with other Microsoft Office products to create a wide variety of Office Business Applications.
To easily find developer documentation and other documentation for the 2007 Microsoft Office system products, you can use the interactive Microsoft Office 2010 Developer Map. For a PDF file that shows all of the Office 2010 client and server products and related technologies, see Office 2010: Developer Map Poster.
Figure 1 shows the Desktop Applications page of the Office 2010 Developer Map. The interactive map includes relationships of all of the Microsoft Office client applications, server applications, mobile applications, services and Office 365 applications, and related technologies, development tools, and platform components. After you install the Office 2010 Developer Map, you can click any item to see a page for that product or feature with links to online documentation.
Figure 1. Microsoft Office 2010 Developer Map
.gif "Office 2010 Developer Map")
Using VBA in Project 2010
Although this article focuses on Project Server 2010, the VBA object model in Project Standard and Project Professional is very widely used. You can use VBA to automate the Project desktop clients with macros and to integrate Project with the other Office 2010 applications to create comprehensive business solutions. For complex solutions, we recommend that you use Microsoft Office development tools in Microsoft Visual Studio 2010 instead of VBA. For more information, see Project Client Programming.
Macros and Custom Ribbon Commands The easiest way to create a simple macro is to use the Record Macro command on the Developer tab of the ribbon, and then manually perform the steps that you want the macro to contain. To show the Developer tab, click Options on the File tab, click Customize Ribbon in the Project Options dialog box, and then select Developer in the Main Tabs list. You will likely need to edit the recorded macro in the Visual Basic Editor to adjust and simplify it.
Because Project Standard 2010 and Project Professional 2010 use the ribbon user interface instead of a toolbar and menus, there are new methods for adding a custom command button. See How to: Use VBA to Add a Custom Command to the Ribbon and How to: Use Managed Code to Add a Custom Command to the Ribbon.
For general information about creating and editing VBA macros, see the Office Developer Center and Getting Started with VBA Development in Office 2010. For specific articles about Project VBA, see the Using Events chapter and the Working with Timephased Data chapter from VBA Programming for Microsoft Office Project Versions 98 Through 2007. There are additional how-to articles for Project VBA in the Project 2007 SDK, such as Calendar Exceptions and Effective Work Weeks and Using VBA with Local Custom Fields and Outline Codes.
Tip
The only book on VBA programming for Project is now updated to include Project 2010. See VBA Programming for Microsoft Project '98 through 2010 with an Introduction to VSTO.
To deploy a macro to other Project Standard users, you can distribute a project .mpp file or .mpt file that contains the macro. For example, you can post the project file in a SharePoint document library, and provide instructions for copying and using the macro. To use a macro for all projects on a local computer, copy the macro to the local global template. To copy to the Global.mpt file, you can use the Organizer on the Developer tab of the ribbon.
To deploy a macro to a group of Project Professional users, you can check out the enterprise global template, and then copy the macro to the enterprise global template in Project Server. You can then create a custom ribbon command, and copy that to the checked-out enterprise global template.
Note
On the Developer tab in the Project Professional ribbon, click Open Enterprise Global. To copy macros, open the Organizer, and then click the Modules tab in the Organizer dialog box. In the left pane of the Organizer, select a VBA module, and then select Checked-out Enterprise Global from the right pane.
Automating Project by Using Visual Studio Office development tools in Visual Studio 2010 provides advantages for developing more complex, secure, and scalable solutions that automate the Project 2010 desktop clients and other Microsoft Office applications. ClickOnce publishing in Visual Studio greatly simplifies developing, testing, and deploying advanced solutions that include the Project desktop client.
For an overview of changes for VBA developers in Project 2010, see VBA Object Model Changes. For more information about Office development tools in Visual Studio 2010, see the Office Development with Visual Studio Developer Center on MSDN. For a detailed example of a Project 2010 add-in developed with Visual Studio 2010, see Walkthrough: Building a Managed Code Add-in to Check PWA Compatibility.
Note
Add-ins for Project 2010 must be updated to work with both 32-bit and 64-bit versions. For more information, see Office Talk: Working with VBA in the 32-bit and 64-bit Versions of Office 2010.
Project Server Architecture
The architecture of Project Server 2010 is multitiered. The presentation tier includes Project Web App, Project Professional 2010, and third-party client applications. The application services tier includes the PSI services, the business logic, and SharePoint Server 2010. The data tier includes the Data Access Layer (DAL) components and multiple Microsoft SQL Server databases. Figure 2 shows a simplified view of the Project Server architecture. For more detailed information, see Project Server 2010 Architecture.
Figure 2. Project Server 2010 architecture
.gif "Project Server 2010 architecture")
Project Server supports multiple virtual sites of Project Web App. You can install one or more instances of Project Web App on the same computer as the Project Server core components, or on separate computers within the same SharePoint server farm. Each instance of Project Web App uses the same core Project Server and other shared services, but separate databases. For example, the following two Project Web App virtual site collections require a total of eight Project Server databases and share the configuration and content databases of SharePoint Server:
https://ServerName/pwa/
https://ServerName/pwaTest/
In the previous examples, pwa and pwaTest are names of the Project Web App virtual site collections. Each virtual site has its own independent list of authorized users that is stored in the SharePoint content database. Project Server databases do not store user logon information. The pwa site, for example, uses the databases named ProjectServerDraft, ProjectServerPublished, ProjectServerArchive, and ProjectServerReporting. The pwaTest site uses the independent databases named TestDraft, TestPublished, TestArchive, and TestReporting. You can install the databases on different computers running SQL Server 2005 or SQL Server 2008.
Project Web App is built with Microsoft ASP.NET 3.5 and uses compiled assemblies that interact with Project Server through the PSI. ActiveX controls are eliminated in Project Web App pages and replaced by the new JS Grid control in SharePoint 2010. Developers do not have access to the code behind the Web Parts and ASPX pages in Project Web App. However, you can access the JS Grid control object model to modify and extend Project Server Web Parts that use the JS Grid control. You can also modify the Project Web App ribbon and use the SharePoint Server object model to create your own Web Parts that interact with Project Server Web Parts. The Microsoft Visual C# or Microsoft Visual Basic code in your extensions is not exposed to other developers. For examples, see How to: Modify the Ribbon in PWA, Walkthrough: Customizing the PWA Ribbon and Accessing the JS Grid, and Walkthrough: Creating a Project Server Web Part with a JS Grid.
Project Web App uses SharePoint Server 2010 for authentication and as a web server. For more information about how Project Web App works with the PSI when it is installed on a separate computer, see Project Server 2010 Architecture in the Project 2010 SDK.
Accessing Project Server 2010 Data
Project Professional 2010 and all third-party applications communicate with Project Server 2010 only through the PSI. In versions of Project Server before 2007, Project Professional used ODBC for direct access to Project Server databases. ODBC cannot be used through most corporate firewalls. Project Professional 2010 eliminates the need for direct database access, except for the Reporting database. The Reporting database can be installed on a computer running SQL Server, separate from the other Project Server databases.
Warning
Nothing prevents you from using direct programmatic access to the Draft, Published, and Archive databases. You should be aware that the Project Professional cache, the Publishing database, and the Reporting database all rely on a cache synchronization protocol that can be disrupted by direct data editing. If you damage your Project Server databases or corrupt Project Professional client-side caches by using direct access to change data, be warned that product support will not be able to help.
The PSI is the interface between your application and the business object layer. Business objects in Project Server are the components that include the rules for how logical entities such as Project, Task, Resource, and Assignment can be changed and how they interact with each other and with the other Project Server components. Each logical entity can span multiple database tables. Because all client applications go through the PSI and use the same business logic, Project Server maintains the correct relationships between the business objects. The business objects do not directly interact with the Project Server databases; they call the DAL, which handles transactions with the correct database tables.
Not all Project Server data is available through the PSI. For example, most of the enterprise calendar data is a binary image (a BLOB) field in the Published database. PSI methods can create, read, and update enterprise calendar exceptions, but cannot manage data for work weeks. To manage work week data, you must use Project Professional (or a VBA macro, or a Project add-in).
Try the Reporting Database
In some cases, it is easier to read Project Server data by using the Reporting database than by using the PSI. For example, you can quickly get the value of a custom field that uses a lookup table, because Project Server creates an OLAP view and a user view in the Reporting database for each custom field. For example, the built-in MSPLT_Department_UserView contains data for departments that are defined in the Department lookup table in Project Web App. The following query lists the first nine departments in the lookup table, plus the special Null member.
SELECT TOP 10 [LookupMemberUID]
,[MemberValue]
,[MemberDescription]
FROM [ProjectServer_Reporting].[dbo].[MSPLT_Department_UserView]
For the Reporting Database schema reference, see the Project 2010 SDK download. The schema reference includes views for the built-in custom fields that use lookup tables, such as Cost Type, Health, and RBS. For custom fields that do not use a lookup table, you can use the project view, resource view, or task user view. For example, the following query finds the value of a task custom field named Test Number, for all tasks in the specified project.
SELECT task.[ProjectUID]
,[TaskName]
,[TaskIndex]
,[TaskDuration]
,[Test Number]
FROM [ProjectServer_Reporting].[dbo].[MSP_EpmTask_UserView] AS task
INNER JOIN [ProjectServer_Reporting].[dbo].[MSP_EpmProject_UserView] AS proj
ON task.ProjectUID = proj.ProjectUID
WHERE proj.ProjectName = N'My Swell Project'
For more information, see Custom Fields and the Reporting Database.
Caching, Queuing, Events, and Server-Side Scheduling in Project 2010
The local cache in Project Professional 2010, with the Project Server Queue Service, enables offline work and reduces the time that is required to open and save projects. When a project manager reconnects after working offline, Project Professional sends a message to the Project Server Queue and saves only the changed data. The Project Server Queue handles saving the data asynchronously, and the project manager can exit Project Professional or get back to work.
The Project Server Events Service is a major feature that enables extending Project Server functionality. Developers can create event handlers and register them programmatically by using methods in the Events service of the PSI or by using Project Web App. Each major business object (such as CustomFields, CubeAdmin, LookupTable, Project, Reporting, Security, and TimeSheet) includes multiple events that you can see on the Server Side Event Handlers page in Project Web App (https://ServerName/ProjectServerName/_layouts/pwa/admin/Events.aspx). Event handlers provide "hooks" for adding new functionality, customizing existing functionality, and integrating with other applications. For some examples, see Events in Project Server 2010 in this article.
The scheduling engine in Project Server 2010 is improved. In earlier Project versions, for example, when a team member reported a different amount of time than was scheduled for a task, the project manager had to open the project in Project Professional to reschedule the task and its dependents. Project Server 2010 can reschedule tasks. For example, you can implement a custom timesheet system and Project Server reschedules projects without requiring the data to make a round trip through Project Professional. However, the PSI does not include methods to directly call the Project Server scheduling engine.
Note
The public methods in the PSI support the most common and useful requirements for managing server-side projects and integration with other applications. The public PSI does not address all of the functionality of Project Professional or Project Web App, which also use methods and some private PSI services.
For more information, see What the PSI Does and Does Not Do.
Integration with Microsoft SharePoint Server 2010
Project Server 2010 requires Microsoft SharePoint Server 2010 with Enterprise Client Access License. All Project Web App features are based on SharePoint Server, including site administration, user authentication, workflow, Project Server Web Parts such as Project Center and My Tasks, and project sites that include lists of issues, risks, deliverables, and related documents. For an introduction to SharePoint architecture, see SharePoint 2010 Architectures Overview.
Project Server Security
SharePoint Server 2010 handles user authentication through claims processing, which is a new feature for SharePoint Server. SharePoint handles both Windows authentication and forms authentication for Project Server users. Project Server adds global permissions and category permissions for user authorization of various Project Server features and actions, which are accessible when you select a user in the Manage Users page in Project Web App.
The Security business object in Project Server (with programmatic access through the PSI Security service) manages security groups, categories, templates, and the global Project Web App permissions. The Security service can add existing permissions or remove permissions from the sets available for Project Server users. However, the Security service does not have a method for creating custom permissions.
Note
In Office Project Server 2007, you can create custom global and category permissions by modifying security tables in the Published database. The Walkthrough: Creating and Using Custom Project Server Permissions article is the only SDK example where an exception is made for directly changing the Published database. Custom permissions appear in the lists of permissions in Project Web App, where Project Server administrators can secure a third-party extension in the same way that they secure other Project Server features. In Project Server 2010, that process for creating custom permissions is obsolete. As an alternative, you could create your own user interface to manage custom permissions.
For information about how to incorporate the Project Server security model in reports, see Using Project Server Security in SQL Server Reporting Services Reports. For more information about Project Server security, including a discussion of global and category permissions, see the Project Server Security Primer in the Project Server 2007 SDK and Security and Protection for Project Server 2010 on TechNet.
Project Server Web Parts
The webpage development capability of Project Web App and SharePoint Server 2010 is built upon the .NET Framework 3.5. You can develop Web Parts for Project Web App just as you can for other SharePoint sites, because Project Web App is a SharePoint site. Visual Studio 2010 makes it much easier than in earlier versions to develop, deploy, test, and debug Web Parts. A new Visual Web Part project template provides a designer for Web Parts.
You can add Web Parts to Project Web App pages that include the Edit Page option on the Site Actions menu. Some pages, such as Portfolio Analyses and Server Settings, are designed for specific functionality and do not allow you to edit the page. However, Project Web App administrators can use the Quick Launch link on the Server Settings page to add sections and links to custom pages in Quick Launch. Figure 3 shows how easy it is to add Web Parts to editable Project Web App pages. Simply click Edit Page on the Site Actions menu, and then click Add a Web Part in the page section that you want. In Figure 3, the Issues Web Part is selected in the Project Web App category.
Figure 3. Adding a Project Server Web Part
.gif "Adding a Project Server Web Part")
Project Server 2010 includes 18 specialized Project Server Web Parts in the Project Web App category, such as Project Center, Project Details, and My Timesheet. SharePoint Server 2010 includes many more Web Parts, in several categories. (The JS Grid Examples category in Figure 3 is a custom addition that you would not see in your own Project Web App site). To see a list of the approximately 90 built-in Web Parts that are available for use in Project Web App, on the Site Actions menu, click Site Settings, and then click Web parts in the Galleries section.
Web Parts can use the System.Web.UI.WebControls.WebParts namespace in ASP.NET 3.5, or the Microsoft.SharePoint.WebControls namespace. For more information about custom Web Parts and which namespace to use, see Developing Project Server Web Parts.
Note
You can add Project Server 2010 Web Parts to other SharePoint sites if they are within the same server farm as Project Server. Project Server 2010 does not need to provision the other SharePoint sites.
With the target .NET Framework 3.5, both the Visual Web Part project template and the Web Part item template in Visual Studio 2010 create a Web Part with the .webpart file name extension. Project Web App also supports legacy Windows SharePoint Services 2.0 Web Parts (which have the .dwp file name extension), .ascx custom controls, and other extensibility features of Microsoft ASP.NET 2.0. We recommend that you build ASP.NET 3.5 Web Parts where possible, for compatibility with SharePoint Server 2010 and other ASP.NET 3.5 or Microsoft ASP.NET 4.0 applications that are not hosted by SharePoint.
Modifying Project Web App Pages
SharePoint Server 2010 uses master pages to control the look and feel of webpages within a site. However, Project Server does not allow the use of Microsoft SharePoint Designer 2010 to edit Project Web App pages or master pages, because SharePoint Designer cannot manage the integral code that accesses the PSI and other Project Server assemblies. You can make changes for Project Web App to incorporate your organization's branding, color scheme, and terminology; see the Look and Feel section on the Site Settings page. You can also add, remove, disable, change the appearance, or change the action of controls on the Project Web App ribbon. For more information, see How to: Modify the Ribbon in PWA.
The JS Grid control (part of Microsoft SharePoint Foundation 2010) replaces the ActiveX grid control that is used in previous versions of Project Server. The JS Grid control uses ECMAScript (JavaScript, JScript) for client-side modifications of the grid. For Project Web App pages that include a JS Grid control, you can use the JS Grid control object model and event handlers to modify the grid and add functionality; callbacks can also use server-side assemblies. For an example, see Walkthrough: Customizing the PWA Ribbon and Accessing the JS Grid. Your custom Web Parts can call PSI methods or third-party applications. For an example, see Walkthrough: Creating a Project Server Web Part with a JS Grid.
Project Sites
When you create and publish a project, by default you also create a project site for team collaboration. In earlier versions of Project Server, a project site was known as a project workspace. For example, the default site for a project named My Test Project is the following:
https://ServerName/My%20Test%20Project/default.aspx
You can specify another server that is running SharePoint within the same farm, or specify a different site name, when you use Project Professional or the PSI to create and publish projects. Project sites can include lists of documents, issues, risks, and project deliverables. A project manager can publish tasks or milestones as a list of deliverables for a project, and other project managers can subscribe to that list to get notifications of changes in dates. Publishing or subscribing to deliverables does not affect task scheduling on either project, but serves as a way to improve collaboration between projects.
A deliverable list is a specialized SharePoint list. The SharePoint 2010 SDK provides examples of how to develop custom lists. Because project sites are basic SharePoint sites that have some custom lists, you can use all of the SharePoint techniques for customization and extension, including modifying the master page with SharePoint Designer 2010. To create a new master page for project sites, manually create a project site that is not connected to a project (that is, where the site is not created by Project Server when you publish a project). Modify that site and then use its master page as the master page for the other project sites.
For information about modifying the template for project sites, see Extending the Project Workspace Template in the Project 2007 SDK. For information about using SharePoint list data such as issues, risks, and other custom lists, see the book excerpt, Importing SharePoint List Data into Project Server 2007 Custom Fields. The process also works for Project Server 2010. For more information about customizing project sites, see the SharePoint Developer Center.
Project Server Workflows
The Windows Workflow Foundation (WF) is a Windows-based platform component that is hosted and extended by SharePoint Foundation 2010. WF is a development framework, not a server or application, which provides a common workflow technology for SharePoint and other Windows applications. For more information about workflows in SharePoint, see What's New: Workflow Enhancements.
Project Server 2010 adds more extensions, and a restriction, to the SharePoint workflow platform. Project Server includes custom workflow activities, which can be used with the standard SharePoint and WF activities. You cannot use SharePoint Designer 2010 to develop Project Server workflows, as you can in SharePoint. Project Server workflows require development with Visual Studio 2010 on a Project Server computer.
Some tools in the Microsoft Project 2010 Solution Starters, which were introduced after the release of Project Server 2010, help in creating simple (non-branching) workflows and managing related features. Workflows are fully integrated into demand management and portfolio analyses. For more information about Project Server workflows, see Workflow and Demand Management and Developing Project Server Workflows.
SimpleUI URL Options in Project Web App
Project Web App pages still implement the legacy URL options, named SimpleUI, to hide or show various parts of the page, although these options are seldom used. In Project Server 2010, the SimpleUI setting is persisted as a cookie on the local user's computer. SimpleUI applies globally to the Project Web App pages, but not to other SharePoint sites in the farm that do not have Project Server provisioning. The ribbon, which is new in Project Server 2010, is not affected. For a simple example, the following URL hides the Quick Launch in Project Web App:
https://ServerName/ProjectServerName/default.aspx?SimpleUI=8
Now all the pages have the same elements removed, and you no longer see the SimpleUI option in other pages. To temporarily return to the default view for the current page, add ?SimpleUI=0 to any Project Web App URL. To persist the default view on all pages, add ?SimpleUI=16. Unlike the 256 combinations of SimpleUI in Project Server 2003, Project Server 2010 uses 32 bitmask combinations (0 through 31). For a table of URL options, see Scenarios for Custom Web Parts in the Project 2007 SDK.
Project Server Interface
The PSI includes a set of 22 public services (also called web services, when they are accessed through the ASMX interface). Most of the PSI services correspond to Project Server business objects, which are logical entities such as Project and Resource. The PSI has a Project service for the Project entity, a Resource service for the Resource entity, a TimeSheet service for the TimeSheet entity, and so on. Each PSI service includes one or more DataSet objects that contain data for that entity. Most PSI methods either use a DataSet parameter or return a DataSet object. For example, the QueueCreateProject method in the Project service sends a message to the Project Server Queue to create a project in the Draft database with the data specified in the ProjectDataSet parameter. Following is the signature of the QueueCreateProject method.
public void QueueCreateProject(Guid jobUid, ProjectDataSet dataset,
bool validateOnly);
The jobUid parameter enables you to track and manage the job in the queue by using methods of the QueueSystem service. PSI methods that start with the name Queue, such as QueuePublish and QueueCheckInProject, all run asynchronously; Project Server puts a message on the queue, and then passes control back to your application. Other methods, such as CheckOutProject and ReadProject, run synchronously; your application does not continue until the method completes.
The ReadProject method reads the specified project in a specified database and returns a ProjectDataSet object. All entities are identified in Project Server by a GUID. Some parameters in PSI methods use enumerations that are in the Microsoft.Office.Project.Server.Library.dll assembly, or sometimes in the PSI service. For example, the following is the signature of the ReadProject method.
public ProjectDataSet ReadProject(Guid projectUid, DataStoreEnum dataStore);
In the following code fragment of a call to the ReadProject method, the SvcProject namespace is an arbitrary name of a proxy for the Project service in the PSI. The value of the projUid variable is the GUID of a project that was previously saved to the Draft database (the working store).
using PSLibrary = Microsoft.Office.Project.Server.Library;
. . .
private static SvcProject.ProjectClient projectClient;
. . .
// Initialization of the projectClient object is not shown here.
Guid projUid = new Guid("8024BEB0-7814-44CF-98FF-4E74148E3404");
SvcProject.ProjectDataSet projDs =
projectClient.ReadProject(projUid, PSLibrary.DataStoreEnum.WorkingStore);
. . .
Dual Interface: ASMX and WCF
Because the WCF interface is defined in the Project Server application service in the back end of SharePoint Server, you cannot use Internet Explorer to view the WCF interface of PSI services. The WCF interface for each PSI service includes a primary class that contains the methods that you use to access the service. The primary class name has the Client suffix. For example, the primary class in the Project service is ProjectClient; in the Resource service, the primary class is ResourceClient.
There are several overloads for the constructor of a primary class. The common way to initialize a primary class is to define a WCF endpoint, and then use the name of the endpoint as a parameter, as in the following example:
projectClient = new SvcProject.ProjectClient("basicHttp_Project");
You can define a WCF endpoint programmatically or in a service configuration file such as app.config or web.config. For an example of an app.config file, see the Adding a Service Configuration File section in Prerequisites for WCF-Based Code Samples. For an example of programmatically defining a WCF endpoint, see the Configuring the Services Programmatically section in Walkthrough: Developing PSI Applications Using WCF. You can use a service configuration file when your application is stand-alone—that is, when your application does not affect the service configuration file of another application. To avoid modifying the app.config file for Project Web App itself, you must programmatically define a WCF endpoint when your application is an extension of Project Server, such as an event handler, a modification of the JS Grid control on a Project Web App page, or a PSI extension.
ASMX Interface Because the ASMX interface is accessed in the Project Web App front end, you can use Internet Explorer to see the ASMX interface of PSI web services. For example, change the following URL for your Project Web App instance, and then paste the URL into Internet Explorer:
https://ServerName/ProjectServerName/_vti_bin/PSI/project.asmx?wsdl
The primary class in the ASMX interface for each PSI web service is simply the name of the service. For example, the primary ASMX class in the Project service is Project; in the Resource service, it is Resource. In the following code snippet, ProjectWebSvc is the arbitrary namespace of a proxy for the Project service in the PSI. You can initialize the primary Project object simply by setting the Url property and the Credentials property, as in the following example.
using System.Web.Services.Protocols;
using PSLibrary = Microsoft.Office.Project.Server.Library;
. . .
ProjectWebSvc.Project project = new ProjectWebSvc.Project();
project.Url = "https://ServerName/ProjectServerName/_vti_bin/psi/project.asmx";
project.Credentials = CredentialCache.DefaultCredentials;
After initialization of the primary class in a PSI service, the remainder of the code in an ASMX-based application is the same as in a WCF-based application (except in cases where your application does impersonation or where the Project Web App instance uses both Windows authentication and forms authentication). For more information about using the ASMX interface, see Prerequisites for ASMX-Based Code Samples. Several PSI methods in the Project 2010 SDK include code examples for both the WCF interface and the ASMX interface; for example, see ReadProjectStatus.
We recommend that you use the WCF interface when you develop new applications that use the PSI services. The ASMX interface is available for legacy Project Server applications (those developed for Office Project Server 2007). For older applications developed for Project Server 2003 or earlier versions, you must completely rearchitect the applications to run on Project Server 2010. In many cases, the older applications can no longer work because of new features introduced in Office Project Server 2007 and Project Server 2010. For information about porting older Project Data Service (PDS) applications, see PDS Parity in PSI Web Services. For more information about the WCF and ASMX interfaces, see Overview of WCF and the PSI.
There Is a Quicker Way to Get Started
Using the WCF interface of the PSI can be confusing, because there are so many options in developing with WCF services in Project Server. There are three ways to add a WCF service reference, and there are two ways to configure the service (or three ways, if you use the Service Configuration Editor in Visual Studio, as described in the Configuring the Services with app.config section in Walkthrough: Developing PSI Applications Using WCF).
To simplify matters when you are starting to learn PSI development, try an example where the configuration is already done.
To create your first WCF-based PSI application
Install the Project 2010 SDK download. It is easier to install to a directory such as C:\Project_SDK, instead of to the default directory, to avoid permission issues when using the Visual Studio samples.
Extract the ~\Documentation\Intellisense\WCF\Source.zip file to the same subdirectory, and then run the CompileWCFProxyAssembly command in a Visual Studio Command Prompt window. That creates the ProjectServerServices.dll proxy assembly.
Open the Samples\ManagedCodeReference\CreateProject4Department.sln solution in Visual Studio 2010.
Note
You should work on a test installation of Project Server, if possible. For many applications (except workflows, or modifying Project Web App or project sites), you can develop on an external computer, but you then must copy the Microsoft.Office.Project.Server.Library.dll assembly and the ProjectServerServices.dll proxy assembly to the remote computer.
Set a reference to the ProjectServerServices.dll proxy assembly that you created in step 2, and ensure that the Microsoft.Office.Project.Server.Library reference is valid.
In the app.config file, change the endpoint addresses to use the correct server name and Project Web App name, for the ProjectServer.svc endpoint.
In the Program.cs file, change the directory name for the OUTPUT_FILES constant, if you want a different value.
Create one or more departments in the Department lookup table (use https://ServerName/ProjectServerName/_layouts/PWA/Admin/EditLookupTable.aspx?_guid=e7397277-1ab0-4096-b2dd-57029a055ba4), and then find the GUID of one of the departments, as described in comments in the Program.cs file. Change the value of the DEPARTMENT_TEST constant.
Compile and run the program. You should see the following output in the Visual Studio Command Prompt window.
XML output of the ProjectDataSet before QueueCreateProject: C:\Project\Samples\Output\ProjectDataSet4Department_before.xml Creating project: Test Dept 1 Waiting for job: ProjectCreate ................................................. XML output of the ProjectDataSet after ReadProject: C:\Project\Samples\Output\ProjectDataSet4Department_after.xmlPress any key to exit the Command Prompt window. If you get errors, ensure that you have correct permissions to access Project Web App and create projects. Also check the ULS logs, as described in Checking Errors in Project Server 2010.
Using DataSet Objects in the PSI
Every PSI service includes the DataSet classes it needs that correspond to information in the business entities. A DataSet object is essentially an in-memory relational database that includes a schema for tables, relationships, constraints, rows, and fields. Each DataSet object contains one or more DataTable objects that contain DataRow objects. Each DataRow includes one or more properties (data fields) and methods for managing the row. For example, the ResourceDataSet class includes subclasses such as ResourceDataTable and ResourceRatesDataTable, which correspond to the Resource table and the ResourceRates table. The ResourceDataSet.ResourceRatesRow subclass defines a row (that is, a resource cost record) in the ResourceRates table.
In the following code for the Demo_UpdateResource console application, the resourceDs variable contains a ResourceDataSet object.
Note
The definition of the "basicHttp_Resource" WCF endpoint in the app.config file is not shown here. You can adapt any app.config file for PSI sample solutions in the Project 2010 SDK download.
To handle FaultException errors in WCF-based applications, you should use try – catch statements for calls to PSI methods. In ASMX-based applications, you would catch SoapException errors. For more information, see the Code Example for WCF section and the Code Example for ASMX section in Project Server Error Codes.
using System;
using System.ServiceModel;
using System.Xml;
using PSLibrary = Microsoft.Office.Project.Server.Library;
namespace Demo_UpdateResource
{
class Program
{
private const string ENDPOINT_RESOURCE = "basicHttp_Resource";
private const string OUTPUT_FILES = @"C:\Project\Samples\Output\";
private static SvcResource.ResourceClient resourceClient;
private static string outFilePath;
static void Main(string[] args)
{
outFilePath = OUTPUT_FILES + "Demo_ReadResource.xml";
resourceClient = new SvcResource.ResourceClient(ENDPOINT_RESOURCE);
Guid myUid = resourceClient.GetCurrentUserUid();
SvcResource.ResourceDataSet resourceDs = resourceClient.ReadResource(myUid);
// Set cost per use to 1.25 USD.
double costPerUse = 1.25 * PSLibrary.ValidationConst.s_cost_multiplier;
if (resourceDs.ResourceRates[0].RES_COST_PER_USE != costPerUse)
{
resourceDs.ResourceRates[0].RES_COST_PER_USE = costPerUse;
if (resourceDs.Resources[0].IsRES_CHECKOUTBYNull())
{
Guid[] resourceUids = { myUid }; // Array of resources to check out.
resourceClient.CheckOutResources(resourceUids);
}
bool validateOnly = false;
bool autoCheckIn = true;
resourceClient.UpdateResources(resourceDs, validateOnly, autoCheckIn);
}
resourceClient.Close();
Console.WriteLine("XML output file for ResourceDataSet: {0}", outFilePath);
resourceDs.WriteXml(outFilePath);
Console.Write("\nPress any key to exit... ");
Console.ReadKey(true);
}
}
}
The Demo_UpdateResource does the following:
Initializes a ResourceClient object with the WCF endpoint.
Gets the GUID of the application user with the GetCurrentUserUid method.
Initializes a ResourceDataSet object with the ReadResource method. The ResourceDataSet includes one row in the ResourceRates table, which is accessed by ResourceRates[0].
Sets the cost per use value to $1.25 (on a U.S. English system). The RES_COST_PER_USE property uses the s_cost_multiplier field to convert the cost value.
Determines whether the cost per use of the application user is $1.25. If not, sets the RES_COST_PER_USE field to $1.25.
Determines whether the RES_CHECKOUTBY value is null; if so, check out the resource.
Updates the resource by using the UpdateResources method.
Note
In the Project 2010 SDK, the Remarks section in the topic for each method in the primary classes of PSI services shows which Project Server permissions are required to use the method. For example, the UpdateResources method uses four permissions, including the ManageUsersAndGroups global permission and the EditEnterpriseResourceData category permission. If the application user does not have all of the required permissions, the UpdateResources method call fails with an exception.
Closes the ResourceClient object, to help with garbage collection.
Serializes the ResourceDataSet object to an XML file for debugging purposes, by using the WriteXml method. The following example is part of the XML file, showing the updated RES_COST_PER_USE field.
<?xml version="1.0" standalone="yes"?> <ResourceDataSet xmlns="https://schemas.microsoft.com/office/project/server/webservices/ResourceDataSet/"> <Resources> <!-- Fields in the Resources table. --> </Resources> <ResourceCustomFields> <!-- Fields in the ResourceCustomFields table. --> </ResourceCustomFields> <CalendarExceptions> <!-- Fields in the CalendarExceptions[0] row.--> </CalendarExceptions> <CalendarExceptions> <!-- Fields in the CalendarExceptions[1] row.--> </CalendarExceptions> <ResourceRates> <RES_UID>efef7161-eb7f-43b0-8936-7247ca393453</RES_UID> <RES_RATE_TABLE>0</RES_RATE_TABLE> <RES_STD_RATE>12</RES_STD_RATE> <RES_OVT_RATE>15</RES_OVT_RATE> <RES_COST_PER_USE>125</RES_COST_PER_USE> </ResourceRates> <ResourceAvailabilities> <RES_UID>efef7161-eb7f-43b0-8936-7247ca393453</RES_UID> <RES_AVAIL_UNITS>100</RES_AVAIL_UNITS> </ResourceAvailabilities> </ResourceDataSet>
To debug the Demo_UpdateResource application during development and testing, for example, set a breakpoint on the statement that contains the UpdateResources call. When the application pauses execution, hover the mouse pointer over the resourceDs parameter, and then click the small magnifying glass icon to show the DataSet Visualizer dialog box. In the Table drop-down list, select ResourceRates (Figure 4).
Figure 4. Using the DataSet Visualizer during debugging
.gif "Debugging with the DataSetVisualizer")
After the application completes, if you open the Edit User page in Project Web App for that user, the Cost/Use text box shows $1.25.
Many of the code samples in the Project 2010 SDK use datasets. For example, the QueueCreateProject topic includes WCF-based and ASMX-based code samples that add rows to datatables in an empty ProjectDataSet, and then create a project. The ProjTool test application includes many examples that manipulate datasets in the PSI. The source code for ProjTool is available in the Project 2010 SDK download; see Using the ProjTool Test Application in Project Server 2010. For general information about datasets, see ADO.NET.
PSI Methods That Use an xmlFilter Parameter
Eight PSI methods for reading data use an XML string filter object in an xmlFilter parameter, which can limit the amount of data that the method returns in a DataSet. The filtering methods include ReadCalendars, ReadCustomFields, ReadCustomFields2, ReadLookupTables, ReadLookupTablesMultiLang, ReadResources, ReadResourceAssignments, and ReadResourcePlan. In most cases, if the xmlFilter parameter is an empty string, the method returns all of the data available to it; an exception is the ReadResourceAssignments method, which requires a non-empty string because there can be many thousands of assignments.
For example, the GetLookupTableFilter method in the following code creates an XML filter that limits the LookupTableDataSet to include only the LookupTableTrees table with the LT_UID, LT_STRUCT_UID, and LT_VALUE_FULL columns. The GetRbsValue method calls the ReadLookupTables method, and then iterates through the filtered LookupTableTrees table to find the full value of the RBS custom field that is specified by the lutValueUid parameter.
using PSLibrary = Microsoft.Office.Project.Server.Library;
. . .
private string GetRbsValue(Guid lutValueUid)
{
string rbsValue = string.Empty;
// Don't use a known LCID when ReadLookupTables uses a non-empty filterXml parameter.
int noLcid = 0;
PSLibrary.Filter lutFilter = GetLookupTableFilter();
string lutFilterXml = lutFilter.GetXml();
SvcLookupTable.LookupTableDataSet lutDs =
lookupTableClient.ReadLookupTables(lutFilterXml, false, noLcid);
for (int i = 0; i < lutDs.LookupTableTrees.Count; i++)
{
if (lutDs.LookupTableTrees[i].LT_STRUCT_UID == lutValueUid)
{
rbsValue = lutDs.LookupTableTrees[i].LT_VALUE_FULL;
break;
}
}
return rbsValue;
}
// Create a filter for the ReadLookupTables method.
private PSLibrary.Filter GetLookupTableFilter()
{
// Create an empty LookupTableDataSet, to get the table and column names.
SvcLookupTable.LookupTableDataSet lutDs = new SvcLookupTable.LookupTableDataSet();
string lutTableName = lutDs.LookupTableTrees.TableName;
string lutUidColumn = lutDs.LookupTableTrees.LT_UIDColumn.ColumnName;
string lutStructUidColumn = lutDs.LookupTableTrees.LT_STRUCT_UIDColumn.ColumnName;
string lutFullValueColumn = lutDs.LookupTableTrees.LT_VALUE_FULLColumn.ColumnName;
// Get the GUID for the built-in RBS lookup table.
Guid lutRbsUid = PSLibrary.LookupTables.RBS_LT_UID;
PSLibrary.Filter lutFilter = new PSLibrary.Filter();
lutFilter.FilterTableName = lutTableName;
lutFilter.Fields.Add(new PSLibrary.Filter.Field(lutUidColumn));
lutFilter.Fields.Add(new PSLibrary.Filter.Field(lutStructUidColumn));
lutFilter.Fields.Add(new PSLibrary.Filter.Field(lutFullValueColumn));
PSLibrary.Filter.FieldOperationType equal = PSLibrary.Filter.FieldOperationType.Equal;
lutFilter.Criteria = new PSLibrary.Filter.FieldOperator(equal, lutUidColumn,
lutRbsUid.ToString());
return lutFilter;
}
The complete Visual Studio solution is in the ReadRBS sample in the Project 2010 SDK download. For more information about using an xmlFilter parameter, see How to: Use a Filter Parameter with PSI Methods in the Project 2007 SDK.
Impersonation and Extensions for the PSI
Impersonating a user in a Project Server application is not as commonly used in Project Server 2010 as it is in Office Project Server 2007. For example, the ReadStatusForResource and SubmitStatusForResource methods do not require impersonation and supersede the ReadStatus and SubmitStatus methods. Project Server 2010 also has additional restrictions and requires more administrative settings. For more information and a code example, see How to: Use Impersonation with WCF.
You can extend the PSI itself with additional services. Methods in custom PSI services can call other PSI methods, for example, to check user authorization, use impersonation for specific jobs, consolidate multiple PSI calls on the server to save network traffic, or add new functionality to Project Server. For a simple WCF-based example named HelloService that also calls the ReadResource PSI method, see Creating a PSI Extension for Project Server 2010. The PSI extension is installed in the Project Web App front-end application; the URL, for example, is https://ServerName/ProjectServerName/_vti_bin/PSI/HelloService.svc?wsdl.
The PSI extension in the How to: Create a PSI Extension to Read Custom Fields in the RDB article uses a stored procedure in the Reporting database to find all of the projects that have a specified custom field value. The complete Visual Studio solutions for the PSI extension examples are in the Project 2010 SDK download.
Using Windows PowerShell with the PSI
Windows PowerShell scripts are often used to help with administration tasks for Project Server 2010 and SharePoint Server 2010. You can also use Windows PowerShell with the ASMX interface to call PSI methods. In the following example, use the actual name of the computer, not localhost. For example, if a Project Web App instance named PWA is on the 5050 port of the MyServer computer, change the $pwaUrl value to $pwaUrl = "http://MyServer:5050/pwa".
Note
Run the SharePoint 2010 Management Shell (in the Microsoft SharePoint 2010 Products folder of the Start menu) as an administrator. Every time that you run the following script, the Get-Credential command (known as a cmdlet in Windows PowerShell) requires that you type in your domain, user name, and password.
############################################################################
## Get-RegularProjectList
## Uses the PSI to get a ProjectDataSet.Project table that includes
## regular projects (not templates or proposals).
## The script user must have Project Server administrator permissions for the
## ReadProjectList method.
## To run on your Project Server computer, change the $pwaUrl value.
#############################################################################
$pwaUrl = "https://ServerName/ProjectServerName"
$svcProjectUrl = $pwaUrl + "/_vti_bin/PSI/Project.asmx?wsdl"
$c = Get-Credential
# Create a proxy for the Project web service, from the ASMX interface.
$svcProjectProxy = New-WebServiceProxy -uri $svcProjectUrl -credential $c
$svcProjectProxy.ReadProjectList().Project | Where-Object { $_.PROJ_TYPE -eq 0 } `
| Out-GridView –title "List of Regular Projects"
In the preceding code, the ReadProjectList method returns a ProjectDataSet with values for the following fields in the Project table: PROJ_UID, PROJ_NAME, and PROJ_TYPE. Figure 5 shows output in the grid view that is created with the Out-GridView cmdlet (which can be abbreviated as ogv) in Windows PowerShell. You can filter values in the grid view.
Figure 5. Filtering values in the grid view of output from Windows PowerShell
.gif "Using the grid view in Windows PowerShell")
The Project 2010 SDK includes several topics that show how to use Windows PowerShell for administrative activities such as deployment of custom solutions. For example, see How to: Deploy a Project Server Workflow and How to: Modify the Ribbon in PWA. See also the administrative script example in SetDatabaseTimeout. TechNet includes references for Windows PowerShell cmdlets for SharePoint and Project Server; see Windows PowerShell for Project Server 2010.
Although the preceding code example shows that you can easily use scripts with existing Windows PowerShell cmdlets that access the PSI to read Project Server data, there are several limitations. Besides typing in your credentials each time, limitations include the difficulty of using scripts on remote computers, complexity of scripts for jobs that create or update Project Server entities or require more than one PSI service, using hardcoded values instead of enumerations and fields in the Microsoft.Office.Project.Server.Library namespace, awkward debugging, and no IntelliSense. If you need more Windows PowerShell capability, a much better solution is to create custom cmdlets that access the PSI through the WCF interface. For more information, see the MSDN Code Gallery download in Microsoft Project 2010: Powershell Cmdlets for Project Server PSI.
Events in Project Server 2010
Every Project Server 2010 business entity (such as Project, Task, Assignment, CustomField, and Timesheet) includes events. Project Server implements more than 220 events, including both pre-event and post-event types. Pre-events occur before Project Server saves data to the database. An event handler for a pre-event can cancel the operation and is synchronous. That is, an application that uses a pre-event cannot continue until the event handler is finished. Post-events cannot be canceled (the data is already saved), and can be asynchronous or synchronous. Applications can subscribe to events such as the Project Publishing pre-event or the Project Published post-event and run one or more associated event handlers. When you register an event handler in Project Web App, you can specify the order in which Project Server runs multiple event handlers for one event.
Pre-events enable developers to add constraints, custom data validation, or business rule checks. For example, a corporate project management office (PMO) might require that all enterprise project text custom fields for certain projects have a two-letter prefix. A CustomField Changing pre-event handler could implement the business rule.
Post-events are the main way to integrate Project Server with an LOB application, such as an accounting system. For example, there are 14 TimeSheet events including Submitting, Submitted, Recalling, and Recalled. The Submitting and Recalling events are pre-events. You can create event handlers that check your organization's business rules before a timesheet is submitted to the database, and cancel the submission if the rules are not met. The Submitted and Recalled events are post-events. After a project manager submits timesheet data, a Timesheet Submitted post-event handler could send the weekly data to an accounting system.
When you create a class for a Project Server event handler, it inherits from an event receiver base class in the Microsoft.Office.Project.Server.Events.dll assembly. Event receiver classes include ProjectEventReceiver, CustomFieldsEventReceiver, and so on. You can create one or more event handler methods in one event handler class. Each event handler method overrides the base class method. For example, a CustomFieldsEvents class can include the OnCreating and OnCreated methods. The following code includes two event receiver classes with several event handlers.
using System;
using System.Diagnostics;
using System.Data;
using System.Xml;
using Microsoft.Office.Project.Server.Events;
using PSLibrary = Microsoft.Office.Project.Server.Library;
namespace TestEventHandlers
{
public class ProjectEvents : ProjectEventReceiver
{
public override void OnPublishing(
PSLibrary.PSContextInfo contextInfo,
ProjectPrePublishEventArgs e)
{
. . .
}
}
public class CustomFieldsEvents : CustomFieldsEventReceiver
{
public override void OnCreating(
PSLibrary.PSContextInfo contextInfo,
CustomFieldsPreEventArgs e)
{
. . .
}
public override void OnCreated(
PSLibrary.PSContextInfo contextInfo,
CustomFieldsPostEventArgs e)
{
. . .
}
}
}
Event handler methods include context information such as the user name and GUID, language, and Project Web App site GUID. The pre-event e parameter (the event arguments) includes the Cancel property along with other information about the entity or event. For example, ProjectPrePublishEventArgs for the project OnPublishing event handler includes the project name, GUID, and the SharePoint site URL for the project site. The event arguments parameter for a post-event does not include the Cancel property.
For a list of all Project Server events for PSI applications, see PSEventID in the managed code reference for the PSI. For an example OnCreating event handler for the ProjectCreating pre-event, see How to: Create a Project Server Event Handler and Log an Event.
Using Datasets in Event Handlers
Many Project Server events are directly related to PSI methods; for example, the QueueCreateProject method raises the Creating pre-event and the Created post-event. The event arguments parameter (e) in a pre-event handler or a post-event handler can include a DataSet for the entity, if the related PSI method uses a DataSet object. For example, the event arguments parameter for the OnCreated event handler of the CustomFieldsCreated post-event includes CustomFieldsPostEventArgs.CustomFieldInformation of type CustomFieldDataSet.
Note
To use a DataSet object in an event handler, you must set a reference to the Microsoft.Office.Project.Schema.dll assembly. The Microsoft.Office.Project.Server.Schema namespace includes the necessary class definitions such as CustomFieldDataSet.
You can copy the schema assembly from the [Windows]\assembly\GAC_MSIL\Microsoft.Office.Project.Schema\14.0.0.0__71e9bce111e9429c directory with the following command. Run the Command Prompt window as an administrator, and change the [Windows] placeholder to match your computer.
set SCHEMA= [Windows]\assembly\GAC_MSIL\Microsoft.Office.Project.Schema\14.0.0.0__71e9bce111e9429c
xcopy /y %SCHEMA%\*.dll .
The following code shows a simple post-event handler that uses CustomFieldInformation in the event argument for the custom field Created event. You could get the name of the custom field, for example, with the statement string cfName = customFieldDs.CustomFields[0].MD_PROP_NAME, where customFieldDs is of type Microsoft.Office.Project.Server.Schema.CustomFieldDataSet. CustomFields is a CustomFieldsDataTable object that is in e.CustomFieldInformation—which itself is of type CustomFieldDataSet. The custom fields table has only one row (CustomFields[0]), which contains data for the just-created custom field. For a list of properties in a custom field row, see CustomFieldDataSet.CustomFieldsRow.
using System;
using System.Diagnostics;
using Microsoft.Office.Project.Server.Events;
using PSLibrary = Microsoft.Office.Project.Server.Library;
using PSSchema = Microsoft.Office.Project.Server.Schema;
namespace TestCreatedCustomField
{
public class WriteCustomFieldCreatedEvent : CustomFieldsEventReceiver
{
public override void OnCreated(
PSLibrary.PSContextInfo contextInfo,
CustomFieldsPostEventArgs e)
{
// Create an event log instance and assign its source.
EventLog myLog = new EventLog();
myLog.Source = "Custom Field OnCreated Event Handler";
// Get information from the event arguments.
string userName = contextInfo.UserName.ToString();
PSSchema.CustomFieldDataSet customFieldDs = e.CustomFieldInformation;
string cfName = customFieldDs.CustomFields[0].MD_PROP_NAME;
byte cfTypeEnum = customFieldDs.CustomFields[0].MD_PROP_TYPE_ENUM;
Guid cfUid = customFieldDs.CustomFields[0].MD_PROP_UID;
string[] cfTypes = Enum.GetNames(typeof(PSLibrary.CustomField.Type));
string cfType = "";
int index = 0;
// Find the name of the custom field type.
foreach (int i in Enum.GetValues(typeof(PSLibrary.CustomField.Type)))
{
if (i == Convert.ToInt32(cfTypeEnum))
{
cfType = cfTypes[index];
break;
}
index++;
}
// Write an entry to the Application event log.
int eventId = 3652; // Create an arbitrary event ID.
string logEntry;
logEntry = "User: " + userName +
"\nCustom Field Name: " + cfName +
"\nGUID: " + cfUid.ToString() +
"\nType: " + cfType +
"\nThe custom field has been created.";
myLog.WriteEntry(logEntry, EventLogEntryType.Information, eventId);
}
}
}
If you compile and install the event handler, register the event handler in Project Web App, and then create a resource custom field named Test Res Duration of type Duration, you can see the Application event in the Event Viewer for the Project Server computer (Figure 6). The complete Visual Studio solution for the TestCreatedCustomField example, including scripts for copying references and installing the event handler, is in the Samples\EventHandlers\TestCreatedCustomField directory in the Project 2010 SDK download.
Figure 6. Using the Event Viewer to show properties in an event handler
.gif "Using the Event Viewer with an event handler")
Datasets in event handlers are for read-only use. For example, you cannot modify the CustomFieldDataSet to change the name of a custom field within the OnCreating pre-event handler. However, you can trap the event, get the properties that you need, cancel creation of the custom field, programmatically configure the WCF endpoint for the CustomFields service, and then use the CreateCustomFields method in the CustomFields web service to create a custom field with the correct name.
For general information, see Project Server Events in the Project 2007 SDK. For an example that includes instructions for registering event handlers and writing to the ULS log, see How to: Create a Project Server Event Handler and Log an Event. For other examples, see How to: Customize E-Mail for Project Server Notifications, which uses an OnSending event handler for email notifications; and see Project Server 2010 Delegation Audit Event Handler, which uses OnActivated and OnDeactivated event handlers for user delegation.
EPM Reporting in Project 2010
The Project Professional 2010 and Project Standard 2010 desktop clients include the Visual Reports feature that can use Microsoft Visio 2010 and Microsoft Office Excel 2007 or Excel 2010. With Visual Reports, you can create graphical reports and pivot table reports from local Project files. On the server side, the platform for EPM reporting is a major upgrade in Project Server 2010 that supports the Microsoft Business Intelligence (BI) framework. The Business Intelligence Center of SharePoint Server 2010 is customized and built in Project Web App. The purpose of the Business Intelligence Center is to help provide timely and relevant business insight to all employees who have access to Project Web App.
The reporting infrastructure in Project Server includes the Reporting database (RDB), the Report Data Service (RDS), and the Cube Build Service (CBS). For more information, search for Visual Reports or for reporting in the Project Team blog (https://blogs.msdn.com/project/) and other Project blogs, end-user documentation for Project, and TechNet. For example, see Business Intelligence in Project Server 2010, Project 2010: Business Intelligence Overview, and Reporting on projects (Project Server 2010). In the Project 2010 SDK, see Cube Build Service and Custom Fields and the Reporting Database.
To get started with Project Server reporting, see the reporting videos on the Train & Learn page for Project 2010.
Reporting Database and the Report Data Service
The default Reporting database (RDB) tables and views are designed to be read-only for generating reports from project data. The Project Server 2010 Reporting Database Schema reference is in the Project 2010 SDK download. The RDB schema includes three core parts:
EPM data (such as projects, tasks, resources, assignments, and custom fields)
Timesheet data
Collaboration data (issues, risks, and deliverables on project sites)
The Report Data Service (RDS) updates the RDB in near real time (within a few minutes) from changes in the Published database. The RDB tables are de-normalized to make it relatively easy to create reports by using Microsoft SQL Server Reporting Services (SSRS).
The RDS handles updates to the RDB with a queue and can manage multithreaded update operations from multiple servers. Users can likely see changed data in Project Web App before it arrives in a report from the RDB. The RDS includes post-events for data updates, so you can manage the reporting cache and update reports after the necessary data is present.
Views in the RDB include views that are designed for OLAP and views for users who are creating reports directly from the RDB; for example, resource data is available in MSP_EpmResource_OlapView and in MSP_EpmResource_UserView. The OLAP views are designed for use by the Cube Build Service in generating the OLAP cubes. The user views generally include more fields than the OLAP views and are designed for creating reports. Sample queries in the Project Server Report Pack use tables and user views. The Office Project 2007 SDK download includes the Report Pack with seven sample SSRS reports. The MSDN Code Gallery includes an update of the Report Pack; see Project Server 2007 Report Pack II—"The Top Reports".
Note
Some of the Report Pack samples for Office Project Server 2007 rely on specific custom fields and lookup tables that were created for the demonstration virtual machine that was shipped in 2007. Some Report Pack samples use Project Server features that are obsolete or not used in Project Server 2010. You can use Report Pack samples as a starting point for creating new reports in Project Server 2010.
You can add tables and views to the RDB that include external data and use the RDS to manage updates of custom tables and views. For example, the MSDN Code Gallery sample in Project Server 2010 Delegation Audit Event Handler creates a PS2010_UserDelegationAudit table in the RDB.
Cube Build Service
The Cube Build Service (CBS) creates multiple OLAP cubes from Project Server and related SharePoint data. Project Web App helps to manage SQL Server Analysis Services cubes, supports customization of the cubes, and has a centralized location for Reporting Services reports that use the OLAP cubes or the RDB. You can add enterprise custom fields as new dimensions or measures, and add calculated measures to the cubes, all through Project Web App.
In addition to administration in Project Web App, the CBS has extensive event and trace logging for the ULS logs. The PSI CubeAdmin web service enables programmatic management and scheduling of cube building. The OLAP database for Project Server 2010 includes 14 default cubes, which are described in Cube Build Service.
You can build the default OLAP cubes by using incremental data changes to enable greater frequency and shorter duration of updates. Views of cube data are available in Dashboards and Web Parts. You can create additional views and custom Web Parts that combine Project Server and external data. For example, you can use Excel 2010 with PivotTable reports and conditional formatting; and you can publish the Excel workbooks or spreadsheets to Excel Services for thin rendering on any SharePoint site.
The Business Intelligence Center page in Project Web App has rich collaboration capabilities. Team members can easily create key performance indicators (KPIs) that monitor data trends and show Excel workbooks that contain data from Visual Reports by publishing them to SharePoint through Excel Services. Administrators or developers can create scorecard elements, views, and roles, publish updates of Project Server data to PerformancePoint Services in Microsoft SharePoint Server 2010, and show PerformancePoint content in the Business Intelligence Center.
For an example that shows how to extend the Portfolio Analyzer cube, see How to: Calculate Resource Availability in OLAP Cubes. For information about how to add custom fields as dimensions or measures in cubes, see Custom Fields and OLAP Cubes.
Checking Errors in Project Server 2010
When you are developing solutions for Project Server, you can check two main areas for configuration and run-time errors: the application event log and the Unified Logging Service (ULS) trace logs. You should also use try-catch blocks for code that calls PSI methods. For more information about errors and sample code for handling exceptions for WCF and for ASMX-based applications, see Project Server Error Codes.
Application Event Log On the Start menu on the Project Server computer, click Run, and then type eventvwr. In the left pane of the Event Viewer window, expand the Windows Logs node, and then click Application to see the events logged by Project Server, SharePoint, ASP.NET, SQL Server, custom event handlers, and other applications (see Figure 6). If you sort the events by source, you can easily find the Project Server events. Sources include ProjectQueueService14 and ProjectEventService14.
ULS Logs The ULS trace logs and event logs can provide more detail than the application event log. You can configure a ULS trace log to record specific categories or all categories and levels of activities in Project Server and SharePoint. To view the trace logs, you can use Notepad, another text editor, or Microsoft Excel. To easily read and monitor the ULS log, and to filter for events and save ULS log examples, you can download and install the ULS Viewer from MSDN Code Gallery. The ULS Viewer is an unsupported application. For an example that shows how to use the ULS Viewer, see How to: Create a Project Server Event Handler and Log an Event.
To configure the ULS logs and other timer jobs for Project Server
Open the SharePoint 2010 Central Administration application, click Monitoring, and then click Review job definitions in the Timer Jobs section of the Monitoring page.
Click Diagnostic Data Provider: Trace Log, and then on the Edit Timer Job page, set the timer job to run every 10 minutes. You can similarly configure the Diagnostic Data Provider: Event Log. You can set five additional Diagnostic Data Provider timer jobs, for example for performance counters and SQL queries that are related to SharePoint applications.
The Project Server Service Application also has four settings that you can configure on the Job Definitions page, which govern how often the SharePoint timer runs other jobs for Project Web App.
On the Monitoring page in SharePoint 2010 Central Administration, click Configure diagnostic logging in the Reporting section. On the Diagnostic Logging page, expand the Project Server category, and then select a specific category such as Server-Side Events. If you select the top Project Server node, all 39 Project Server categories are logged.
For the most information, select Verbose for the least critical event to report in the event log and in the trace log. Because the event log and the trace log can be large in size, run verbose logging only when you need it.
Warning
If you are logging events on a production server, select only specific categories to keep the size of the log manageable. To turn off all logging, select None for the least critical event in each log. To record relatively few events, select High or Monitorable for the trace log. The Unexpected level generally shows application exceptions. For the event log, select Error or Critical to log fewer events.
The Enable Event Log Flood Protection setting is selected by default. The default path for the trace logs is %CommonProgramFiles%\Microsoft Shared\Web Server Extensions\14\LOGS. If you use the ULS Viewer, you can open trace logs in the default path or set another path.
Set the maximum number of days to store trace log files; the default is 14 days. You can also restrict disk space for the trace log.
The ULS creates a new trace log file every 30 minutes. Trace log files include the date and time in the file name, for example, SERVERNAME-20110208-1326.log.
Conclusion
Project Server 2010 is a platform based on the latest programming and software collaboration frameworks—the .NET Framework and SharePoint Server—which will be the basis of Microsoft Project and other Microsoft software programs for many years to come. The Project Server platform makes it easier to develop extensions and integrate with a wide variety of other applications.
The Project Server Interface (PSI) and related datasets eliminate the need to directly access the three core Project Server databases (Draft, Published, and Archive). Project Server events are the key to extending Project Server and integrating with LOB applications. Event handlers can start workflows, workflows can make PSI calls, and other event handlers can send messages to project detail pages in workflows.
Project Server reporting and OLAP cubes are part of the extensible Project platform and provide customers and partners many opportunities to improve project management, communication, and business decisions in organizations.
Additional Resources
For more information, see the following resources:
Microsoft Project Server 2010 (Microsoft TechNet)
Project Help and How-To (end-user help)
Project Server Help and How-To (end-user help)
Project Functions for Custom Fields (used in VBA macros)
VBA Programming for Microsoft Office Project Versions 98 Through 2007
Microsoft Project 2010: Powershell Cmdlets for Project Server PSI