Creating fields using CSOM

 

When creating a field, whether you are using CAML, server-side object mode, or one of the client-side object models, you typically specify the following attributes:

• The ID of the fied, which is a GUID
• The Name, which is the internal name of the field
• The StaticName, which is the static name of the field
• The DisplayName, which is display name of the field
• The Type attribute which indicates the data type of the field

Only the attributes ID, Name and Type are required. You also have a number of other attributes that you set in order to indicate whether the field is required, whether the field can be used in a sort order, etc. You can find a detailed list of possible attributes and a detailed description in this MSDN reference article.

The order in which you specify the attributes is of no importance, but I always have the habit of specifying the ID first, then the internal name, display name and data type (except in this post where the focus lays on the different data types that can be used  ). Setting the internal name is required, while the defining the static name is optional. The difference between the two fields is that the internal name needs to be unique within the site collection, and SharePoint can change this name at creation time to guarantee uniqueness. Static name must not be unique and will therefore not be changed by SharePoint.  Therefore it can be practical to specify both Name and StaticName attributes and set them to the same value.

Another point of interest is the SourceID attribute. You can set it, but you don't have to. Out of the box SharePoint fields all have the SourceID set to http://schemas.microsoft.com/sharepoint/v3,  and a lot of developers have the habit set their own custom fields to this same value. But you don't have to do this. If you look more closely at a field manually created by a user directly on a list, the sourceID is set to {$ListId:Lists/Demo List;}. A good practice is for example to build your SourceID as follows:

http://schemas.<company&gt;.com/<name of the application>/<release>

for example:

http://schemas.biwug.be/camldesigner/v1

This post gives you an overview of the different field types that you can create through CSOM.

Create a Text field

A simple text field can be created as follows:

string schemaTextField = "<Field ID='<GUID>' Type='Text' Name='LastName' StaticName='LastName' DisplayName='Last Name' />";

Field simpleTextField = demoList.Fields.AddFieldAsXml(schemaTextField, true, AddFieldOptions.AddToDefaultContentType);

clientContext.ExecuteQuery();

Written like this, SharePoint will ignore the internal name you specified, and will apply the display name. To make sure your internal name is applied, you have to add the AddFieldOptions.AddFieldInternalNameHint:

string schemaTextField = "<Field Type='Text' Name='LastName' StaticName='LastName' DisplayName='Last Name' />";

Field simpleTextField = demoList.Fields.AddFieldAsXml(schemaTextField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

You can find the (only) explanation of the AddFieldOptions enumeration here.

Know that this enumeration has the FlagsAttribute to allow a bitwise combination, meaning that you can combine the different values:

Field simpleTextField = demoList.Fields.AddFieldAsXml(schemaTextField, true, AddFieldOptions.AddFieldInternalNameHint | AddFieldOptions.AddToAllContentTypes);

Creating a hidden field

If you want to create a hidden field, you have to include the hidden attribute and set it to true:

string schemaTextField = "<Field Type='Text' Name='LastName' StaticName='LastName' DisplayName='Last Name' Hidden='TRUE' />";

Field simpleTextField = demoList.Fields.AddFieldAsXml(schemaTextField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Omitting this attribute will create a field visible to your users.

You can also

Creating an indexed field

While creating a field, you can also index it.

Field f = list.Fields.GetByInternalNameOrTitle(fieldName);

clientContext.Load(f);

clientContext.ExecuteQuery();

f.Indexed = true;

f.Update();

clientContext.ExecuteQuery();

Create a multi line field

You can create different types of multi line fields:

• a plain text field
• a rich text field
• an enhanced text field

A plain multi line text field

string schemaMultilineTextField = "<Field ID='<GUID>' Type='Note' Name='Comments' StaticName='Comments'

DisplayName='Comments' NumLines='6' RichText='FALSE' Sortable='FALSE' />"

Field multilineTextField = demoList.Fields.AddFieldAsXml(schemaMultilineTextField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

A rich multi line text field

string schemaRichTextField = "<Field ID='<GUID>' Type='Note' Name='Comments' StaticName='Comments'

DisplayName='Comments' NumLines='6' RichText='TRUE' Sortable='FALSE' />"

Field multilineTextField = demoList.Fields.AddFieldAsXml(schemaRichTextField , true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

An enhanced multi line text field

string schemaRichTextField = "<Field ID='<GUID>' Type='Note' Name='Comments' StaticName='Comments'

DisplayName='Comments' NumLines='6' RichText='TRUE' RichTextMode='FullHtml' IsolateStyles='TRUE' Sortable='FALSE' />"

Field multilineTextField = demoList.Fields.AddFieldAsXml(schemaRichTextField , true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Create a boolean field

In the SharePoint user interface this is called a Yes/No field.

string schemaBooleanField = "<Field Type='Text' Name='Married' StaticName='Married' DisplayName='Married' />";

Field booleanField = demoList.Fields.AddFieldAsXml(schemaBooleanField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

If you want to set a default value, you have to specify a 0 for false or a 1 for true:

string schemaBooleanField = "<Field Type='Boolean' Name='Married' StaticName='Married' DisplayName='Married'>"

+ "<Default>0</Default></Field>;

Field booleanField = demoList.Fields.AddFieldAsXml(schemaBooleanField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Create a DateTime field

A DateTime field is created in a similar way, but you can set additional properties, like the Format property. In case of a DateTime field, the format attribute will indicate whether you want to create a date only field, or a date time field.

Date only field

string schemaBirthDate = "<Field ID='<GUID>' Type='DateTime' Name='BirthDate' StaticName='BirthDate'

DisplayName='Birth date' Format='DateOnly' >"

+ "<Default>[Today]</Default></Field>";

Field birthDateField = demoList.Fields.AddFieldAsXml(schemaBirthDate, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

The Default node is optional. The sample code snippet indicates that today's date will be suggested to the user. If nothing is specified, no date will be sugested to the user.

Date and time field

string schemaArrivalField = "<Field ID='<GUID>' Type='DateTime' Name='ArrivalDateTime' StaticName='ArrivalDateTime'

DisplayName='Arrival' Format='DateTime'>"

   + "<Default>[Now]</Default></Field>";

Field birthDateField = demoList.Fields.AddFieldAsXml(schemaBirthDate, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

As in previous code sample, the Default node is optional. This sample code snippet indicates that the current date and time will be suggested to the user. If nothing is specified.

Create a Number field

With this type of field, you have to specify the different choices on beforehand. You can also choose if you want to show the different options within a dropdown list or with radio buttons.

string schemaNumberField = "<Field ID='<GUID>' Type='Number' Name='NbrOfEmployees' StaticName='NbrOfEmployees'

DisplayName='Number of employees' />";

Field birthDateField = demoList.Fields.AddFieldAsXml(schemaBirthDate, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Previous code snippet will create a standard number field where the user can set positive and negative numbers, and where the number of decimals is generated automatically. If you want to declare a number field that only allows positive numbers, you will have to declare it this way:

string schemaPosNumberField = "<Field ID='<GUID>' Type='Number' Name='NbrOfEmployees' StaticName='NbrOfEmployees'

DisplayName='Number of employees' Min='0' />";

And if you want to restrict the range of values that can be entered by the user, you have to declare the number field the following way:

string schemaNumberField = "<Field ID='<GUID>' Type='Number' Name='NbrOfEmployees' StaticName='NbrOfEmployees'

DisplayName='Number of employees' Min='0' Max='5000'/>";

You can also define the number of decimals:

string schemaNumberField = "<Field ID='<GUID>' Type='Number' Name='NbrOfEmployees' StaticName='NbrOfEmployees'

   DisplayName='Number of employees' Min='0' Decimals='0' />";

You can also create a percentage field by using the Number type. In that case you have to add an addition attribute Percentage, which you have to set to true:

string schemaPercentageField = "<Field ID='<GUID>' Type='Number' Name='NbrOfEmployees' StaticName='NbrOfEmployees'

   DisplayName='Number of employees' Percentage='True' Decimals='2' />";

Create a Choice field

With this type of field, you have to specify the different choices on beforehand. You can also choose if you want to show the different options within a dropdown list or with radio buttons.

Dropdown list

string schemaChoiceField = "<Field ID='<GUID>' Type='Choice' DisplayName='Menu Choice' Name='MenuChoice' StaticName='MenuChoice'

Format='Dropdown'>"

+ "<Default>Meat menu</Default>"

   +         "<CHOICES>"

   +         "    <CHOICE>Fish menu</CHOICE>"

   +         "    <CHOICE>Vegeterian menu</CHOICE>"

   +         "</CHOICES>"

+ "</Field>";

Field choiceField = demoList.Fields.AddFieldAsXml(schemaChoiceField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Radio buttons

string schemaChoiceField = "<Field ID='<GUID>' Type='Choice' Name='DessertChoice' StaticName='DessertChoice'

DisplayName='Desserts' Format='RadioButtons'>"

   + "<Default>Ice cream</Default>"

   +         "<CHOICES>"

   +         "    <CHOICE>Fresh fruit</CHOICE>"

   +         "    <CHOICE>Sorbet</CHOICE>"

   +         "</CHOICES>"

   + "</Field>";

Field choiceField = demoList.Fields.AddFieldAsXml(schemaChoiceField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Checkboxes

When creating Choice fields  in the user interface, you also have the option to display checkboxes to allow more than one selection:

To achieve this in code you have to set the Type attribute to MultiChoice. Of course, don't specify the Format attribute.

string schemaChoiceField = "<Field ID='<GUID>' Type='MultiChoice' Name='SideDishesChoice' StaticName='SideDishesChoice'

DisplayName = 'Side dishes' >"

+ "<Default>Patatoes</Default>"

   +         "<CHOICES>"

   +         "    <CHOICE>Fresh vegetables</CHOICE>"

   +         "    <CHOICE>Beans</CHOICE>"

+ " <CHOICE>Pepper Sauce</CHOICE>"

   +         "</CHOICES>"

+ "</Field>";

Field choiceField = demoList.Fields.AddFieldAsXml(schemaChoiceField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Fill In option

To allow users to fill in a different choice than already available, you have to add the FillInChoice attribute. If that attribute is omitted in the XML,  users will only be able to choose from the available options.

string schemaChoiceField = "<Field ID='<GUID>' Type='Choice' DisplayName='Menu Choice' Name='MenuChoice' StaticName='MenuChoice'

Format='Dropdown' FillInChoice='TRUE'>"

+ "<Default>Meat menu</Default>"

   +         "<CHOICES>"

   +         "    <CHOICE>Fish menu</CHOICE>"

   +         "    <CHOICE>Vegeterian menu</CHOICE>"

   +         "</CHOICES>"

+ "</Field>";

Field choiceField = demoList.Fields.AddFieldAsXml(schemaChoiceField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Create a Picture field

If you want to create a picture field, you have to set the field type to URL. An additional attribute Format will indicate that you want to create a picture field:

string schemaPictureField = "<Field ID='<GUID>' Type='URL' Name='EmployeePicture' StaticName='EmployeePicture'

DisplayName='Employee Picture' Format='Image'/>";

Field pictureField = demoList.Fields.AddFieldAsXml(schemaPictureField, true, AddFieldOptions.AddInternalNameHint);

clientContext.ExecuteQuery();

Create a URL field

If you want to create a field to contain an hyperlink, you also have to define a field of type URL, but in that case you set the Format attribute to Hyperlink:

string schemaUrlField = "<Field ID='<GUID>' Type='URL' Name='BlogUrl' StaticName='BlogUrl' DisplayName='Blog URL' Format='Hyperlink'/>";

Field urlField = demoList.Fields.AddFieldAsXml(schemaPictureField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Create a Lookup field

You typically create a lookup field when the value needs to be looked up in another SharePoint list. When creating a Lookup field, you also need to specify the necessary attributes to indicate the lookup list and the field that is shown when a value is selected:

string schemaLookupField = "<Field ID ='<GUID>' Type='Lookup' Name='Country' StaticName='Country' DisplayName='Country'

   List='Countries' ShowField='Title' />"

Field lookupField = demoList.Fields.AddFieldAsXml(schemaLookupField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

If you want to show another field from the lookup list, instead of the Title, you can set the ShowField attribute to another field.

You can also define how the relationship with the lookup field must behave.  But in that case the field needs to be indexed:

string schemaLookupField = "<Field ID ='<GUID>' Type='Lookup' Name='Country' StaticName='Country' DisplayName='Country'

    List='Countries' ShowField='Title' RelationshipDeleteBehavior='Restrict' Indexed='TRUE'/>"

If you want to create a multi-select lookup field, you have to use the type LookupMulti, and you have to set an additional attribute Mult (and not Multi):

string schemaMultiLookupField = "<Field ID ='<GUID>' Type='LookupMulti' Name='Country' StaticName='Country' DisplayName='Country'

    List='Countries' ShowField='Title' Mult='TRUE'/>"

Create a User field

A field of type User is defined as follows:

string schemaUserField = "<Field ID ='<GUID>' Type='User' Name='Employee' StaticName='Employee' DisplayName='Employee' />"

Field userField = demoList.Fields.AddFieldAsXml(schemaUserField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

You can set different attributes:

• UserSelectionMode: this attribute can be set to PeopleOnly or to PeopleAndGroups
• UserSelectionScope: this attribute can be set to limit the selection of possible users to a certain group. The value must be an integer value that indicates the ID of group

Following code sample defines a user field that allows selection of multiple users from the site member group:

string schemaUserField = "<Field ID ='<GUID>' Type='UserMulti' Name='Employee' StaticName='Employee' DisplayName='Employee'

UserSelectionMode='PeopleOnly' UserSelectionScope='7' Mult='TRUE'/>"

Create a Managed Metadata field

The creation of a managed metadata field requires a bit more than just defining the CAML. I'll add it here for completeness, but credits are for Waldek Mastykarz with his post Programmatically creating Site Columns and Content Types using the App Model

string schemaTaxonomyField = "<Field ID ='<GUID>' Type='TaxonomyFieldType' Name='ProductCategory' StaticName='ProductCategory'

DisplayName='ProductCategory' />"

Field field = demoList.Fields.AddFieldAsXml(schemaTaxonomyField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Of course, this is not enough; you also have to bind this field to a termset or term in the term store:

Guid termStoreId = Guid.Empty;

Guid termSetId = Guid.Empty;

GetTaxonomyFieldInfo(clientContext, out termStoreId, out termSetId);

   

// Retrieve the field as a Taxonomy Field

TaxonomyField taxonomyField = clientContext.CastTo<TaxonomyField>(field);

taxonomyField.SspId = termStoreId;

taxonomyField.TermSetId = termSetId;

taxonomyField.TargetTemplate = String.Empty;

taxonomyField.AnchorId = Guid.Empty;

taxonomyField.Update();

   

clientContext.ExecuteQuery();

In case you want to create a multi-select managed metadata field, you have to define a field of type TaxonomyFieldTypeMulti.

Create a Calculated field

Calculated fields can be created in a number of flavors. The following code snippet generates a calculated field that will show employee data based on the fields FirstName, LastName and EmployeeID. It will be formatted as follows:

Karine Bosch (id 82176)

string formula = "<Formula>=FirstName&amp; " " &amp;LastName&amp; " (id: " &amp;EmployeeID&amp; " "</Formula>"

      + "<FieldRefs>"

      + "<FieldRef Name='FirstName' />"

      + "<FieldRef Name='LastName' />"

      + "<FieldRef Name='EmployeeID' />"

      + "</FieldRefs>";

 

string schemaCalculatedField = "<Field ID='<GUID>' Type='Calculated' Name='FullName' StaticName='FullName'

DisplayName='Full Name' ResultType='Text' Required='TRUE' ReadOnly='TRUE'>" + formula + "</Field>";

Field fullNameField = demoList.Fields.AddFieldAsXml(schemaCalculatedField, true, AddFieldOptions.AddFieldInternalNameHint);

clientContext.ExecuteQuery();

Another example is a field that defaults to the year number of todays' date. In this case the element <DefaultFormula> is used within a Text field:

string fieldXml = "<Field DisplayName='Year' Type='Text'>"

+ "<DefaultFormula>=CONCATENATE(YEAR(Today))</DefaultFormula>"

+ "</Field>";

Field field = list.Fields.AddFieldAsXml(fieldXml, true,

AddFieldOptions.defaultValue);

context.ExecuteQuery();

Kudos to Steve Moucheron, who sent me his code snippet!