Karine Bosch’s Blog

On SharePoint

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 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:

multichoice

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 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();

 

Additional references:

18 Comments »

  1. […] You can read more on how to create other type of fields using CSOM here. […]

    Pingback by Creating fields using CSOM in SharePoint 2013 « Karine Bosch’s Blog | May 14, 2015 | Reply

  2. How to create multiple checkbox columns ?

    Comment by Dhruba Adhikari | October 8, 2015 | Reply

    • Let’s say that’s a challenge for this weekend🙂

      Comment by Karine Bosch | October 20, 2015 | Reply

    • string schemaBooleanField = “”
      + “0;
      Field booleanField = demoList.Fields.AddFieldAsXml(schemaBooleanField, true, AddFieldOptions.AddInternalNameHint);
      clientContext.ExecuteQuery();

      This is for the check box

      Comment by Paleru | June 29, 2016 | Reply

  3. Very good post! On “Create a boolean field” You need to specify the field type as “Boolean”, not “Text”.

    Comment by Terje Hognestad | October 20, 2015 | Reply

    • Thanks for noticing the typo! I corrected it in the post.

      Comment by Karine Bosch | October 20, 2015 | Reply

  4. Hi, and thanks for the handy reference.
    I think I spotted another small typo: In the Managed Metadata field markup you have included “List=’Countries’ ShowField=’Title'” – I think that must be a copy/paste mistake from the Lookup field?

    Comment by Mads de Vries Laursen | November 6, 2015 | Reply

    • Hi Mads, yes, you’re right. I updated the code snippet. Thanks for pointing out!
      Kind regards,
      Karine

      Comment by Karine Bosch | January 4, 2016 | Reply

  5. This is a great post, clear and concise information. Than you!

    Comment by Xavier | November 14, 2015 | Reply

  6. Very nice. Thanks for sharing !

    Comment by Sylvain Gantois | December 2, 2015 | Reply

  7. You should add the GetTaxonomyFieldInfo()-Method in your “Create Managed Metadata field” from Waldek. This is a crucial part of the job. Thanks nonetheless, your post sent me there🙂

    Comment by Ole Albers | January 26, 2016 | Reply

  8. Hi,

    I am getting a ‘Value does not fall with in the expected range’ error when executing the code given above for Look up field. Please help.

    Comment by Jinad | April 15, 2016 | Reply

    • Hi Jinad,
      I suppose that one of the arguments in the schemaLookupField string is not correct. This can be the ID, the name, staticname etc. Best you can do is re-verify them.
      Kind regards,
      Karine Bosch

      Comment by Karine Bosch | April 16, 2016 | Reply

  9. Thanks for sharing, this helped me a lot🙂

    Comment by Ulhas Morbale (@ulhasmorbale) | July 1, 2016 | Reply

  10. This is great article, just one thing want to add to it for Choice column is Fill In Choice FillInChoice=’TRUE’

    Comment by Ulhas Morbale (@ulhasmorbale) | July 12, 2016 | Reply

    • Thanks for the feedback! I added it to the article.
      Kind regards,
      Karine Bosch

      Comment by Karine Bosch | July 28, 2016 | Reply

  11. How to provide a default value to choice column from list of choices. From your example: set default value to “Vegetarian Menu”.

    Comment by tok2vb | October 27, 2016 | Reply

  12. Excellent article

    Comment by Dimos | November 8, 2016 | Reply


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: