Resource.ReadResources Method

Gets filtered information about enterprise resources or users.

Namespace:  [Resource Web service]
Service reference: http://ServerName:32843/[Project Service Application GUID]/PSI/Resource.svc
Web service reference: http://ServerName/ProjectServerName/_vti_bin/PSI/Resource.asmx?wsdl

Syntax

'Declaration
<SoapDocumentMethodAttribute("https://schemas.microsoft.com/office/project/server/webservices/Resource/ReadResources", RequestNamespace := "https://schemas.microsoft.com/office/project/server/webservices/Resource/",  _
    ResponseNamespace := "https://schemas.microsoft.com/office/project/server/webservices/Resource/",  _
    Use := SoapBindingUse.Literal, ParameterStyle := SoapParameterStyle.Wrapped)> _
Public Function ReadResources ( _
    xmlFilter As String, _
    autoCheckOut As Boolean _
) As ResourceDataSet
'Usage
Dim instance As Resource
Dim xmlFilter As String
Dim autoCheckOut As Boolean
Dim returnValue As ResourceDataSet

returnValue = instance.ReadResources(xmlFilter, _
    autoCheckOut)

[SoapDocumentMethodAttribute("https://schemas.microsoft.com/office/project/server/webservices/Resource/ReadResources", RequestNamespace = "https://schemas.microsoft.com/office/project/server/webservices/Resource/", 
    ResponseNamespace = "https://schemas.microsoft.com/office/project/server/webservices/Resource/", 
    Use = SoapBindingUse.Literal, ParameterStyle = SoapParameterStyle.Wrapped)]
public ResourceDataSet ReadResources(
    string xmlFilter,
    bool autoCheckOut
)

Parameters

• xmlFilter
  Type: System.String
  Filter XML string as returned by Filter. String.Empty returns information about all resources.

• autoCheckOut
  Type: System.Boolean
  Automatically check out the resources for modification.

Return Value

Type: [Resource Web service].ResourceDataSet
A ResourceDataSet populated with enterprise resource information.

Remarks

The ReadResources method populates related data in the CalendarExceptions, ResourceAvailabilities, ResourceCustomFields and ResourceRates properties, in addition to the Resources property. The ReadUserList method can have better performance, but provides only the resource GUIDs and names.

With the exception of the secondary ResourceCustomFieldsDataTable, however, you can use the Fields.Add method to filter columns in the other secondary datatables of the ResourceDataSet. For more information, see How to: Use a Filter Parameter with PSI Methods.

Project Server Permissions

Examples

The following example retrieves enterprise resources or creates several resources if they do not exist, reads the resource using a resource filter, checks out each resource if available, updates the RES_CODE property of available resources, and checks the resources back in. It reports the before state, updates made, and the after state of the resources.

Please see Prerequisites for ASMX-Based Code Samples for critical information on running this code sample.

using System;
using System.Collections.Generic;
using System.Text;
using System.Net;
using System.Data;
using System.Web.Services.Protocols;
using System.Threading;
using PSLibrary = Microsoft.Office.Project.Server.Library;

namespace Microsoft.SDK.Project.Samples.CheckInResources
{
   class Program
   {
      [STAThread]
      static void Main()
      {
         try
         {
            const string PROJECT_SERVER_URI = "https://ServerName/ProjectServerName/";
            const string RESOURCE_SERVICE_PATH = "_vti_bin/psi/resource.asmx";

            ResourceWebSvc.ResourceDataSet resourceDs;
            PSLibrary.Filter resourceFilter;
            string filterXml;

            // Set up the Web service objects
            ResourceWebSvc.Resource resourceSvc = new ResourceWebSvc.Resource();

            resourceSvc.Url = PROJECT_SERVER_URI + RESOURCE_SERVICE_PATH;
            resourceSvc.Credentials = CredentialCache.DefaultCredentials;

            // Get the resources
            Console.WriteLine("Getting/Creating resources");
            Guid[] resources = EnsureEnterpriseResources(resourceSvc);

            // Read the resources so we can see what it looked like before.
            resourceFilter = GetResourceFilter(resources);
            filterXml = resourceFilter.GetXml();

            resourceDs = resourceSvc.ReadResources(filterXml, false);
            WriteTablesToConsole(resourceDs.Tables);

            // Check out resources so they can be modified
            Guid me = resourceSvc.GetCurrentUserUid();
            bool checkedOut =false;
            Random rand = new Random();
            // Modify the resources
            foreach(ResourceWebSvc.ResourceDataSet.ResourcesRow resourceRow in resourceDs.Resources)
            {
               Console.WriteLine("Check out " + resourceRow.RES_NAME);
               if (resourceRow.IsRES_CHECKOUTBYNull())
               {
                  resourceSvc.CheckOutResources(new Guid[] { resourceRow.RES_UID });
                  checkedOut=true;
               }
               else
               {
                  if (resourceRow.RES_CHECKOUTBY == me)
                  {
                     checkedOut = true;
                  }
                  else
                  {
                     checkedOut = false;
                     Console.WriteLine("\tCan't check out this resource, skip updating this one.");
                  }
               }
               if (checkedOut)
               {
                  ResourceWebSvc.ResourceDataSet updateDs = resourceSvc.ReadResource(resourceRow.RES_UID);
                  updateDs.Resources[0].RES_CODE = "A" + rand.Next(1000,9999) ;
                  Console.WriteLine("Update RES_CODE to " + updateDs.Resources[0].RES_CODE);
                  resourceSvc.UpdateResources(updateDs, false, false);
                  Console.WriteLine("Check in " + resourceRow.RES_NAME);
                  resourceSvc.CheckInResources(new Guid[] { resourceRow.RES_UID },false);
               }
               Console.ForegroundColor=ConsoleColor.Yellow;
               Console.WriteLine("".PadRight(30,'-'));
               Console.ResetColor();
            }

            // retrieve the data from the server for display
            resourceDs = resourceSvc.ReadResources(filterXml, false);
            WriteTablesToConsole(resourceDs.Tables);

         }
         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);
         }
         finally
         {
            Console.ResetColor();
            Console.WriteLine("\r\n\r\nPress any key...");
            Console.ReadKey();
         }
      }

      private static void WriteResourceState(ResourceWebSvc.ResourceDataSet resourceDs)
      {
         foreach (ResourceWebSvc.ResourceDataSet.ResourcesRow row in resourceDs.Resources.Rows)
         {
            // If the resource type is greater than the inactive offset, it is inactive.
            Console.ForegroundColor = ConsoleColor.Blue;
            Console.Write(row.RES_NAME);
            Console.ForegroundColor = ConsoleColor.Gray;
            Console.Write(" is ");
            if (row.RES_TYPE > (int)PSLibrary.Resource.Type.INACTIVATED_OFFSET)
            {
               Console.ForegroundColor = ConsoleColor.Red;
               Console.Write("Inactive\r\n");
            }
            else
            {
               Console.ForegroundColor = ConsoleColor.DarkGreen;
               Console.Write("Active\r\n");
            }
            Console.ResetColor();
         }
      }
      private static Guid[] EnsureEnterpriseResources(ResourceWebSvc.Resource resourceSvc)
      {
         string[] resourceNames = new string[] { "Lertchai Treetawatchaiwong", 
                                                 "Bricks", 
                                                 "Conference Room A",
                                                 "Rental"};
         PSLibrary.Resource.Type[] resourceTypes = new PSLibrary.Resource.Type[] { PSLibrary.Resource.Type.WorkResource, PSLibrary.Resource.Type.MaterialResource, PSLibrary.Resource.Type.WorkResource, PSLibrary.Resource.Type.CostResources };
         Guid[] resources = new Guid[resourceNames.Length];
         for (int i = 0; i < resourceNames.Length; i++)
         {
            resources[i] = EnsureEnterpriseResource(resourceSvc, resourceNames[i], resourceTypes[i]);
         }
         return resources;
      }
      private static Guid EnsureEnterpriseResource(ResourceWebSvc.Resource resourceSvc, string resourceName, PSLibrary.Resource.Type resourceType)
      {
         ResourceWebSvc.ResourceDataSet resourceDs = new ResourceWebSvc.ResourceDataSet();

         PSLibrary.Filter resourceFilter = new Microsoft.Office.Project.Server.Library.Filter();
         resourceFilter.FilterTableName = resourceDs.Resources.TableName;
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_UIDColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_NAMEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_INITIALSColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_TYPEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));

         PSLibrary.Filter.FieldOperator existingResource = new PSLibrary.Filter.FieldOperator(PSLibrary.Filter.FieldOperationType.Equal, resourceDs.Resources.RES_NAMEColumn.ColumnName, resourceName);
         resourceFilter.Criteria = existingResource;
         string filterXml = resourceFilter.GetXml();
         resourceDs = resourceSvc.ReadResources(filterXml, false);
         if (resourceDs.Resources.Count >= 1)
         {
            return resourceDs.Resources[0].RES_UID;
         }
         else
         {
            resourceDs = new ResourceWebSvc.ResourceDataSet();
            ResourceWebSvc.ResourceDataSet.ResourcesRow resourceRow = resourceDs.Resources.NewResourcesRow();
            resourceRow.RES_UID = Guid.NewGuid();
            resourceRow.RES_NAME = resourceName;
            resourceRow.RES_INITIALS = resourceName.Substring(0, 1) +
                              (resourceName.IndexOf(" ") > 0 ? resourceName.Substring(resourceName.IndexOf(" ") + 1, 1) : "");
            resourceRow.RES_TYPE = (int)resourceType;
            resourceDs.Resources.AddResourcesRow(resourceRow);
            resourceSvc.CreateResources(resourceDs, false, true);
            return resourceRow.RES_UID;
         }
      }

      private static PSLibrary.Filter GetResourceFilter(Guid[] resources)
      {
         ResourceWebSvc.ResourceDataSet resourceDs = new ResourceWebSvc.ResourceDataSet();
         PSLibrary.Filter resourceFilter = new PSLibrary.Filter();
         resourceFilter.FilterTableName = resourceDs.Resources.TableName;
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_UIDColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_NAMEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_INITIALSColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_TYPEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_CODEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));

         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_ACCRUE_ATColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_BOOKING_TYPEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));

         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_CAN_LEVELColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_CHECKOUTBYColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_CHECKOUTDATEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_COST_CENTERColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_DEF_ASSN_OWNERColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_EXTERNAL_IDColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_GROUPColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_HAS_NOTESColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_HIRE_DATEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_HYPERLINK_ADDRESSColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_HYPERLINK_FRIENDLY_NAMEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_HYPERLINK_SUB_ADDRESSColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));

         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_IDColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_IS_TEAMColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_IS_WINDOWS_USERColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_MATERIAL_LABELColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         //resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_NOTESColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));

         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_PHONETICSColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_RTF_NOTESColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));
         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_TERMINATION_DATEColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));

         resourceFilter.Fields.Add(new PSLibrary.Filter.Field(resourceDs.Resources.TableName, resourceDs.Resources.RES_TIMESHEET_MGR_UIDColumn.ColumnName, PSLibrary.Filter.SortOrderTypeEnum.None));


         //List<PSLibrary.Filter.FieldOperator> resourceFieldOps = new List<PSLibrary.Filter.FieldOperator>();
         PSLibrary.Filter.IOperator[] fos = new PSLibrary.Filter.IOperator[resources.Length];
         for (int i = 0; i < resources.Length; i++)
         {
            fos[i] = new PSLibrary.Filter.FieldOperator(PSLibrary.Filter.FieldOperationType.Equal, resourceDs.Resources.RES_UIDColumn.ColumnName, resources[i]);
         }

         PSLibrary.Filter.LogicalOperator lo = new Microsoft.Office.Project.Server.Library.Filter.LogicalOperator(PSLibrary.Filter.LogicalOperationType.Or, fos);

         resourceFilter.Criteria = lo;
         return resourceFilter;
      }
      // Write all contents of a table collection to the console
      private static void WriteTablesToConsole(System.Data.DataTableCollection theTables)
      {
         Console.ForegroundColor = ConsoleColor.DarkGreen;
         foreach (System.Data.DataTable table in theTables)
         {

            int[] columnWidths = new int[table.Columns.Count];
            int tableWidth = 0;
            string dataString;
            Console.WriteLine("Table: " + table.TableName);

            // Write out the column names and get their spacing
            StringBuilder tableRow = new StringBuilder();
            for (int i = 0; i < table.Columns.Count; i++)
            {
               columnWidths[i] = GetColumnWidth(table.Columns[i]);
               tableRow.Append(table.Columns[i].ColumnName.PadRight(columnWidths[i]));

               tableWidth += columnWidths[i];
            }
            // add a space so it won't wrap
            tableWidth += 1;
            // make the console as wide as the widest table
            Console.BufferWidth = (Console.BufferWidth > tableWidth ? Console.BufferWidth : tableWidth);
            tableRow.Append("\r\n");
            Console.Write(tableRow.ToString());

            // Write out the data
            foreach (DataRow row in table.Rows)
            {
               tableRow = new StringBuilder();
               for (int i = 0; i < table.Columns.Count; i++)
               {
                  dataString = row[i].ToString();
                  // truncate output if it is wider than 
                  // the desired column width
                  if (dataString.Length >= columnWidths[i])
                  {
                     dataString = dataString.Substring(0, columnWidths[i] - 1);
                  }
                  // add the output to the stringbuilder and pad right to fill
                  // up to the column width.
                  tableRow.Append(dataString.PadRight(columnWidths[i]));
               }
               tableRow.Append("\r\n");
               Console.Write(tableRow.ToString());
            }
            Console.Write("\r\n".PadLeft(tableWidth, '-'));
         }
         Console.ResetColor();
      }
      // Helper function for WriteTablesToConsole
      private static int GetColumnWidth(DataColumn column)
      {
         // Note: may not handle byte[]data types well
         const int MAX_COL_WIDTH = 40;
         int dataWidth = 0;

         //return 12 for numbers, 30 for dates, and string width for strings.
         switch (column.DataType.UnderlyingSystemType.ToString())
         {
            case "System.Boolean":
            case "System.Byte":
            case "System.Byte[]":
            case "System.Char":
            case "System.Decimal":
            case "System.Double":
            case "System.Int16":
            case "System.Int32":
            case "System.Int64":
            case "System.SByte":
            case "System.Single":
            case "System.UInt16":
            case "System.UInt32":
            case "System.UInt64":
               dataWidth = 12;
               break;
            case "System.DateTime":
            case "System.TimeSpan":
               dataWidth = 30;
               break;
            case "System.Guid":
               dataWidth = 37;
               break;
            case "System.String":
               // If it has a maxlength, use it
               if (column.MaxLength > 0)
               {
                  dataWidth = column.MaxLength;
               }
               else
               {
                  // Otherwise use the max col width
                  dataWidth = MAX_COL_WIDTH;
               }
               break;
            default:
               dataWidth = column.ColumnName.Length;
               break;
         }
         // truncate if over the max length
         if (dataWidth > MAX_COL_WIDTH)
         {
            dataWidth = MAX_COL_WIDTH;
         }
         // always be at least as wide as the colum name
         return (column.ColumnName.Length > (dataWidth) ? column.ColumnName.Length + 1 : dataWidth);
      }
   }
}

See Also

Reference

Resource Class

Resource Members

Resource Web Service

Other Resources

How to: Use a Filter Parameter with PSI Methods