Share via


Project.CheckOutProject Method

Checks out a specified project.

Namespace:  WebSvcProject
Assembly:  ProjectServerWebServices (in ProjectServerWebServices.dll)

Syntax

'Declaration
<SoapDocumentMethodAttribute("http://schemas.microsoft.com/office/project/server/webservices/Project/CheckOutProject", RequestNamespace := "http://schemas.microsoft.com/office/project/server/webservices/Project/",  _
    ResponseNamespace := "http://schemas.microsoft.com/office/project/server/webservices/Project/",  _
    Use := SoapBindingUse.Literal, ParameterStyle := SoapParameterStyle.Wrapped)> _
Public Sub CheckOutProject ( _
    projectUid As Guid, _
    sessionUid As Guid, _
    sessionDescription As String _
)
'Usage
Dim instance As Project
Dim projectUid As Guid
Dim sessionUid As Guid
Dim sessionDescription As String

instance.CheckOutProject(projectUid, _
    sessionUid, sessionDescription)
[SoapDocumentMethodAttribute("http://schemas.microsoft.com/office/project/server/webservices/Project/CheckOutProject", RequestNamespace = "http://schemas.microsoft.com/office/project/server/webservices/Project/", 
    ResponseNamespace = "http://schemas.microsoft.com/office/project/server/webservices/Project/", 
    Use = SoapBindingUse.Literal, ParameterStyle = SoapParameterStyle.Wrapped)]
public void CheckOutProject(
    Guid projectUid,
    Guid sessionUid,
    string sessionDescription
)

Parameters

  • sessionUid
    Type: System.Guid
    GUID of the session in which the queue job is submitted.
  • sessionDescription
    Type: System.String
    Optional. Description of the session.

Remarks

CheckOutProject reserves (locks) the project for editing or deleting. If the project is unavailable for editing, an exception is raised. The lock is an application-level logical lock rather than a database lock. Projects must be locked before any changes can be made in either Project Professional or the Project Server APIs. When used along with the Shared Services Provider (SSP) APIs, the check-out operation is logically equivalent to opening a project with read/write permission in Project Professional.

The check-out operation is synchronous and is processed immediately.

The logical lock on the project is associated with the sessionUid and the user making the check-out call. Subsequent operations against the checked-out project are accepted only if the user is the same as the one who checked out the project and the call supplies the same sessionUid.

The sessionDescription parameter is an optional string that is stored as part of the project while it is checked out; the string specifies who has the project checked out. For Project Professional, sessionDescription is the computer name to which the project was checked out. For SSP calls, the user can supply whatever string makes sense; typically it is the name of the process that performed the check-out operation. (For example, "Timesheet updates", "Sync with SAP", and so forth.)

Project Server Permissions

Permission

Description

SaveProject

Save the specified project. Category permission.

EditProjectProperties

Can edit the new project. Category permission.

BuildTeamOnProject

Can assign resources from the resource pool to the new project. Category permission.

Examples

Applications typically call CheckOutProject, do some update or editing procedures, and then call QueueCheckInProject. The following example creates a sample project, checks out that project and renames it, and checks it back in

Please see Prerequisites for Reference Code Samples for critical information on running this code sample.

using System;
using System.Collections.Generic;
using System.Text;
using System.Net;
using System.Threading;
using System.Web.Services.Protocols;
using PSLibrary = Microsoft.Office.Project.Server.Library;
[assembly: CLSCompliant(true)]
namespace Microsoft.SDK.Project.Samples.CheckOutProject
{
   class Program
   {
      [STAThread]
      static void Main(string[] args)
      {
         try
         {
            #region Setup
            const string PROJECT_SERVER_URI = "http://ServerName/ProjectServerName/";
            const string PROJECT_SERVICE_PATH = "_vti_bin/psi/project.asmx";
            const string QUEUESYSTEM_SERVICE_PATH = "_vti_bin/psi/queuesystem.asmx";

            Guid jobId;
            Guid sessionId = Guid.NewGuid();
            const string SESSION_DESCRIPTION = "Check out sample utility";

            // Set up the Web service objects
            ProjectWebSvc.Project projectSvc = new ProjectWebSvc.Project();

            projectSvc.Url = PROJECT_SERVER_URI + PROJECT_SERVICE_PATH;
            projectSvc.UseDefaultCredentials = true;

            QueueSystemWebSvc.QueueSystem q = new QueueSystemWebSvc.QueueSystem();
            q.Url = PROJECT_SERVER_URI + QUEUESYSTEM_SERVICE_PATH;
            q.UseDefaultCredentials = true;
 
            // Create a sample project
            Console.WriteLine("Creating sample project");
            Guid projectId = CreateSampleProject(projectSvc, q);
            Console.WriteLine("Created Project UID: " + projectId.ToString());
            #endregion
            #region Check out, rename, and check in
            // Check out the project
            // The session ID is used later is used later to check in the project. 
            Console.WriteLine("Checking out sample project");
            projectSvc.CheckOutProject(projectId, sessionId, SESSION_DESCRIPTION);
           
            // Rename the project
            Console.WriteLine("Renaming the project");
            jobId = Guid.NewGuid();
            projectSvc.QueueRenameProject(jobId, sessionId, projectId, "My Renamed Project at " + DateTime.Now.ToShortTimeString().Replace(":", ""));
            WaitForQueue(q, jobId);

            // Check in the project
            Console.WriteLine("Checking in the project");
            jobId = Guid.NewGuid();
            projectSvc.QueueCheckInProject(jobId, projectId, false, sessionId, SESSION_DESCRIPTION);
            WaitForQueue(q, jobId);
            #endregion
         }
         #region Exception handling
         catch (SoapException ex)
         {
            PSLibrary.PSClientError error = new PSLibrary.PSClientError(ex);
            PSLibrary.PSErrorInfo[] errors = error.GetAllErrors();
            string errMess = "==============================\r\nError: \r\n";
            for (int i = 0; i < errors.Length; i++)
            {
               errMess += "\n" + ex.Message.ToString() + "\r\n";
               errMess += "".PadRight(30, '=') + "\r\nPSCLientError Output:\r\n \r\n";
               errMess += errors[i].ErrId.ToString() + "\n";

               for (int j = 0; j < errors[i].ErrorAttributes.Length; j++)
               {
                  errMess += "\r\n\t" + errors[i].ErrorAttributeNames()[j] + ": " + errors[i].ErrorAttributes[j];
               }
               errMess += "\r\n".PadRight(30, '=');
            }
            Console.ForegroundColor = ConsoleColor.Red;
            Console.WriteLine(errMess);
         }
         catch (WebException ex)
         {
            string errMess = ex.Message.ToString() +
               "\n\nLog on, or check the Project Server Queuing Service";
            Console.ForegroundColor = ConsoleColor.Red;
            Console.WriteLine("Error: " + errMess);
         }
         catch (Exception ex)
         {
            Console.ForegroundColor = ConsoleColor.Red;
            Console.WriteLine("Error: " + ex.Message);
         }
         #endregion
         finally
         {
            Console.ResetColor();
            Console.WriteLine("\r\n\r\nPress any key...");
            Console.ReadKey();
         }
      }
      static private void WaitForQueue(QueueSystemWebSvc.QueueSystem q, Guid jobId)
      {
         QueueSystemWebSvc.JobState jobState;
         const int QUEUE_WAIT_TIME = 2; // two seconds
         bool jobDone = false;
         string xmlError = string.Empty;
         int wait = 0;

         //Wait for the project to get through the queue
         // - Get the estimated wait time in seconds
         wait = q.GetJobWaitTime(jobId);

         // - Wait for it
         Thread.Sleep(wait * 1000);
         // - Wait until it is done.

         do
         {
            // - Get the job state
            jobState = q.GetJobCompletionState(jobId, out xmlError);

            if (jobState == QueueSystemWebSvc.JobState.Success)
            {
               jobDone = true;
            }
            else
            {
               if (jobState == QueueSystemWebSvc.JobState.Unknown
               || jobState == QueueSystemWebSvc.JobState.Failed
               || jobState == QueueSystemWebSvc.JobState.FailedNotBlocking
               || jobState == QueueSystemWebSvc.JobState.CorrelationBlocked
               || jobState == QueueSystemWebSvc.JobState.Canceled)
               {
                  // If the job failed, error out
                  throw (new ApplicationException("Queue request failed \"" + jobState + "\" Job ID: " + jobId + ".\r\n" + xmlError));
               }
               else
               {
                  Console.WriteLine("Job State: " + jobState + " Job ID: " + jobId);
                  Thread.Sleep(QUEUE_WAIT_TIME * 1000);
               }
            }
         }
         while (!jobDone);
      }
      static private Guid CreateSampleProject(ProjectWebSvc.Project projectSvc, QueueSystemWebSvc.QueueSystem q)
      {
         ProjectWebSvc.ProjectDataSet projectDs = new ProjectWebSvc.ProjectDataSet();
         Guid jobId;
         // Create the project
         ProjectWebSvc.ProjectDataSet.ProjectRow projectRow = projectDs.Project.NewProjectRow();
         projectRow.PROJ_UID = Guid.NewGuid();
         projectRow.PROJ_NAME = "Its a wonderful project at " + 
            DateTime.Now.ToShortDateString().Replace("/", "") + " " + 
            DateTime.Now.ToShortTimeString().Replace(":", "");
         projectRow.PROJ_TYPE = (int)PSLibrary.Project.ProjectType.Project;
         projectDs.Project.AddProjectRow(projectRow);

         // Add some tasks
         ProjectWebSvc.ProjectDataSet.TaskRow taskOne = projectDs.Task.NewTaskRow();
         taskOne.PROJ_UID = projectRow.PROJ_UID;
         taskOne.TASK_UID = Guid.NewGuid();
         //Task Duration format must be specified
         taskOne.TASK_DUR_FMT =(int) PSLibrary.Task.DurationFormat.Day;
         taskOne.TASK_DUR = 4800;  // 8 hours in duration units (minute/10)
         taskOne.TASK_NAME = "Task One";
         taskOne.TASK_START_DATE = System.DateTime.Now.AddDays(1);
         projectDs.Task.AddTaskRow(taskOne);

         ProjectWebSvc.ProjectDataSet.TaskRow taskTwo = projectDs.Task.NewTaskRow();
         taskTwo.PROJ_UID = projectRow.PROJ_UID;
         taskTwo.TASK_UID = Guid.NewGuid();
         //Task Duration format must be specified
         taskTwo.TASK_DUR_FMT = (int)PSLibrary.Task.DurationFormat.Day;
         taskTwo.TASK_DUR = 4800;  // 8 hours in duration units (minute/10)
         taskTwo.TASK_NAME = "Task Two";
         taskTwo.TASK_START_DATE = System.DateTime.Now.AddDays(1);
         projectDs.Task.AddTaskRow(taskTwo);

         // Save the project to the database
         jobId = Guid.NewGuid();
         projectSvc.QueueCreateProject(jobId, projectDs, false);
         WaitForQueue(q, jobId);
         return projectRow.PROJ_UID;
      }
   }
}

See Also

Reference

Project Class

Project Members

WebSvcProject Namespace