Using the ProjTool Test Application in Project Server 2010

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

In this article
Compiling ProjTool
Basic Operation of ProjTool
Creating Multilanguage Lookup Tables
Using Forms Authentication and Impersonation in ProjTool

The ProjTool test application is updated to use Windows Communication Foundation (WCF) services in the Project Server Interface (PSI) and to work with Windows authentication, Forms authentication, and impersonation in Microsoft Project Server 2010. ProjTool includes examples that use the Project, Resource, LookupTable, Calendar, CustomFields, QueueSystem, Archive, and Admin services. ProjTool is useful for viewing, creating, and modifying data in a test installation of Project Server 2010, and helps to show how several PSI methods work. (The routines for Forms authentication, multi-authentication, and impersonation are adapted from test code by Tiger Wang, Microsoft Corporation.)

Solution download:   The Microsoft Visual Studio 2010 solution of ProjTool in the Project 2010 SDK download requires compiling. For a compiled version of ProjTool.exe, see the Project Programmability blog post for ProjTool. The source code language is Microsoft Visual C#.

This article describes how to compile the ProjTool application and use some of its features. This article does not explain most of the ProjTool code or how to use the PSI and datasets. For more information about using the PSI with WCF, see Overview of WCF and the PSI and Prerequisites for WCF-Based Code Samples. For information about the original ProjTool application for Microsoft Office Project Server 2007, see Using the ProjTool Test Application with Project Server 2007.

ProjTool does not use all of the PSI services or all of the methods in any one service, but it does provide a base for a fairly comprehensive test application. Following are the main purposes of ProjTool:

• Provide developers with a way to quickly populate the Project Server databases with data in a test installation.

• Enable the easy retrieval and viewing of many datasets that are used in the PSI, to help with development of other applications that use Project Server.

• Show how to set the headers for calls to PSI methods when the Project Server installation includes Forms authentication or both Forms and Windows authentication on the same address port (multi-authentication).

• Show related changes in fields when you update project data.

• Show how to use some of the PSI and DataSet methods that are central to Project Server development.

This article includes the following sections:

• Compiling ProjTool

• Basic Operation of ProjTool

  • ProjTool Settings

  • Using the ProjTool Main Window

  • Creating Projects

  • Modifying Project Data

• Creating Multilanguage Lookup Tables

• Using Forms Authentication and Impersonation in ProjTool

  • Setting Headers for Forms Authentication and Impersonation

Compiling ProjTool

You can modify and compile ProjTool on the Project Server test computer or on a remote development computer. On a remote computer, you must copy the Microsoft.Office.Project.Server.Library.dll assembly from a Project Server computer, and then set a reference to the copy. The ProjTool code sample can be directly compiled for the May 2010 release of Project Server 2010. If you are using a more recent service pack or update of Project Server 2010, use Procedure 1 to update the Visual Studio solution.

Procedure 1. To compile ProjTool for an update of Project Server

1. Start Visual Studio 2010, and then open the ProjTool.sln solution file. Open the Solution Explorer pane, and then expand the ProjTool project, the WCFHelpers project, and the References node and the Web References node.

2. If you are developing on a remote computer, perform the following steps to ensure that ProjTool uses the same library assembly that Project Server uses:

   1. Delete the Microsoft.Office.Project.Server.Library reference in both Visual Studio projects.

   2. Create a directory on your development computer, which contains assemblies that you need to compile samples in the Project SDK. For example, create the directory C:\Project\Assemblies.

   3. Copy the Microsoft.Office.Project.Server.Library.dll assembly from your test Project Server computer to your development computer. The assembly is located in the [Program Files]\Microsoft Office Servers\14.0\Bin directory on the Project Server computer.

   4. Re-add the assembly as a reference in the ProjTool project and in the WCFHelpers project.

3. Create an updated ProjectServerServices.dll proxy assembly for the PSI, as described in How to: Create a Proxy Assembly for WCF Services, copy the assembly to your development computer, and then set a reference in the ProjTool project to the updated assembly.

4. Create an updated wcf.PWA.cs proxy file for the PWA service. The procedure to create a proxy file for a PSI service is described in How to: Create a Proxy Assembly for WCF Services.

   Note

   The PWA service is used internally and is not supported. ProjTool calculates changes to entities in a ChangeList object, which uses the ProjectUpdatesDataSet in the PWA service.

5. In the WCFHelpers project in Solution Explorer, expand the Web References node, and then right-click to update the WebSvcSiteData web reference and the WsfSvcAuthentication web reference.

   Note

   Both of the web references are set to a local SharePoint site for Project Web App, for example https://localhost/pwa/_vti_bin/SiteData.asmx. If you are not developing on a Project Server test computer, change the Web Reference URL property value to be a remote Project Web App site. The SiteData web service and the Authentication web service are SharePoint services in Project Web App; they are not PSI services.

6. Click the WCFHelpers project, and then compile the project (press Shift + F6) to create an updated WCFHelpers.dll assembly for ProjTool.

7. Compile the ProjTool project.

Basic Operation of ProjTool

When you run ProjTool.exe, you can log on with Windows authentication or Forms authentication. Before you log on with Forms authentication or use impersonation, you must use the ProjTool – Project Server Logon dialog box (Figure 1) and save the correct settings in the ProjTool Settings dialog box (Figure 2). For information about impersonation, see Using Forms Authentication and Impersonation in ProjTool.

You can use programmatic settings for the WCF endpoints (the default), or you can use the app.config file. If you use the app.config file, you must set the correct address for the ProjectServer.svc service in each endpoint. The address in the downloaded app.config file is https://ServerName/pwa/_vti_bin/PSI/ProjectServer.svc. You can also log on by using a Secure Sockets Layer (SSL) URL, for example https://ServerName/ProjectServerName, if Project Server is set up for that.

When you first run ProjTool, the default Project Server name is https://LocalHost/PWA/ and the default authentication type is Windows (Figure 1).

Figure 1. Logging on with Windows authentication or Forms authentication

Click Windows for the authentication type, type the URL of your test instance of Project Web App, and then click Log On. ProjTool opens and shows a list of all of the projects in a grid with data from the ProjectDataSet.Project table.

ProjTool Settings

The ProjTool - Project Server Logon dialog box has a Save Settings link to edit the settings before you log on. The ProjTool Settings dialog box (Figure 2) is also available on the Options menu in the main ProjTool window after you log on.

Figure 2. Using the ProjTool Settings dialog box

Procedure 2. To save ProjTool settings

1. After you log on ProjTool, on the Options menu, click Settings.

2. In the ProjTool Settings dialog box (Figure 2), type the Project Server URL, for example, https://ServerName/PWA/, where PWA is the name of the Project Web App instance.

3. If Project Web App is configured for Forms authentication, type the name and password of the Forms user that you will use most often. For example, type FormsAdmin.

4. Add the port settings. The default port for Windows authentication in Project Web App is 80. The default port for Forms authentication is 81. For example, if you install Project Web App with Forms authentication, a typical sign-in page is https://ServerName:81/PWA/.

   Note

   If you set up a Project Web App instance for multi-authentication, the Windows port and the Forms port can be the same value, for example, https://ServerName:200/PWA/.

5. To log on with the default settings, and skip the Project Server Logon window, select the Auto logon on startup check box.

6. To use the app.config file for WCF endpoint configuration, instead of programmatic configuration, select the Configure WCF endpoints with app.config check box. If you use the app.config file, you must edit the file to set the correct address of the ProjectServer.svc service in Project Web App.

7. The default Project Server Queue setting is Wait until the Queue job is completed. That is, ProjTool does not continue with the main program execution until a set of calls to one Queue-based method in the PSI is completed. For example, if you check out a project, and then click CheckinProject(s) in the main window, ProjTool waits until the Queue session for the QueueCheckinProject call is complete.

   If Wait until all Queue jobs are completed is selected, ProjTool waits for each individual queue request.

8. Click Save and Close.

Unlike the ProjTool implementation for Office Project Server 2007, ProjTool for Project Server 2010 does not have impersonation options in the ProjTool Settings dialog box. Impersonation is managed internally through the Project Server Advanced Logon dialog box, as described in Using Forms Authentication and Impersonation in ProjTool.

Using the ProjTool Main Window

The menu in the ProjTool main window (Figure 3) includes the following items:

• File   Log on as a different user, or log on by using impersonation.

• New   Create projects, projects from templates, custom fields, or enterprise resources. Build a project team, or back up and restore projects.

  The Backup or Restore Enterprise Projects dialog box enables you to save a snapshot of each selected project in the Draft database to the Archive database. You can also restore projects from the Archive database to the Draft database.

• Lookup Table   Create a simple lookup table, a multilanguage lookup table, display lookup table values, and set languages to use for multilanguage lookup tables on the Project Server test computer.

• Tools   Submenu items link to utilities that get an error description, reset the Project Server Queuing Service or Eventing service, restart SQL Server, reset IIS, or reset all services.

• Options   Refresh the grid or clear the status messages. The Settings submenu shows the ProjTool Settings dialog box (Figure 2).

• Help   Shows the About ProjTool dialog box.

Figure 3. Action buttons, list of projects, and status text box in the ProjTool main window

In addition to the menu items, the main window shows a series of action buttons above the project data grid, as follows:

• Delete Project   Deletes one or more selected projects. You can delete from both the Published database and the Draft database, or from only the Published database.

• Checkin Project(s)   Enables you to select a simple or forced check-in of the selected projects. You can use forced check-in if a project is checked out by another user or if the checkout was done with a different Queue session ID.

• Checkout Project(s)   Enables you to check out one or more selected projects in the ProjTool main window, and check them in by using the Checkin Project(s) button.

  Note

  The Queue session ID is not valid for checking in projects by using another window, such as the Project Details dialog box.

• Publish Project(s)   Saves projects from the Draft database to the Published database. You can choose a full publish or a partial publish. The publish process in ProjTool does not create or modify a SharePoint site for the project. You can add that capability in ProjTool with additional user interface components and logic for the QueuePublish method.

• Read Project Details   Shows a dialog box with the entire set of tables in the ProjectDataSet for the selected project (Figure 5). You can add tasks, make changes in the data, and compare the Draft data with the Published data.

  Note

  If you check out the project in the main ProjTool window, and then edit data in the Project Details dialog box, you get a CICOCheckedOutInOtherSession error when you update the data. The project is already checked out by using a different Queue session ID.

• Rename Project   Renames the selected project in the Draft database and the Published database.

• Refresh   Executes the ReadProjectsList method to repopulate the grid.

• Exit   Exits ProjTool.

The text box at the bottom of the main window records the status of actions, with the most recent at the top. The text box also shows XML data from System.ServiceModel.FaultException errors that a PSI call can generate. The status bar at the bottom of the main window shows the Project Server version number and the current date and time.

The May 2010 release version number for Project Server 2010 is 14.0.4750.1000. The corresponding release version of Microsoft Project Professional 2010 is 14.0.4751.1000.

Creating Projects

To create one or more test projects, click Projects on the New menu in the ProjTool main window. Figure 4 shows the Create Server-Side Projects dialog box. In addition to creating multiple projects, you can optionally add tasks to each project, create and add local work, material, or cost resources, and publish the projects.

Figure 4. Using the Create Server-Side Projects dialog box

If the project name prefix is ProjTool Test- and you create two projects, ProjTool increments the project names as ProjTool Test-1 and ProjTool Test-2.

When you click Create Projects and then click Close, you may need to refresh the ProjTool main window to show the new projects in the grid.

Modifying Project Data

To see the Project Details dialog box, select one project in the ProjTool main window, and then click Read Project Details.

Figure 5. Using the Project Details dialog box

The grid tabs show all of the datatables in the ProjectDataSet for the selected project. For example, click the Task tab to show data in the TaskDataTable (Figure 5). The first task is the project summary task (TASK_ID = 0). If the project is not already checked out, you can add and delete tasks and set task properties.

Read/write fields in each table have a white background; read-only fields are gray. ProjTool shows updated fields that are read/write as yellow. When you change some fields in ProjTool, Project Server can internally change related read-only fields. ProjTool shows read-only fields that Project Server changes as light yellow. When you are finished making changes, click Update Project. For example, Figure 5 shows that ProjTool changed the name of task 1 in the project.

To use enterprise resources in the project, click Build Team. Instead of using ProjTool to make a set of changes for the project team, sometimes it is easier to make the changes by using Project Professional 2010.

To save the ProjectDataSet to an XML file, click Save DataSet to XML. You can save the entire ProjectDataSet before and after you make changes, and then easily compare the XML files with a tool such as Beyond Compare.

When you change an assignment percent complete or other timephased value, click Update Project to show changes in related fields.

For example, if you change the value of the ASSN_PCT_WORK_COMPLETE field to 75 for an assignment, and then click Update Project, several additional fields show the changes in yellow (Figure 6). The changed fields in the Assignment table include ASSN_ACT_WORK and ASSN_REM_WORK. In the Task table, the TASK_REM_DUR, TASK_PCT_COMP, TASK_PCT_WORK_COMP, TASK_ACT_WORK, and TASK_REM_WORK fields also show yellow changes for that task and for the project summary task.

Figure 6. Changing an assignment percent complete also changes other fields

Several of the read-only fields also show changes in a light yellow background, such as MOD_DATE in the Task table and Assignment table, and TASK_ACT_DUR, TASK_RESUME_DATE, TASK_STOP_DATE, and TASK_COMPLETE_THROUGH in the Task table. There are additional changes in the Project table and the ProjectResource table.

Creating Multilanguage Lookup Tables

The LookupTable menu in the ProjTool main window contains the following items:

• Simple LookupTable   Displays the Create and Manage Lookup Tables dialog box, and shows all of the data in the LookupTableDataSet in a grid with tabs for the datatables (LookupTables, LookupTableMasks, and LookupTableTrees).

• MultiLanguage LookupTable   Creates multilanguage lookup tables for testing.

• Display LookupTable Values   Shows values in simple or multilanguage lookup tables (Figure 8).

• Set Server Language   Creates Project Server database tables that can hold simulated multilanguage lookup table data, for testing purposes (Figure 7).

You can check out, modify, update, and delete lookup tables in the Create and Manage Lookup Tables dialog box. With the Load Assembly and Create LT from Assembly buttons, you can open a Microsoft .NET Framework assembly and create a lookup table for testing purposes by using the assembly namespace.

You can create multilanguage lookup tables on a test Project Server installation. ProjTool enables you to simulate installing multiple language database tables on the server for testing purposes. It is not necessary to install Project Server language packs to test creating multilanguage lookup tables. The languageList variable in ProjTool contains the list of active Project Server languages.

Figure 7. Language Installer dialog box

Procedure 3. To create and view a sample multilanguage lookup table

1. Click Set Server Language on the LookupTable menu in the ProjTool main window.

   1. In the Language Installer dialog box (Figure 7), select another language in addition to the Project Server primary language in Add/Remove Languages. For example, select English and French. The Project Server primary language should always be selected.

   2. Type the name of the Microsoft SQL Server instance that Project Server uses, and then set the logon properties.

   3. Click Get DataBase List to show the list of databases.

   4. Select the Project Server Published database in the drop-down list for the Project Web App instance that you are using.

   5. Click Save. ProjTool creates the necessary database tables and restarts IIS. You can see the current installed languages in the list. Click Close.

2. Click Multi-Language LookupTable in the LookupTable menu.

   1. In the Create Multi-Language Lookup Tables dialog box, type a name for the lookup table. For example, type LangTest.

   2. Select the primary LCID, for example 1033.

   3. Select the languages that you want in the Languages list; for example, select English and French.

   4. Type 2 for the Number of Levels; 3 for the Values for each Level; and 4 for the Values Length (the number of sample characters in each value).

   5. Click Create, and then click Close.

3. Click Display LookupTable Values in the LookupTable menu.

   1. Select the lookup table in the drop-down list. For example, select LangTest.

   2. Select the language in the drop-down list (Figure 8), and then click Get Values.

Figure 8 shows the lookup table structures and values for the example LangTest multilanguage lookup table. ProjTool creates sample characters in the LT_VALUE_TEXT field, where the number of characters in the first word is the length of each value and the characters are valid in the languages that you used. For example, the value of the first English node is ÂÞæÛ eng 1033 and the value of the same node in French is ÂÞæÛ fra 1036.

Figure 8. Viewing values in a multilanguage lookup table

To see the structure of the multilanguage lookup table that you created in ProjTool, open it in Project Web App. On the Server Settings page, click Enterprise Custom Fields and Lookup Tables. On the Enterprise Custom Fields and Lookup Tables page, for example, click LangTest in the Lookup Tables for Custom Fields section. Project Web App shows only the values for the Project Server language pack that is installed. The ÂÞæÛ eng 1033 value in the test example is one of the two top levels, each of which has three sublevels.

For more information about lookup tables and custom fields, see Local and Enterprise Custom Fields and Walkthrough: Creating a Hierarchical Lookup Table. For a list of language codes, see Locale ID (LCID) Chart.

Using Forms Authentication and Impersonation in ProjTool

To use impersonation with Project Server 2010, you must set permissions for the current user (or the user's group) in the Project Server service application by using the Manage Service Applications page in the SharePoint 2010 Central Administration application. You must also set permissions for the Project Web App site by using the command on the Site Actions menu in Project Web App. For step-by-step procedures about how to set permissions for impersonation, see How to: Use Impersonation with WCF.

Unlike the ProjTool implementation for Office Project Server 2007, the Project Web App site does not have to be running under the logged-on user's credentials. For Forms authentication, ProjTool for Project Server 2010 uses the Authentication web service that is part of Microsoft SharePoint Foundation 2010. In addition, ProjTool uses the SiteData web service to get the Project Web App site ID.

The P14Login method in the Program.cs file is the main logon method in ProjTool. The following code is part of the method for the case where logon is not by impersonation.

if (!isImpersonated)
{
    if (isWindowsAuth)
    {
        if (useDefaultWindowsCredentials)
        {
            result = true;
        }
            /* . . . */
    }
    else    
    {
        // Forms authentication requires the Authentication web service in 
        // Microsoft SharePoint Foundation 2010.
        result = WcfHelpers.LogonWithMsf(userName, password, new Uri(baseUrl));
    }
}

The WcfHelpers class is in a separate Visual Studio project. In the LogonWithMsf method, the authentication object is initialized with the Project Web App URL and a CookieContainer object, and then the Authentication.Login method can accept a Forms user.

public class WcfHelpers
{
    // Use the Authentication class in the SharePoint Foundation web services, not in the PSI.
    private static Authentication authentication = null;
    private static AuthenticationMode mode = AuthenticationMode.Windows;
    private static CookieContainer cookieContainer = null;
    private static String impersonationContextString = String.Empty; 

    /* . . . */

    // Log on by using the Authentication web service in SharePoint Foundation.
    public static bool LogonWithMsf(string username, string password, Uri pwaURI)
    {
        if (authentication == null)
        {
            string rootUrl = pwaURI.Scheme + Uri.SchemeDelimiter + pwaURI.Host + ":" + pwaURI.Port;

            authentication = new Authentication();
            authentication.Url = rootUrl + "/_vti_bin/Authentication.asmx";
        }

        authentication.CookieContainer = new System.Net.CookieContainer();
        LoginResult result = authentication.Login(username, password);

        mode = authentication.Mode();
        cookieContainer = authentication.CookieContainer;

        return (result.ErrorCode == LoginErrorCode.NoError);
    }

    /* . . . */
}

To use impersonation in ProjTool, on the File menu, click Log On As. In the Project Server Advanced Logon dialog box (Figure 9), you can select a name from the list of enterprise resources in the drop-down list. When you impersonate an enterprise resource, you assume the permissions of that user. Impersonation is useful for testing security for applications that integrate with Project Server; however, the use of impersonation should be minimized in production applications.

Figure 9. Project Server Advanced Logon dialog box

Setting Headers for Forms Authentication and Impersonation

When you log on Project Server 2010 by using Forms authentication or impersonation, each set of calls to a specific PSI service must be set within an OperationContextScope block. In the following CreateProject method in the Program.cs file, the scope object is valid for the projectClient object. You can call multiple methods in the Project service within that block, but you cannot call methods in other PSI services. You also cannot nest OperationContextScope blocks.

public static bool CreateProject(SvcProject.ProjectDataSet projectDataSet)
{
    jobGuid = Guid.NewGuid();
    bool result = true;

    using (OperationContextScope scope = new OperationContextScope(projectClient.InnerChannel))
    {
        WcfHelpers.UseCorrectHeaders(isImpersonated);
        projectClient.QueueCreateProject(jobGuid, projectDataSet, false);
    }
    if (waitForQueue)
    {
        result = WaitForQueueJobCompletion(jobGuid, NO_QUEUE_MESSAGE /* SvcQueueSystem.QueueMsgType.ProjectCreate*/);
    }
    return result;
}

The UseCorrectHeaders method in the WcfHelpers class sets the correct HTTP headers for Windows authentication, Forms authentication, multi-authentication, and impersonation for PSI calls within that scope, in the following code.

private static AuthenticationMode mode = AuthenticationMode.Windows;
private static CookieContainer cookieContainer = null;
private static String impersonationContextString = String.Empty; 

public static CookieContainer CookieContainer
{
    get
    { return cookieContainer; }
}

public static AuthenticationMode AuthenticationMode
{
    get
    { return mode; }
}

public static string HeaderXformsKey
{
    get
    { return "X-FORMS_BASED_AUTH_ACCEPTED"; }
}

public static string HeaderXformsValue
{
    get
    { return "f"; }
}

/* . . . */

 public static void UseWindowsAuthOnMultiAuthHeader()
{
    WebOperationContext.Current.OutgoingRequest.Headers.Remove(HeaderXformsKey);
    WebOperationContext.Current.OutgoingRequest.Headers.Add(HeaderXformsKey, 
        HeaderXformsValue);
}

public static void UseCookieHeader()
{
    if (cookieContainer != null)
    {
        var cookieString = cookieContainer.GetCookieHeader(new Uri(authentication.Url));

        WebOperationContext.Current.OutgoingRequest.Headers.Remove("Cookie");
        WebOperationContext.Current.OutgoingRequest.Headers.Add("Cookie", cookieString);
    }
}

public static void UseCorrectHeaders(bool isImpersonated)
{
    if (isImpersonated)
    {
        // Use WebOperationContext in the HTTP channel, not the OperationContext.
        WebOperationContext.Current.OutgoingRequest.Headers.Remove("PjAuth");
        WebOperationContext.Current.OutgoingRequest.Headers.Add("PjAuth", 
            impersonationContextString);
    }

    if (mode == AuthenticationMode.Windows)
    {
        UseWindowsAuthOnMultiAuthHeader();
    }

    UseCookieHeader();
}

The UseCorrectHeaders method first checks whether the call is through impersonation. If so, it removes any existing PjAuth header, and then adds a PjAuth header that includes the value of the impersonation context. For an example of code that gets and sets the impersonation context, see the WcfHelpers class in the ProjTool source code, or see How to: Use Impersonation with WCF.

For Windows authentication and for multi-authentication, the UseCorrectHeaders method calls UseWindowsAuthOnMultiAuthHeader to remove any header named X-FORMS_BASED_AUTH_ACCEPTED, and then adds that header again with the value f. Finally, if the cookieContainer object exists, UseCorrectHeaders calls UseCookieHeader to add the cookie for Forms authentication. The LogonWithMsf method initializes the cookieContainer object when logon is by Forms authentication.

For more information about multi-authentication in the SharePoint claims environment, see the Using Claims Multi-Authentication section in Prerequisites for WCF-Based Code Samples.

See Also

Tasks

How to: Create a Proxy Assembly for WCF Services

How to: Use Impersonation with WCF

Concepts

Overview of WCF and the PSI

Prerequisites for WCF-Based Code Samples

Local and Enterprise Custom Fields

Other Resources

Using the ProjTool Test Application with Project Server 2007

Project Programmability blog post for ProjTool

Locale ID (LCID) Chart

Walkthrough: Creating a Hierarchical Lookup Table