Overview of WCF and the PSI

  • Article

Applies to: Office 2010 | Project 2010 | Project Server 2010 | SharePoint Server 2010

The Project Server Interface (PSI) in Microsoft Project Server 2010 includes both an ASMX Web service interface and a service interface for Windows Communication Foundation (WCF). For the public PSI services, the object model of the ASMX Web service and the object model for the WCF service are identical. The service-oriented architecture of the WCF interface provides improved performance, security, and scalability. Custom applications that use the PSI can use either interface.

This article includes the following sections:

  • Overview of WCF

    • Services in the PSI

    • Using the ASMX and WCF Interfaces

  • Migration and Compatibility of Custom Solutions

Important

The underlying technology for network communications is based on WCF in Project Server 2010, to enable the use of service references (.svc files) and a broad range of improvements. ASMX Web service references are also based on the WCF architecture, and do not use .asmx files. Setting a reference to a PSI Web service in Project Server 2010 requires appending the ?wsdl URL option to the path, for example, https://ServerName/ProjectServerName/_vti_bin/PSI/Resource.asmx?wsdl.

For general procedures to use in development with the WCF interface, including procedures for setting service references, how to create a service configuration file, and tips for using Intellisense descriptions for the PSI, see Prerequisites for WCF-Based Code Samples. For general procedures to use with the ASMX interface, see Prerequisites for ASMX-Based Code Samples.

Overview of WCF

WCF is a distributed messaging platform that was released with Windows Presentation Foundation (WPF) and Windows Workflow Foundation (WF) in the Microsoft .NET Framework 3.0. WCF uses WSDL and SOAP for all types of services by default; it can be configured or extended to use other message formats and discovery mechanisms such as simple XML using RSS. WCF can operate over a variety of communication protocols, including HTTP, TCP, named pipes, MSMQ, and custom protocols. A WCF service can be exposed and consumed over multiple protocols without recompiling. By default, WCF services in Project Server 2010 use SOAP over HTTP (or HTTPS), and are hosted in Microsoft Internet Information Services (IIS).

WCF unifies several Microsoft distributed computing technologies (ASMX, .NET Framework remoting, Enterprise Services, WSE, and MSMQ) and can also interoperate with other Web service platforms and messaging technologies. Because of its very broad interoperability, there are many features of WCF to learn. WCF can be configured programmatically or by using the app.config or web.config XML files.

Using WCF with the PSI in Project Server 2010 is similar to using ASMX for typical applications, although there are more configuration settings to make for the WCF endpoints. A WCF endpoint includes a URI and a binding that specifies the security, protocol, message encoding, and timeouts.

For more information about WCF, see Windows Communication Foundation and Beginner's Guide to Windows Communication Foundation.

Services in the PSI

The classes, members, and method signatures in the ASMX interface and the WCF interface are identical. Table 1 shows the services in the PSI. Although the ASMX column shows the service with an .asmx extension, the actual URL must include the ?wsdl URL option, for example, Admin.asmx?wsdl.

Table 1. Services in the PSI

ASMX

WCF

Public

Local

Comments

Admin.asmx

Admin.svc

   X

   X

 

Archive.asmx

Archive.svc

   X

   X

 

authentication.asmx

 

   X

Internal use only.

Calendar.asmx

Calendar.svc

   X

   X

 

CubeAdmin.asmx

CubeAdmin.svc

   X

   X

 

CustomFields.asmx

CustomFields.svc

   X

   X

 

Driver.asmx

Driver.svc

   X

   X

New in Project Server 2010.

Events.asmx

Events.svc

   X

   X

 

ExchangeSync.asmx

 

   X

New in Project Server 2010; internal use only.

LoginForms.asmx

   X

 

Project Server uses forms-based authentication only with ASMX. WCF uses claims authentication.

LoginWindows.asmx

 

   X

 

Used only for ASMX-based applications, where Project Server 2010 uses multi-authentication (claims- and Forms-based authentication).

LookupTable.asmx

LookupTable.svc

   X

   X

 

Notifications.asmx

Notifications.svc

   X

   X

 

ObjectLinkProvider.asmx

ObjectLinkProvider.svc

   X

   X

 

 

P12Upgrade.svc

 

   X

Used only in upgrades from Project Server 2007. Not documented.

PortfolioAnalyses.asmx

PortfolioAnalyses.svc

   X

   X

New in Project Server 2010.

Project.asmx

Project.svc

   X

   X

 

PWA.asmx

PWA.svc

 

   X

Internal use only.

QueueSystem.asmx

QueueSystem.svc

   X

   X

 

Resource.asmx

Resource.svc

   X

   X

 

ResourcePlan.asmx

ResourcePlan.svc

   X

   X

 

Security.asmx

Security.svc

   X

   X

 

Statusing.asmx

Statusing.svc

   X

   X

 

TimeSheet.asmx

TimeSheet.svc

   X

   X

 

View.asmx

View.svc

 

   X

Internal use only.

WinProj.asmx

WinProj.svc

 

   X

Internal use only.

Workflow.asmx

Workflow.svc

   X

   X

New in Project Server 2010.

WssInterop.asmx

WssInterop.svc

   X

   X

 

The PSI includes 22 public Web services and five private Web services. The private Web services are marked "Internal use only" in Table 1. As in Project Server 2007, the public interfaces are available to external applications through the Project Web App URL. External applications can use the ASMX interface directly. External applications use the WCF interface through the front-end ProjectServer.svc service in Project Web App, which acts as a router to the back-end Project Server services. For a brief description of each PSI service, see PSI Reference Overview.

Using the ASMX and WCF Interfaces

ASMX Interface:   The ASMX interface can be used only through a front-end (Project Web App) URL. The URL for the public ASMX interface of the Resource Web service, for example, is https://ServerName/ProjectServerName/_vti_bin/PSI/Resource.asmx?wsdl. That URL displays the XML service contract for the Resource Web service (Figure 1).

The ASMX interface files are contained in the [ProgramFiles]\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI\PSI directory on the Project Server computer. Unlike in Project Server 2007, the ASMX interface in Project Server 2010 uses the underlying WCF infrastructure and is not accessed through .asmx files. Instead, the ASMX interface for each PSI service includes two .aspx files: the discovery file (Servicedisco.aspx) sets the SOAP binding for the service request and response, and the WSDL file (Servicewsdl.aspx) provides the schema for the service. For example, ASMX access to the Resource service uses the Resourcedisco.aspx and Resourcewsdl.aspx files.

Figure 1. Adding an ASMX Web service reference with the WSDL option

Adding an ASMX reference with the WSDL option

WCF Interface:   The WCF interface includes the .svc files in the [Program Files]\Microsoft Office Servers\14.0\WebServices\Shared\ProjectServer\PSI directory. The URL for the WCF interface of the Project service of the PSI, for example, is https://ServerName:32843/[GUID]/PSI/Project.svc. The GUID is the name of the Project Server Service virtual directory in the SharePoint Web Services application. The WCF interface can be used for both local and remote applications through a proxy assembly or proxy source files. Applications and components that are designed to run on the server should use the WCF interface.

You can find the virtual directory name of the Project Server Service application by using SharePoint Central Administration. On the Manage Service Applications page, click the Project Server Service Application instance you want. The URL option of the Manage Project Web App Sites page contains the GUID of the directory name. For example, in https://ServerName:38312/_admin/managepwa.aspx?appid=c476f85e-5c61-4de9-91e3-45e5127e20dc, the Project Server Service application directory is c476f85e5c614de991e345e5127e20dc (without the dashes).

Tip

To quickly find the GUID of the Project Server service application, use a Windows PowerShell command that is installed with SharePoint Server 2010. In the Start menu, click All Programs, click Microsoft SharePoint 2010 Products, and then click SharePoint 2010 Management Shell. Following is the command and the results in the SharePoint 2010 Management Shell window for the defined service applications (your GUIDs will be different). Remove the dashes in the GUID for the Project Server service application.

PS > get-SPServiceApplication 
DisplayName          TypeName             Id
-----------          --------             --
Secure Store Service Secure Store Serv... e23c707b-f94d-4079-86a3-4ee99ed88c60
State Service        State Service        9f15ce66-95a5-4a13-86c5-9df7fd1fb3de
Project Server Se... Project Server PS... c476f85e-5c61-4de9-91e3-45e5127e20dc
PerformancePoint ... PerformancePoint ... b85e01e9-d414-4126-92d5-ee36dfc69668
Excel Services Ap... Excel Services Ap... 8c40adc1-36bf-45e5-984b-39d547256c74
Security Token Se... Security Token Se... 3b19014f-1f5d-4e46-8c6f-2ddb42e89544
Application Disco... Application Disco... a585e505-e56e-4e2f-be70-37859c83ff3e
WSS_UsageApplication Usage and Health ... 0d938d1c-6761-4848-afe4-b5567d4d4f7e
Search Administra... Search Administra... 999b518e-69f8-429a-9766-985aa7d75d1b
SharePoint Server... SharePoint Server... f268bbc9-4afd-43f2-ad27-082ef52e9955
Search Service Ap... Search Service Ap... 9d4ef748-90a1-4207-add6-5b232fcaf7b4

If you know the full name of the Project Server service application, you can use it to get the GUID value, for example:

PS > $projectService = "Project Server Service Application"
PS > (Get-SPServiceApplication | where { $_.Name -eq $projectService }).Id

Guid
----
c476f85e-5c61-4de9-91e3-45e5127e20dc

The Project Server Service application virtual directory name in the example is c476f85e5c614de991e345e5127e20dc (without the dashes), so the back-end URL of the Project service is https://ServerName:32843/c476f85e5c614de991e345e5127e20dc/PSI/Project.svc. However, the back-end URL of a Project Server service is not directly usable because of claims-based authentication and custom WCF bindings in the SharePoint Web Services application. For that reason, access to WCF services must be through the front-end ProjectServer.svc router in Project Web App. For more information about the custom bindings, see How to: Create a Proxy Assembly for WCF Services.

Each .svc file includes a reference to the WCF implementation for Project Server. For example, the Project.svc file for the Project service has the following content.

<%@ ServiceHost=""
Language="C#"
Service="Microsoft.Office.Project.Server.Wcf.Implementation.ProjectImpl,
  Microsoft.Office.Project.Server.Communications.Internal, 
  Version=14.0.0.0,Culture=neutral,PublicKeyToken=71e9bce111e9429c"
Factory="Microsoft.Office.Project.Server.Administration.PsiServiceHostFactory,
  Microsoft.Office.Project.Server.Administration,
  Version=14.0.0.0,Culture=neutral,PublicKeyToken=71e9bce111e9429c"
%>

Using the ProjectServer.svc router:   The Project Web App front-end includes one WCF service, ProjectServer.svc, which serves as router for all of the Project Server services that are available in the SharePoint Web Services application. External applications do not call ProjectServer.svc directly, but set it as an endpoint for the proxy PSI services.

Note

In Project Server 2010, the Project Server service for Project Web App ([Program Files]\Common Files\Microsoft Shared\Web Server Extensions\14\isapi\PSI\ProjectServer.svc) acts only as a router for external access to PSI services on the computer running Project Server. Accordingly, ProjectServer.svc is disabled for publishing metadata. If you try to view https://ServerName/ProjectServerName/_vti_bin/psi/ProjectServer.svc in Internet Explorer, you get an error: The webpage cannot be found. This is normal behavior, and you should not try to enable metadata publishing for ProjectServer.svc.

Figure 2 shows the location of all the WCF interfaces of the PSI services, in the Internet Information Services (IIS) Manager dialog box in Windows Server 2008. In this example, the Project Web App URL is https://server/pwa in the Sharepoint-80 site and, just as in Project Server 2007, it has a _vti_bin/PSI subdirectory.

Figure 2. Location of the PSI services in IIS Manager

Location of the PSI Web services in IIS Manager

In SharePoint Server 2010, the service applications are installed in the SharePoint Web Services application. You can use IIS Manager to find the transport bindings of the site. The default bindings are port 32843 for HTTP and port 32844 for HTTPS. The virtual directory name of the Project Server services is a GUID. The general URI for the WCF interface of the Resource service is therefore https://ServerName:32843/[GUID]/PSI/Resource.svc. In Microsoft Internet Explorer, you cannot directly access the WCF service contract unless you temporarily change the web.config file in the PSI directory.

Note

When you try to set a reference to a WCF service in Visual Studio, for example https://ServerName:32843/1712e91aeb884cdfb437299b89de3443/psi/Resource.svc, you get a System.InvalidOperationException error.

To set a service reference directly in Visual Studio, you must temporarily change the web.config file for the back-end Project Server services, in C:\Program Files\Microsoft Office Servers\14.0\WebServices\Shared\ProjectServer\PSI. For instructions, see How to: Create a Proxy Assembly for WCF Services.

The following shows the error when you try to set a service reference, if you don’t change the web.config file for the back-end Project Server services.

The service encountered an error. 
An ExceptionDetail, likely created by IncludeExceptionDetailInFaults=true, whose value is: 
System.InvalidOperationException: An exception was thrown in a call to a policy export extension. 
Extension: System.ServiceModel.Channels.TransportSecurityBindingElement
Error: Security policy export failed.

To use the front-end ProjectServer.svc for routing calls to the WCF interface of the PSI in your applications, you must do the following:

  1. Add references for the PSI services that you need. As described in Prerequisites for WCF-Based Code Samples, there are three ways to add a service reference. We

    • Set a reference to the ProjectServerServices.dll PSI proxy assembly.

    • Add the SvcUtil.exe output file of the WCF reference to the Visual Studio solution.

    • Add a service reference using Visual Studio.

    Instead of directly setting a service reference, we recommend that you set a reference to the ProjectServerServices.dll proxy assembly or add a proxy source file to your Visual Studio solution. The proxy assembly and source files are in the Project 2010 SDK download.

  2. Create endpoints for the services that point to ProjectServer.svc on the Project Web App front end. For more information about creating WCF endpoints for Project Server services, see Walkthrough: Developing PSI Applications Using WCF, which shows how to programmatically create WCF bindings and endpoints without using an app.config file, and also how to modify an app.config file by using the WCF Service Configuration Editor in Visual Studio.

Migration and Compatibility of Custom Solutions

The public Web methods of the PSI that occur in both Project Server 2007 and Project Server 2010 have the same signatures. Classes and members in the public ASMX and WCF interfaces of Project Server 2010 are identical. However, the number of columns and size of datatables used or returned by PSI methods can be different between Project Server 2007 and Project Server 2010. There are also differences in the Reporting database.

If solutions for Project Server 2007 use the ASMX interface through the front-end Project Web App URL, they can continue to use the ASMX interface. If the Project Server 2007 solutions use ASMX through the Shared Service Provider (SSP), they must be changed to use the WCF interface. We recommend that you use the WCF interface where possible; it has advantages in service-oriented architecture, security, performance, and scalability.

The Compatibility Mode setting in Project Web App refers only to making Project Server 2010 compatible with Project Professional 2007. The setting has no effect on third-party solutions.

Note

Although most solutions developed for Project Server 2007 should also work with Project Server 2010, we recommend that you test solutions on a non-production installation of Project Server 2010 before deploying them to a production server.

If you choose to migrate a Project Server 2007 solution to use the WCF interface, or if the solution does not work as expected on Project Server 2010, you should at a minimum do the following:

  • Make a list of the Web references and namespace names, and then delete the ASMX Web references.

  • Add the ProjectServerServices.dll WCF proxy assembly or source files for the required services, or add the front-end ASMX references again, by using the same namespace names. There are several new methods and datasets in the PSI services in Project Server 2010.

  • Change assembly references to use the Project Server 2010 assemblies, such as Microsoft.Office.Project.Server.Library.dll and Microsoft.Office.Project.Server.Events.Receivers.dll.

  • Compile and test the solution.

You must use Visual Studio 2008 SP1 or later to update solutions to use the WCF interface. The released version of Project Server 2010 requires Microsoft Visual Studio 2010 to create and deploy Project Server workflows.

When you update an application or component, Visual Studio enables you to set the Target Framework on the application Properties page to a specific version of the .NET Framework. If the target framework is .NET Framework 2.0, you can update and add new Web references only by using ASMX. If you set the target framework to .NET Framework 3.5, you can access the Add Service Reference dialog box for WCF services.

Important

Solutions or customizations that you develop with pre-release versions of Project Server 2010 should be recompiled and might require additional changes for the released version.

See Also

Tasks

Walkthrough: Developing PSI Applications Using WCF

How to: Create a Proxy Assembly for WCF Services

How to: Use Impersonation with WCF

Concepts

PSI Reference Overview

Prerequisites for ASMX-Based Code Samples

Prerequisites for WCF-Based Code Samples

Other Resources

Windows Communication Foundation

Beginner's Guide to Windows Communication Foundation