Prerequisites for WCF-Based Code Samples
Applies to: Office 2010 | Project 2010 | Project Server 2010 | SharePoint Server 2010
In this article
Setting Up the Development Environment
Creating the Application and Adding a Service Reference
Setting Other References
Adding a Service Configuration File
Using Claims Multi-Authentication
Changing Values of Generic Constants
Verifying the Results
Cleaning Up
The code samples in the Class Library and Web Service Reference developed for Microsoft Project Server 2010 conform to a standard format that uses Windows Communication Foundation (WCF) services. The samples are designed to be copied into a console application and run as a complete unit. Exceptions are noted in the sample.
Code samples in the Project 2010 SDK that are unchanged from the samples developed for Office Project Server 2007 use ASMX Web services. The ASMX-based samples can also be adapted to use WCF services. This article shows how to use the samples with WCF services. For information about how to use the samples with ASMX Web services, see Prerequisites for ASMX-Based Code Samples.
Note
New applications should use the WCF interface, which is the Microsoft recommended technology for network communications. Existing applications that use the ASMX interface must use the URL through Project Web App, which checks Project Server permissions.
The WCF service URL through the SharePoint Web Services application can be used for middleware components that run only on the Project Server computer and for applications that use impersonation. For more information about the WCF interface and the ASMX interface, see Overview of WCF and the PSI.
Before running the code samples, you must set up the development environment, configure the application, add a service configuration file (or configure the WCF services programmatically), and change generic constant values to match your environment. This article includes the following sections:
Setting Up the Development Environment
Creating the Application and Adding a Service Reference
Using the PSI Proxy Assembly with Intellisense Descriptions
Adding a PSI Proxy File
Adding a Service Reference
Setting Other References
Adding a Service Configuration File
Using Claims Multi-Authentication
Changing Values of Generic Constants
Verifying the Results
Cleaning Up
Setting Up the Development Environment
Set up a test Project Server system.
Use a test Project Server system whenever you are developing or testing. Even when your code works perfectly, interproject dependencies, reporting, or other environmental factors can cause unintended consequences.
Note
Ensure that you are a valid user on the server, and check that you have sufficient permissions for the Project Server Interface (PSI) calls that your application uses.
In some cases you may need to do remote debugging on the server. You may also need to set up an event handler by installing an event handler assembly on the Project Server computer, and then configure the event handler by using the Server Settings page in Project Web App.
Set up a development computer.
You usually access the PSI through a network. The code samples are designed to be run on a client separate from the server, except where noted.
Install the correct version of Microsoft Visual Studio. Except where noted, the code samples are written in Microsoft Visual C#. They can be used with Microsoft Visual Studio 2008 SP1 or Microsoft Visual Studio 2010.
Note
You can use Visual Studio 2008 for most applications developed for Project Server 2010. Project Server workflow applications require development on the Project Server computer, by using Visual Studio 2010. We recommend Visual Studio 2010 for all Project Server development.
Copy Project Server DLLs to the development computer. For non-workflow applications, copy the following assemblies from [Program Files]\Microsoft Office Servers\14.0\Bin on the Project Server computer to the development computer:
Microsoft.Office.Project.Server.Events.Receivers.dll
Microsoft.Office.Project.Server.Library.dll
Note
Workflow applications require development on a Project Server computer. For more information, see Developing Project Server Workflows.
For information about how to compile and use the ProjectServerServices.dll proxy assembly for the WCF services in the PSI, see Using the PSI Proxy Assembly with Intellisense Descriptions.
Set up Intellisense descriptions.
To use Intellisense descriptions for classes and members in Project Server assemblies, copy the Intellisense XML files from the Project 2010 SDK download to the same directory where the Project Server assemblies are located. For example, copy the Microsoft.Office.Project.Server.Library.xml file to the directory where your application will set a reference to the Microsoft.Office.Project.Server.Library.dll assembly.
Intellisense descriptions for the PSI services require that you use the ProjectServerServices.xml file with the ProjectServerServices.dll proxy assembly.
Creating the Application and Adding a Service Reference
Create a console application.
When you create a console application, in the drop-down list of the New Project dialog box, select .NET Framework 3.5. You can copy the PSI example code into the new application.
Add references required for WCF.
On the .NET tab of the Add Reference dialog box, add a reference to System.ServiceModel. A Web application would use System.ServiceModel.Web.
Add a reference to System.Runtime.Serialization.
Copy the code.
Copy the complete code example into the Program.cs file of the console application.
Set the namespace for the sample application.
You can either change the namespace listed at the top of the sample to the application default namespace, or change the default application namespace to match the sample. You can find the default application namespace in the application properties.
For example, the code sample for CreateNewAssignment has the namespace Microsoft.SDK.Project.Samples.CreateNewAssignment. Copy the namespace from the Program.cs file and then open the project Properties pane (on the Project menu, click CreateNewAssignment Properties). On the Application tab, copy the namespace into the Default namespace text box.
Set the service references.
Many examples require a reference to one or more of the PSI services. These are listed in the sample itself or in comments that precede the sample. To get the correct namespace of the service references, ensure that you first set the default application namespace.
There are three ways to add a WCF service reference:
Compile the ProjectServerServices.dll PSI proxy assembly, and then set a reference to the assembly. See Using the PSI Proxy Assembly with Intellisense Descriptions.
Add a PSI proxy source code file to the Visual Studio solution. See Adding a PSI Proxy File.
Add a service reference by using Visual Studio. See Adding a Service Reference.
Warning
Adding a service reference in Visual Studio requires that you temporarily change the web.config file in the back-end Project Server Service application directory on the computer running Project Server. We recommend using either of the first two methods.
Using the PSI Proxy Assembly with Intellisense Descriptions
You can use a proxy assembly for all public WCF services in the PSI. Compile the ProjectServerServices.dll proxy assembly by using the Documentation\Intellisense\WCF\CompileWCFProxyAssembly.cmd script in the Project 2010 SDK download, and then copy the proxy assembly to your development computer. Copy the ProjectServerServices.xml file for Intellisense to the same location. In Visual Studio, set a reference to the ProjectServerServices.dll proxy assembly.
For Project Server service packs and updates, you can update the proxy source files and create a new proxy assembly by using the GenWCFProxyAssembly.cmd script in the same SDK download folder. For more information, see How to: Create a Proxy Assembly for WCF Services. For a link to the SDK download, see Project 2010 SDK Documentation.
Note
There are no object model changes in the PSI for the Service Pack 1 (SP1) version of Project Server 2010, so the proxy files in the Project 2010 SDK download are the same as in previous releases of the SDK. After installing SP1, you do not need to generate new PSI proxy source files with the GenWCFProxyAssembly.cmd script.
For future Project Server service packs and updates, you can create updated proxy source files and a new PSI proxy assembly for WCF. For more information, see How to: Create a Proxy Assembly for WCF Services.
The arbitrary namespaces created for both the ASMX Web services and the WCF services are the same, so that the ProjectServerServices.xml file for Intellisense works with either version. For example, the namespace of the Resource service in the WCF-based proxy assembly and in the ASMX-based proxy assembly is SvcResource. You can, of course, change the namespace names—if you build your own proxy assembly and ensure that the namespaces match in the proxy assembly and in the ProjectServerServices.xml file. If a code sample in the SDK uses a different name for a PSI Web service namespace, for example ProjectSvc, you must change the sample to use SvcProject to match the names in the proxy assembly.
Advantages to using the WCF-based proxy assembly include the following:
You can develop most solutions (except workflow solutions) with the proxy assembly on a different computer than the Project Server computer. Setting an individual service reference requires access to the local Project Services application on the Project Server computer.
The proxy assembly includes all PSI service namespaces, so you do not need to use multiple service references.
If you add the ProjectServerServices.xml file to the same directory where you set a reference to the ProjectServerServices.dll proxy assembly, you can get Intellisense descriptions for the PSI classes and members. For more information, see the ReadMe file in the Documentation\Intellisense folder of the SDK download.
Disadvantages to using the proxy assembly are that the solution is larger and you must distribute and install the proxy assembly with the solution. You must also use the same namespaces that are in the proxy assembly and Intellisense files, unless you change the script to build a proxy assembly and change the ProjectServerServices.xml Intellisense file to use different namespaces.
Adding a PSI Proxy File
The Project 2010 SDK download also includes the source files generated by the SvcUtil.exe command for the proxy assembly. The source files are in Source.zip in the Documentation\Intellisense\WCF subdirectory. Instead of setting a reference to the proxy assembly, you can add one or more of the source files to a Visual Studio solution. For example, to use the Project service and the Resource service, add the wcf.Project.cs and wcf.Resource.cs files to the solution.
In WCF, the primary class in each PSI service is defined by an interface and implemented in a client class for access to the members. For example, the primary PSI interface SvcProject.Project is implemented in the SvcProject.ProjectClient class. To define a ProjectClient object as a class variable named projectClient, for example, use the following code. In the example, the SetClientEndpoints method creates a projectClient object that uses the basicHttp_Project endpoint, which is defined in the app.config file. For more information about an app.config file, see the Adding a Service Configuration File section.
private static SvcProject.ProjectClient projectClient;
. . .
private static void SetClientEndpoints()
{
projectClient = new SvcProject.ProjectClient("basicHttp_Project");
. . .
}
public void DisposeClients()
{
projectClient.Close();
. . .
}
Note
Whether you use a PSI proxy assembly or add a proxy file to add a Project service reference named SvcProject, the same code would be used to create and dispose a projectClient object.
Adding a Service Reference
If you do not use the WCF-based proxy assembly or add a proxy file for a PSI service, you can set one or more individual service references directly in Visual Studio.
Warning
To set a service reference, you must temporarily exchange the web.config file in the Project Service application directory. We recommend that you use the ProjectServerServices.dll proxy assembly or add proxy source files, instead of directly adding service references in Visual Studio.
The following steps show how to set a service reference by using Visual Studio 2010 on a computer running a test installation of Project Server:
Exchange the web.config file, as described in How to: Create a Proxy Assembly for WCF Services, and then run iisreset.
In Solution Explorer, right-click the References folder, and then click Add Service Reference.
In the Add Service Reference dialog box, in the Address text box, type https://localhost:32843/[GUID]/psi/ServiceName.svc, and then press Enter. Replace [GUID] with the virtual directory name of the Project Server service application, such as c476f85e5c614de991e345e5127e20dc. Replace ServiceName with the name of the service, such as Project.
You can get the name of the Project Server Service virtual directory in one of the following ways:
Open the SharePoint 2010 Central Administration application in Internet Explorer. Click Manage service applications, and then click the Project Server Service application that you want. For example, click ProjectServerService. The URL of the Manage Project Web App Sites page contains the virtual directory name. For example, in https://localhost:36701/_admin/managepwa.aspx?appid=c476f85e-5c61-4de9-91e3-45e5127e20dc , the virtual directory name is c476f85e5c614de991e345e5127e20dc (the directory name contains no dashes).
Open the Internet Information Services (IIS) Manager dialog box on the Project Server computer. Expand the SharePoint Web Services node in the Connections pane, and then expand the service virtual directories below that, until you find the directory that includes a PSI folder. Select the directory, click Advanced Settings in the Actions pane, and then copy the directory name in the Virtual Path field.
Note
There can be more than one Project Server Service virtual directory. Ensure that you choose the virtual directory that contains the Project Web App instance that you want.
Use the get-SPServiceApplication cmdlet in Windows PowerShell that is installed with SharePoint Server 2010. On the taskbar, click Start, 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). Copy 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-5b232fcaf7b4If 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-45e5127e20dcNote
Remove the dashes in the GUID to get the virtual directory name.
URLs such as https://localhost:32843/c476f85e5c614de991e345e5127e20dc/PSI/Project.svc are standard for Project Server services.
After the service reference resolves, type the reference name in the Namespace text box. Code examples in the Project 2010 SDK use the arbitrary namespace name SvcServiceName. For example, the Project service in the code examples is named SvcProject.
Replace the original web.config file in the Project Service directory, and then rerun iisreset.
Setting Other References
Project Server applications often use other services, such as Microsoft SharePoint Foundation 2010 Web Services. If other services or references are required, they are noted in the code example.
Local references for the code sample are listed in using statements at the top of the sample.
In Solution Explorer, right-click the References folder, and then click Add Reference.
Click Browse, and then browse to the location where you stored the Project Server DLLs that you copied previously. Choose the DLLs that you want, and then click OK.
Note
Ensure that the assembly versions on your development computer exactly match those on the target Project Server computer.
Adding a Service Configuration File
If an application programmatically configures the WCF services, it does not use a service configuration file. Otherwise, a Windows application or console application uses the system.serviceModel element in an app.config file; a Web application includes system.serviceModel in web.config. For more information about using an app.config file or programmatically configuring the WCF services, see Walkthrough: Developing PSI Applications Using WCF.
When it generates a service proxy source file, the SvcUtil.exe command also creates an output.config file that is the basis for the default system.serviceModel element in an app.config file or web.config file. The Project 2010 SDK download includes a sample output.config file in Documentation\Intellisense\WCF\Source.zip. For example, the default output.config file that SvcUtil.exe creates for the WssInterop service includes two custom bindings, named CustomBinding_WssInterop and CustomBinding_WssInterop1. The client element includes two default endpoints: one endpoint is for the HTTPS address on port 32844 and the other is for the TCP address on port 32845, as follows:
<client>
<endpoint address="https://ServerName.domain:32844/[GUID]/PSI/WssInterop.svc"
binding="customBinding" bindingConfiguration="CustomBinding_WssInterop"
contract="SvcWssInterop.WssInterop" name="CustomBinding_WssInterop" />
<endpoint address="net.tcp://ServerName.domain:32845/[GUID]/PSI/WssInterop.svc"
binding="customBinding" bindingConfiguration="CustomBinding_WssInterop1"
contract="SvcWssInterop.WssInterop" name="CustomBinding_WssInterop1">
<identity>
<dns value="ServerName" />
</identity>
</endpoint>
</client>
PSI service configuration does not use the default bindings and endpoints. Project Server requires that applications access PSI services through the front-end ProjectServer.svc, which acts as a router for calls to the back-end services. To create the app.config file, do the following steps:
If you set a reference to the ProjectServerServices.dll proxy assembly, or add the proxy source file for a service, the application does not contain an app.config file. Add a new item to the Visual Studio project. In the Add New Item dialog box, select the Application Configuration File template, name it app.config, and then click Add.
Delete all text in the app.config file, and then copy the following code into the file. You can use the same binding, for example basicHttpConf, for each service endpoint. If you want to use more than one binding, for example, to bind both HTTP and HTTPS protocols, you must create a binding for each protocol.
<?xml version="1.0" encoding="utf-8" ?> <configuration> <system.serviceModel> <behaviors> <endpointBehaviors> <behavior name="basicHttpBehavior"> <clientCredentials> <windows allowedImpersonationLevel="Impersonation" /> </clientCredentials> </behavior> </endpointBehaviors> </behaviors> <bindings> <basicHttpBinding> <binding name="basicHttpConf" sendTimeout="01:00:00" maxBufferSize="500000000" maxReceivedMessageSize="500000000"> <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="500000000" /> <security mode="TransportCredentialOnly"> <transport clientCredentialType="Ntlm" realm="http://SecurityDomain" /> </security> </binding> </basicHttpBinding> </bindings> <client> <endpoint address="https://ServerName/ProjectServerName/_vti_bin/PSI/ProjectServer.svc" behaviorConfiguration="basicHttpBehavior" binding="basicHttpBinding" bindingConfiguration="basicHttpConf" contract="SvcServiceName.ServiceName" name="basicHttp_ServiceName" /> </client> </system.serviceModel> </configuration>Replace ServerName/ProjectServerName in the client endpoint address with the name of your server and Project Web App instance.
Replace ServiceName with the name of the PSI service, such as WssInterop. Ensure that you replace all three instances of the service name, for example:
<endpoint address="http://myserver/pwa/_vti_bin/PSI/ProjectServer.svc" behaviorConfiguration="basicHttpBehavior" binding="basicHttpBinding" bindingConfiguration="basicHttpConf" contract="SvcWssInterop.WssInterop" name="basicHttp_WssInterop" />To use more than one PSI service, create one endpoint element for each service, and for each binding element that service uses. For example, the following endpoints configure the client to use the basic HTTP binding for the WssInterop service and the QueueSystem service:
Note
If you run an application and get an error that the server is too busy, or that the HTTP request is unauthorized, ensure that the endpoint addresses are correct in the app.config file.
<client> <endpoint address="https://ServerName/pwa/_vti_bin/PSI/ProjectServer.svc" behaviorConfiguration="basicHttpBehavior" binding="basicHttpBinding" bindingConfiguration="basicHttpConf" contract="SvcWssInterop.WssInterop" name="basicHttp_WssInterop" /> <endpoint address="https://ServerName/pwa/_vti_bin/PSI/ProjectServer.svc" behaviorConfiguration="basicHttpBehavior" binding="basicHttpBinding" bindingConfiguration="basicHttpConf" contract="SvcQueueSystem.QueueSystem" name="basicHttp_QueueSystem" /> </client>
Tip
You can edit an app.config file by using the WCF Service Configuration Editor in Visual Studio (on the Tools menu). When you set the contract element in the Microsoft Service Configuration Editor dialog box, if the solution is using the PSI proxy assembly, open ProjectServerServices.dll in the bin\debug directory. The Contract Type Browser dialog box shows all of the WCF service contracts (Figure 1).
If the solution is using a service proxy file, such as wcfWssInterop.cs, compile the application and then open the executable file in the bin\debug directory. For more information about editing the app.config file, see Walkthrough: Developing PSI Applications Using WCF.
Figure 1. Using the Contract Type Browser in the Microsoft Service Configuration Editor
.gif "Using the Contract Type Browser")
Using Claims Multi-Authentication
Authentication of Project Server users, whether by Windows authentication or Forms authentication, is done through claims processing in SharePoint. Multi-authentication means that the Web application on which Project Web App is provisioned supports both Windows authentication and Forms-based authentication. If that is the case, any call to a WCF or ASMX service that uses Windows authentication will fail with the following error, because the claims process cannot determine which type of user to authenticate:
The server was unable to process the request due to an internal error.
For more information about the error, either turn on Include ExceptionDetailInFaults
(either from ServiceBehaviorAttribute or from the <serviceDebug> configuration behavior)
on the server in order to send the exception information back to the client,
or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation
and inspect the server trace logs.
To fix the problem for WCF, all calls to PSI methods should be within an OperationContextScope that is defined for each PSI service. Do not nest scopes for multiple services; for example, when using calls to the Resource and Project service, each set of calls should be within its own scope.
In the following example, the DisableFormsAuth method can be called from every OperationContextScope section in an application. The method removes any header value that previously disabled Forms authentication, so that Forms authentication can proceed if the isWindowsAuth parameter is false. If isWindowsAuth is true, the DisableFormsAuth method disables Forms authentication.
In the WcfSample method, the projectClient object is an instance of the PSI SvcProject.ProjectClient class.
// Class variable that determines whether to disable Forms authentication.
private bool isWindowsUser = true;
public void DisableFormsAuth(bool isWindowsAuth)
{
WebOperationContext.Current.OutgoingRequest.Headers.Remove(
"X-FORMS_BASED_AUTH_ACCEPTED");
if (isWindowsAuth)
{
// Disable Forms authentication, to enable Windows authentication.
WebOperationContext.Current.OutgoingRequest.Headers.Add(
"X-FORMS_BASED_AUTH_ACCEPTED", "f");
}
}
private void WcfSample()
{
// Limit the scope of WCF calls to the client channel.
using (OperationContextScope scope = new OperationContextScope(projectClient.InnerChannel))
{
// Add a Web request header to enable Windows authentication in
// multi-authentication installations.
DisableFormsAuth(isWindowsUser);
// Add calls to the projectClient methods here:
// . . .
}
}
Note
Making PSI calls within an OperationContextScope is required only for applications that run in a multi-authentication environment. If Project Server uses only Windows authentication, it is not necessary to set a scope and add a Web request header that disables Forms authentication.
The fix for an ASMX-based application is different. For more information, see the Using Claims Multi-Authentication section in Prerequisites for ASMX-Based Code Samples.
For a complete code sample that uses multi-authentication, see the Samples\MultiAuthentication\WCFLogon_MultiAuth subdirectory in the Project 2010 SDK download.
Changing Values of Generic Constants
Most samples have one or more variables that you must update for the sample to work properly in your environment. In the following example, if you have SSL installed, use the HTTPS protocol instead of the HTTP protocol. Replace ServerName with the name of the server that you are using. Replace ProjectServerName with the virtual directory name of your project server site, such as PWA.
const string PROJECT_SERVER_URI = "https://ServerName/ProjectServerName/";
Any other variables that you must change are noted at the top of the code example.
Verifying the Results
Getting and interpreting results from a code sample is not always straightforward. For example, if you create a project, you must publish the project before it can appear on the Project Center page in Project Web App.
You can verify code sample results in several ways, for example:
Use the Microsoft Project Professional 2010 client to open the project from the Project Server computer, and view the items that you want.
View the Queue log in Project Web App. Click Personal Settings in the Quick Launch, and then click My Queued Jobs (https://ServerName/ProjectServerName/MyJobs.aspx). You can sort by the job status in the View drop-down list. The default status is In Progress and Failed Jobs in the Past Week.
View published projects on the Project Center page of Project Web App (https://ServerName/ProjectServerName/projects.aspx).
Use the Server Settings page in Project Web App to view all queues and enterprise objects (https://ServerName/ProjectServerName/_layouts/pwa/admin/admin.aspx). You must have administrative permissions to access the Server Settings page.
Use Microsoft SQL Server Management Studio to run a query on a table of a Project Server database. For example, use the following query to select the top 200 rows of the MSP_WORKFLOW_STAGE_PDPS table to show information about the project detail pages (PDPs) in workflow stages.
SELECT TOP 200 [STAGE_UID] ,[PDP_UID] ,[PDP_NAME] ,[PDP_POSITION] ,[PDP_ID] ,[PDP_STAGE_DESCRIPTION] ,[PDP_REQUIRES_ATTENTION] FROM [ProjectServer_Published].[dbo].[MSP_WORKFLOW_STAGE_PDPS]
Cleaning Up
After you test some code samples, there are enterprise objects and settings that should be deleted or reset. You can use the Server Settings page in Project Web App to manage enterprise data (https://ServerName/ProjectServerName/_layouts/pwa/admin/admin.aspx). Links on the Server Settings page enable you to delete old items, force check-in projects, manage the job queue for all users, and perform other administrative tasks.
Following are some of the links on the Server Settings page to use for typical cleanup activities after running code samples:
Force Check-in Enterprise Objects
Server Side Event Handlers
Manage Queue Jobs
Enterprise Custom Fields and Lookup Tables
Delete Enterprise Objects
Enterprise Project Types
Workflow Phases
Workflow Stages
Project Detail Pages
See Also
Tasks
Walkthrough: Developing PSI Applications Using WCF
How to: Use Impersonation with WCF
How to: Create a Proxy Assembly for WCF Services
Concepts
Prerequisites for ASMX-Based Code Samples