For at least 9 years I worked on a project called mpFx, which is just marketing-speak for a library that encapsulated the Project Server Interface to ease Project Server development. It started out open source and then shipped with a product later on as an internal asset.

You can find plenty of information about it with this search.

Time (Again) for An Encapsulation Library for Project Server and Beyond

When CSOM arrived (Client-Server Object Model) for SharePoint and Project Server 2013-2016 and Online, I knew there was another opportunity to make things just a little easier, although this time around the easing was less painful in the birthing because the CSOM is a nice API to start with.

I did some preliminary work on an encapsulation library but I didn’t get deep into it until joining DeltaBahn LLC, where I am chief architect. Sorry folks, this one won’t like end up open source, but I will share pieces of it that may help you out.

But, to wet your whistle, I will give you and idea of the overall API layout I am designing by showing you some sample code and then I will dive into a particular piece of the code that may help somebody out there.

CloudClient for Project Server Development

This time around, my encapsulation library covers much more than the PSI. It includes functionality for working with SharePoint, Project Server, Project Server oData, and some Azure features as well.

Let’s take a look at connecting to Office 365 with a “Scope”, which defines which major components of Office Online you want to work with: CSOM for SharePoint, CSOM for Project Server, and Project Server oData. This scoping approach allows you to be light as your requirements demand.

What follows comes from my unit tests. The method is called from the ConnectTest unit test:

public static CloudClient Connect()
{
    try
    {
        ServerOptions serverOptions = new ServerOptions
        {
            Url = ConfigurationExtensions.Get(@"POLInstance"),
            UserName = ConfigurationExtensions.Get(@"UserName"),
            Password = ConfigurationExtensions.Get(@"Password").ToSecureString(),
            DefaultTimeoutInMilliseconds = ConfigurationExtensions.Get(@"Timeout"),
            MaxRetryCount = ConfigurationExtensions.Get(@"MaxRetryCount"),
            Scope = ServerOptions.Union(Scope.ProjectCSOM, Scope.SharePointCSOM, Scope.ProjectOData)
        };
 
        CloudClient cloudClient = new CloudClient(serverOptions);
 
        cloudClient.OnConnectionStatusChanged += CloudClient_OnConnectionStatusChanged                
        cloudClient.OnStatusChanged += CloudClient_OnStatusChanged;
        cloudClient.OnError += CloudClient_OnError;
 
        cloudClient.Connect();
 
        return cloudClient;
    }
    catch (ServerException serverException)
    {
        DebugFx.WriteLine(serverException.GetMessage());
    }
    catch (CloudClientException exception)
    {
        DebugFx.WriteLine(exception.CreateMessage(false));
    }
    catch (Exception exception)
    {
        DebugFx.WriteLine(exception.GetType().Name);
        DebugFx.WriteLine(exception.CreateMessage(false));
    }
 
    throw new CloudClientException(Resources.ERROR_FAILED_TO_CONNECT);
}

public static CloudClient Connect()

{

try

{

ServerOptions serverOptions = new ServerOptions

{

Url = ConfigurationExtensions.Get(@"POLInstance"),

UserName = ConfigurationExtensions.Get(@"UserName"),

Password = ConfigurationExtensions.Get(@"Password").ToSecureString(),

DefaultTimeoutInMilliseconds = ConfigurationExtensions.Get(@"Timeout"),

MaxRetryCount = ConfigurationExtensions.Get(@"MaxRetryCount"),

Scope = ServerOptions.Union(Scope.ProjectCSOM, Scope.SharePointCSOM, Scope.ProjectOData)

};

CloudClient cloudClient = new CloudClient(serverOptions);

cloudClient.OnConnectionStatusChanged += CloudClient_OnConnectionStatusChanged

cloudClient.OnStatusChanged += CloudClient_OnStatusChanged;

cloudClient.OnError += CloudClient_OnError;

cloudClient.Connect();

return cloudClient;

}

catch (ServerException serverException)

{

DebugFx.WriteLine(serverException.GetMessage());

}

catch (CloudClientException exception)

{

DebugFx.WriteLine(exception.CreateMessage(false));

}

catch (Exception exception)

{

DebugFx.WriteLine(exception.GetType().Name);

DebugFx.WriteLine(exception.CreateMessage(false));

}

throw new CloudClientException(Resources.ERROR_FAILED_TO_CONNECT);

}

You can see in the creation of the ServerOptions, towards the end, the Scope, which is the union of bit flags that signal the API which component parts to initialize.
Another unit test enumerates through the projects and tasks. In this case I am doing some additional processing on a project called “CTA Test I”, which is where we will dive into my “how-to” for this post.

How-To Read Text Custom Fields Backed by a Lookup Table

[TestMethod]
[Localizable(false)]
public void EnumerateProjectTasks()
{
    ClientTester.TestContext = TestContext;
 
    using (CloudClient client = ClientTester.Connect())
    {
        Assert.IsTrue(client != null);
 
        foreach (KeyValuePair&lt;Guid, PSProject&gt; kvp in client.PublishedProjects)
        {
            PSProject project = kvp.Value;
 
            if (!project.Name.Equals("CTA Test I"))
            {
                continue;
            }
 
            ClientTester.WriteLine("Project Name: " + project.Name);
 
            foreach (PublishedTask task in project.Tasks)
            {
                ClientTester.WriteLine(DebugFx.Tab + "Task Name: " + task.Name);
                ClientTester.WriteLine(DebugFx.Tab + "Task Start: " + task.Start);
                ClientTester.WriteLine(DebugFx.Tab + "Task Finish: " + task.Finish);
 
                ClientTester.WriteLine(DebugFx.Tab + "-------------------------------------------");
                ClientTester.WriteLine("Custom Field Data");
 
                client.PSLoad(task);
 
                foreach (CustomField customField in task.CustomFields)
                {
                    if (task[customField.InternalName] == null)
                    {
                        continue;
                    }
 
                    ClientTester.WriteLine(DebugFx.Tab + "Custom Field Name: " + customField.Name);
                    ClientTester.WriteLine(DebugFx.Tab + "Custom Field Type: " + customField.FieldType);
 
                    switch (customField.FieldType)
                    {
                        case CustomFieldType.COST:
                        case CustomFieldType.DATE:
                        case CustomFieldType.FINISHDATE:
                        case CustomFieldType.DURATION:
                        case CustomFieldType.FLAG:
                        case CustomFieldType.NUMBER:
                            ClientTester.WriteLine(DebugFx.Tab + "Custom Field Value: " + task[customField.InternalName]);
                            break;
                        case CustomFieldType.TEXT:
 
                            bool isList;
 
                            object result = client.CustomFields.GetTaskValue(task, customField, out isList);
 
                            if (isList)
                            {
                                foreach (string value in result as List)
                                {
                                    ClientTester.WriteLine(DebugFx.Tab + "Custom Field Value: " + value);
                                }
                            }
                            else
                            {
                                ClientTester.WriteLine(DebugFx.Tab + "Custom Field Value: " + result);
                            }
 
                            break;
                        default: throw new ArgumentOutOfRangeException();
                    }
                }
            }
        }
 
        Assert.IsTrue(client.PublishedProjects != null);
 
        client.Close();
    }
}

[TestMethod]

[Localizable(false)]

public void EnumerateProjectTasks()

{

ClientTester.TestContext = TestContext;

using (CloudClient client = ClientTester.Connect())

{

Assert.IsTrue(client != null);

foreach (KeyValuePair<Guid, PSProject> kvp in client.PublishedProjects)

{

PSProject project = kvp.Value;

if (!project.Name.Equals("CTA Test I"))

{

continue;

}

ClientTester.WriteLine("Project Name: " + project.Name);

foreach (PublishedTask task in project.Tasks)

{

ClientTester.WriteLine(DebugFx.Tab + "Task Name: " + task.Name);

ClientTester.WriteLine(DebugFx.Tab + "Task Start: " + task.Start);

ClientTester.WriteLine(DebugFx.Tab + "Task Finish: " + task.Finish);

ClientTester.WriteLine(DebugFx.Tab + "-------------------------------------------");

ClientTester.WriteLine("Custom Field Data");

client.PSLoad(task);

foreach (CustomField customField in task.CustomFields)

{

if (task[customField.InternalName] == null)

{

continue;

}

ClientTester.WriteLine(DebugFx.Tab + "Custom Field Name: " + customField.Name);

ClientTester.WriteLine(DebugFx.Tab + "Custom Field Type: " + customField.FieldType);

switch (customField.FieldType)

{

case CustomFieldType.COST:

case CustomFieldType.DATE:

case CustomFieldType.FINISHDATE:

case CustomFieldType.DURATION:

case CustomFieldType.FLAG:

case CustomFieldType.NUMBER:

ClientTester.WriteLine(DebugFx.Tab + "Custom Field Value: " + task[customField.InternalName]);

break;

case CustomFieldType.TEXT:

bool isList;

object result = client.CustomFields.GetTaskValue(task, customField, out isList);

if (isList)

{

foreach (string value in result as List)

{

ClientTester.WriteLine(DebugFx.Tab + "Custom Field Value: " + value);

}

else

{

ClientTester.WriteLine(DebugFx.Tab + "Custom Field Value: " + result);

}

break;

default: throw new ArgumentOutOfRangeException();

}

Assert.IsTrue(client.PublishedProjects != null);

client.Close();

}

I a not doing anything in particular with the custom field values except for in the method object result = client.CustomFields.GetTaskValue(task, customField, out isList). Text fields in Project Server have the unique condition of being either text, a textual lookup value from a lookup table, or a list of entries from a lookup table.
The situation is this: I have two custom fields backed by lookup fields. One allows for more than one selection, and another allows a single selection. I call client.PSLoad(task); which is a shortcut for LoadQuery and Execute, which in a production application would use generics to include just what you need, like this:

_CloudClient.PSContext.Load(PublishedProject.Tasks,
    tasks =&gt; tasks.Include(t =&gt; t.Name,
        t =&gt; t.Start,
        t =&gt; t.Finish,                    
        t =&gt; t.TaskType,
        t =&gt; t.Predecessors,
        t =&gt; t.Successors,
        t =&gt; t.IsSubProject,
        t =&gt; t.CustomFields));
 
_CloudClient.PSContext.ExecuteQuery();

_CloudClient.PSContext.Load(PublishedProject.Tasks,

tasks => tasks.Include(t => t.Name,

t => t.Start,

t => t.Finish,

t => t.TaskType,

t => t.Predecessors,

t => t.Successors,

t => t.IsSubProject,

t => t.CustomFields));

_CloudClient.PSContext.ExecuteQuery();

However, for the purposes of getting to the meat of what we are doing here with lookup fields, I just load the entire task. Let’s take a look at that.

object result = client.CustomFields.GetTaskValue(task, customField, out isList); 
public object GetTaskValue(PublishedTask task, CustomField customField, out bool isList)
{
    if (task == null)
    {
        throw new ArgumentNullException(nameof(task));
    }
    if (customField == null)
    {
        throw new ArgumentNullException(nameof(customField));
    }
 
    isList = false;
 
    if (!(task[customField.InternalName] is string[]))
    {
        return task[customField.InternalName];
    }
 
    if (!customField.IsObjectPropertyInstantiated(@"LookupEntries"))
    {
        CloudClient.PSLoad(customField.LookupEntries);
    }
            
    string[] values = task[customField.InternalName] as string[];
 
    if (values.Length == 1)
    {
        LookupEntry lookupEntry = customField.LookupEntries.FirstOrDefault(e =&gt; e.InternalName.Equals(values[0]));
 
        if (lookupEntry != null)
        {
            return lookupEntry.FullValue;
        }
 
        throw new InvalidOperationException(Resources.ERROR_INVALID_CF_STATE_LT_MISSING_ENTRY);
    }
 
    List valueList = new List();
 
    foreach (string entry in values)
    {
        LookupEntry lookupEntry = customField.LookupEntries.FirstOrDefault(e=&gt;e.InternalName.Equals(entry));
 
        if (lookupEntry == null)
        {
            throw new InvalidOperationException(Resources.ERROR_INVALID_CF_STATE_LT_MISSING_ENTRY);
        }
 
        valueList.Add(lookupEntry.FullValue);
    }
 
    isList = true;
    return valueList

object result = client.CustomFields.GetTaskValue(task, customField, out isList);

public object GetTaskValue(PublishedTask task, CustomField customField, out bool isList)

{

if (task == null)

{

throw new ArgumentNullException(nameof(task));

}

if (customField == null)

{

throw new ArgumentNullException(nameof(customField));

}

isList = false;

if (!(task[customField.InternalName] is string[]))

{

return task[customField.InternalName];

}

if (!customField.IsObjectPropertyInstantiated(@"LookupEntries"))

{

CloudClient.PSLoad(customField.LookupEntries);

}

string[] values = task[customField.InternalName] as string[];

if (values.Length == 1)

{

LookupEntry lookupEntry = customField.LookupEntries.FirstOrDefault(e => e.InternalName.Equals(values[0]));

if (lookupEntry != null)

{

return lookupEntry.FullValue;

}

throw new InvalidOperationException(Resources.ERROR_INVALID_CF_STATE_LT_MISSING_ENTRY);

}

List valueList = new List();

foreach (string entry in values)

{

LookupEntry lookupEntry = customField.LookupEntries.FirstOrDefault(e=>e.InternalName.Equals(entry));

if (lookupEntry == null)

{

throw new InvalidOperationException(Resources.ERROR_INVALID_CF_STATE_LT_MISSING_ENTRY);

}

valueList.Add(lookupEntry.FullValue);

}

isList = true;

return valueList

What follows is the output. Towards the bottom of the listing, in bold, the single-value lookup and the multi-value lookup values are apparent.

:Creating connection to Project Server Online: 'https://server/sites/pwa' 
:Project Server Online Version = 16.0.6420.1203
:Connected to Project Server Online Reporting Feed
:Connected to SharePoint Online
:SharePoint Server Online Version = 16.0.6420.1203
:Project Name: CTA Test I
:Loading Tasks
:Task Name: Define process for gathering requirements
:Task Start: 5/2/2017 8:00:00 AM
:Task Finish: 5/2/2017 5:00:00 PM
:-------------------------------------------
:Custom Field Data
:-------------------------------------------
:Custom Field Name: CTA Task Test Field Cost
:Custom Field Type: COST
:Custom Field Value: 320.000000
:Custom Field Name: CTA Task Test Field Date
:Custom Field Type: DATE
:Custom Field Value: 10/10/2010 8:00:00 AM
:Custom Field Name: CTA Task Test Field Flag
:Custom Field Type: FLAG
:Custom Field Value: True
<strong>-- Multiple Value field:
:Custom Field Name: CTA Task Test Field Lookup
:Custom Field Type: TEXT
:Custom Field Value: Brazil
:Custom Field Value: Canada
:Custom Field Value: Denmark
:Custom Field Value: Germany
:Custom Field Value: Italy
:Custom Field Value: Sweden
-- Single Value field:
:Custom Field Name: CTA Task Test Field Lookup Single Lookup
:Custom Field Type: TEXT
:Custom Field Value: Denmark
</strong>

:Creating connection to Project Server Online: 'https://server/sites/pwa'

:Project Server Online Version = 16.0.6420.1203

:Connected to Project Server Online Reporting Feed

:Connected to SharePoint Online

:SharePoint Server Online Version = 16.0.6420.1203

:Project Name: CTA Test I

:Loading Tasks

:Task Name: Define process for gathering requirements

:Task Start: 5/2/2017 8:00:00 AM

:Task Finish: 5/2/2017 5:00:00 PM

:-------------------------------------------

:Custom Field Data

:-------------------------------------------

:Custom Field Name: CTA Task Test Field Cost

:Custom Field Type: COST

:Custom Field Value: 320.000000

:Custom Field Name: CTA Task Test Field Date

:Custom Field Type: DATE

:Custom Field Value: 10/10/2010 8:00:00 AM

:Custom Field Name: CTA Task Test Field Flag

:Custom Field Type: FLAG

:Custom Field Value: True

<strong>-- Multiple Value field:

:Custom Field Name: CTA Task Test Field Lookup

:Custom Field Type: TEXT

:Custom Field Value: Brazil

:Custom Field Value: Canada

:Custom Field Value: Denmark

:Custom Field Value: Germany

:Custom Field Value: Italy

:Custom Field Value: Sweden

-- Single Value field:

:Custom Field Name: CTA Task Test Field Lookup Single Lookup

:Custom Field Type: TEXT

:Custom Field Value: Denmark

</strong>

You will notice that when you unpack the string array, each element of the array will begin with “Entry_” followed by the GUID of the lookup value.

Okay, that’s it for this evening.[/fusion_builder_column][/fusion_builder_row][/fusion_builder_container]

Time (Again) for An Encapsulation Library for Project Server and Beyond

CloudClient for Project Server Development

How-To Read Text Custom Fields Backed by a Lookup Table

About the Author: Colby Africa

Microsoft Dynamics 365 & A Developer’s Adventure Spelunking the SDK

Sortable Binding List for Generics

Code Snippets from Work and Play Volume II

Code Snippets from Work and Play Volume I

Making Project Server Development Easy

Time (Again) for An Encapsulation Library for Project Server and Beyond

CloudClient for Project Server Development

How-To Read Text Custom Fields Backed by a Lookup Table

Share This Story, Choose Your Platform!

About the Author: Colby Africa

Related Posts

Microsoft Dynamics 365 & A Developer’s Adventure Spelunking the SDK

Sortable Binding List for Generics

Code Snippets from Work and Play Volume II

Code Snippets from Work and Play Volume I