C# Technical Notes

1. What is a Variable and Property (Variable vs Property)

Variables :

Variables represent storage locations. Every variable has a type that determines what values can be stored in the variable. C# is a type-safe language, and the C# compiler guarantees that values stored in variables are always of the appropriate type. The value of a variable can be changed through assignment or through use of the ++ and -- operators.

A variable must be definitely assigned (Section 5.3) before its value can be obtained.

As described in the following sections, variables are either initially assigned or initially unassigned. An initially assigned variable has a well-defined initial value and is always considered definitely assigned. An initially unassigned variable has no initial value. For an initially unassigned variable to be considered definitely assigned at a certain location, an assignment to the variable must occur in every possible execution path leading to that location.

1.1 Variable categories

C# defines seven categories of variables: static variables, instance variables, array elements, value parameters, reference parameters, output parameters, and local variables. The sections that follow describe each of these categories.

In the example

class A
{
   public static int x;
   int y;
   void F(int[] v, int a, ref int b, out int c) {
      int i = 1;
      c = a + b++;
   }
}

x is a static variable, y is an instance variable, v[0] is an array element, a is a value parameter, b is a reference parameter, c is an output parameter, and iis a local variable.

Properties :

A property is a member that provides access to a characteristic of an object or a class. Examples of properties include the length of a string, the size of a font, the caption of a window, the name of a customer, and so on. Properties are a natural extension of fields. Both are named members with associated types, and the syntax for accessing fields and properties is the same. However, unlike fields, properties do not denote storage locations. Instead, properties have accessors that specify the statements to be executed when their values are read or written.

Properties are defined with property declarations. The first part of a property declaration looks quite similar to a field declaration. The second part includes a get accessor and/or a set accessor. In the example below, the Button class defines a Caption property.

public class Button 
{
   private string caption;
   public string Caption {
      get {
         return caption;
      }
      set {
         caption = value;
         Repaint();
      }
   }
}

Properties that can be both read and written, such as Caption, include both get and set accessors. The get accessor is called when the property’s value is read; the set accessor is called when the property’s value is written. In a set accessor, the new value for the property is made available via an implicit parameter named value.

The declaration of properties is relatively straightforward, but the real value of properties is seen when they are used. For example, the Caption property can be read and written in the same way that fields can be read and written:

Button b = new Button();
b.Caption = "ABC";      // set; causes repaint
string s = b.Caption;   // get
b.Caption += "DEF";      // get & set; causes repaint

Properties combine aspects of both fields and methods. To the user of an object, a property appears to be a field, accessing the property requires exactly the same syntax. To the implementer of a class, a property is one or two code blocks, representing a get accessor and/or a set accessor. The code block for the get accessor is executed when the property is read; the code block for the set accessor is executed when the property is assigned a new value. A property without a set accessor is considered read-only. A property without a get accessor is considered write-only. A property with both accessors is read-write.

Unlike fields, properties are not classified as variables. Therefore, it is not possible to pass a property as a ref (C# Reference) or out (C# Reference)parameter.

Properties have many uses: they can validate data before allowing a change; they can transparently expose data on a class where that data is actually retrieved from some other source, such as a database; they can take an action when data is changed, such as raising an event, or changing the value of other fields.

Properties are declared within the class block by specifying the access level of the field, followed by the type of the property, followed by the name of the property, then a code block declaring a get-accessor and/or a set accessor. For example:

public class Date
{
    private int month = 7;  //"backing store"

    public int Month
    {
        get
        {
            return month;
        }
        set
        {
            if ((value > 0) && (value < 13))
            {
                month = value;
            }
        }
    }
}

In this example, Month is declared as a property so that the set accessor can make sure the Month value is set between 1 and 12. The Month property uses a private field to track the actual value. The real location of a property’s data is often referred to as the property’s “backing store.” It is common for properties to use private fields as a backing store. The field is marked private in order to make sure it can only be changed by calling the property. For more information about public and private access restrictions, see Access Modifiers (C# Programming Guide).

The body of the get accessor is similar to that of a method. It must return a value of the property type. The execution of the get accessor is equivalent to reading the value of the field. For example, when you are returning the private variable from the get accessor and optimizations are enabled, the call to the get accessor method is inlined by the compiler so there is no method-call overhead. However, a virtual get accessor method can not be inlined since the compiler does not know at compile-time which method may actually be called at run time. The following is a get accessor that returns the value of a private field name: 

class Person
{
    private string name;  // the name field
    public string Name    // the Name property
    {
        get
        {
            return name;
        }
    }
}

When you reference the property, except as the target of an assignment, the get accessor is invoked to read the value of the property. For example:

Person p1 = new Person();
//...

System.Console.Write(p1.Name);  // the get accessor is invoked here

The get accessor must terminate in a return or throw statement, and control cannot flow off the accessor body.

It is a bad programming style to change the state of the object by using the get accessor. For example, the following accessor produces the side effect of changing the state of the object each time the number field is accessed.

private int number;
public int Number
{
    get
    {
        return number++;   // Don't do this
    }
}

The get accessor can either be used to return the field value or to compute it and return it. For example:

class Employee
{
    private string name;
    public string Name
    {
        get
        {
            return name != null ? name : "NA";
        }
    }
}

In the preceding code segment, if you do not assign a value to the Name property, it will return the value NA.

The set accessor is similar to a method whose return type is void. It uses an implicit parameter called value, whose type is the type of the property. In the following example, a set accessor is added to the Name property:

class Person
{
    private string name;  // the name field
    public string Name    // the Name property
    {
        get
        {
            return name;
        }
        set
        {
            name = value;
        }
    }
}

When you assign a value to the property, the set accessor is invoked with an argument that provides the new value. For example:

Person p1 = new Person();
p1.Name = "Joe";  // the set accessor is invoked here                

System.Console.Write(p1.Name);  // the get accessor is invoked here

It is an error to use the implicit parameter name, value, for a local variable declaration in a set accessor.

Properties can be marked as publicprivateprotectedinternal, or protected internal. These access modifiers define how users of the class can access the property. The get and set accessors for the same property may have different access modifiers. For example, the get may be public to allow read-only access from outside the type, and the set may be private or protected. For more information, see Access Modifiers (C# Programming Guide).A property may be declared as a static property using the static keyword. This makes the property available to callers at any time, even if no instance of the class exists. For more information, see Static Classes and Static Class Members (C# Programming Guide).A property may be marked as a virtual property using the virtual keyword. This allows derived classes to override the property behavior using the overridekeyword. For more information about these options, see Inheritance (C# Programming Guide).A property overriding a virtual property can also be sealed, specifying that for derived classes it is no longer virtual. Lastly, a property can be declaredabstract, meaning there is no implementation in the class, and derived classes must write their own implementation. For more information about these options, see Abstract and Sealed Classes and Class Members (C# Programming Guide).

NoteNote
It is an error to use a virtual (C# Reference)abstract (C# Reference), or override (C# Reference) modifier on an accessor of a static property.

This example demonstrates instance, static, and read-only properties. It accepts the name of the employee from the keyboard, incrementsNumberOfEmployees by 1, and displays the Employee name and number.

public class Employee
{
    public static int NumberOfEmployees;
    private static int counter;
    private string name;

    // A read-write instance property:
    public string Name
    {
        get { return name; }
        set { name = value; }
    }

    // A read-only static property:
    public static int Counter
    {
        get { return counter; }
    }

    // A Constructor:
    public Employee()
    {
        // Calculate the employee's number:
        counter = ++counter + NumberOfEmployees;
    }
}

class TestEmployee
{
    static void Main()
    {
        Employee.NumberOfEmployees = 100;
        Employee e1 = new Employee();
        e1.Name = "Claude Vige";

        System.Console.WriteLine("Employee number: {0}", Employee.Counter);
        System.Console.WriteLine("Employee name: {0}", e1.Name);
    }
}
Employee number: 101Employee name: Claude Vige

This example demonstrates how to access a property in a base class that is hidden by another property with the same name in a derived class.

public class Employee
{
    private string name;
    public string Name
    {
        get { return name; }
        set { name = value; }
    }
}

public class Manager : Employee
{
    private string name;

    // Notice the use of the new modifier:
    public new string Name
    {
        get { return name; }
        set { name = value + ", Manager"; }
    }
}

class TestHiding
{
    static void Main()
    {
        Manager m1 = new Manager();

        // Derived class property.
        m1.Name = "John";

        // Base class property.
        ((Employee)m1).Name = "Mary";

        System.Console.WriteLine("Name in the derived class is: {0}", m1.Name);
        System.Console.WriteLine("Name in the base class is: {0}", ((Employee)m1).Name);
    }
}
Name in the derived class is: John, ManagerName in the base class is: Mary
The following are important points in the preceding example:

  • The property Name in the derived class hides the property Name in the base class. In such a case, the new modifier is used in the declaration of the property in the derived class:
    public new string Name
  • The cast (Employee) is used to access the hidden property in the base class:
    ((Employee)m1).Name = "Mary";

    For more information on hiding members, see the new Modifier (C# Reference).

In this example, two classes, Cube and Square, implement an abstract class, Shape, and override its abstract Area property. Note the use of theoverride modifier on the properties. The program accepts the side as an input and calculates the areas for the square and cube. It also accepts the area as an input and calculates the corresponding side for the square and cube.

abstract class Shape
{
    public abstract double Area
    {
        get;
        set;
    }
}

class Square : Shape
{
    public double side;

    public Square(double s)  //constructor
    {
        side = s;
    }

    public override double Area
    {
        get
        {
            return side * side;
        }
        set
        {
            side = System.Math.Sqrt(value);
        }
    }
}

class Cube : Shape
{
    public double side;

    public Cube(double s)
    {
        side = s;
    }

    public override double Area
    {
        get
        {
            return 6 * side * side;
        }
        set
        {
            side = System.Math.Sqrt(value / 6);
        }
    }
}

class TestShapes
{
    static void Main()
    {
        // Input the side:
        System.Console.Write("Enter the side: ");
        double side = double.Parse(System.Console.ReadLine());

        // Compute the areas:
        Square s = new Square(side);
        Cube c = new Cube(side);

        // Display the results:
        System.Console.WriteLine("Area of the square = {0:F2}", s.Area);
        System.Console.WriteLine("Area of the cube = {0:F2}", c.Area);
        System.Console.WriteLine();

        // Input the area:
        System.Console.Write("Enter the area: ");
        double area = double.Parse(System.Console.ReadLine());

        // Compute the sides:
        s.Area = area;
        c.Area = area;

        // Display the results:
        System.Console.WriteLine("Side of the square = {0:F2}", s.side);
        System.Console.WriteLine("Side of the cube = {0:F2}", c.side);
    }
}

Input

4
24
Enter the side: 4Area of the square = 16.00Area of the cube = 96.00Enter the area: 24

Side of the square = 4.90

Side of the cube = 2.00

C# – Object Versus Var Versus Dynamic

Please refer to the article http://www.c-sharpcorner.com/UploadFile/013102/C-Sharp-object-versus-var-versus-dynamic/

Object Oriented Programming Using C#

Before reading this article, please go through the following articles:

  1. Object Oriented Programming Using C#: Part 1
  2. Object Oriented Programming Using C#: Part 2
  3. Object Oriented Programming Using C#: Part 3
  4. Object Oriented Programming Using C#: Part 4
  5. Object Oriented Programming Using C#: Part 5
  6. Object Oriented Programming Using C#: Part 6
  7. Object Oriented Programming Using C#: Part 7
  8. Object Oriented Programming Using C#: Part 8
  9. Object Oriented Programming Using C#: Part 9

  10. Object Oriented Programming Using C#:Part 10

Introducing SharePoint Apps in Sharepoint 2013

I have been fortunate in that I was hired by Microsoft early in the lifecycle of SharePoint 2013 to write training material for developers and architects. At this point I have been designing, writing and thinking about SharePoint apps for a little over a year. I would like to share what I have learned and show the evolution of my thoughts by writing a series of blog post on the new SharePoint app model.

Let’s begin with a bit of history. SharePoint 2007 represents the first version of SharePoint technologies where Microsoft invested to create a true development platform by introducing features and farm solutions. Next came SharePoint 2010 where Microsoft extended the options available to developers by introducing sandboxed solution deployment as an alternative to farm solution deployment. With SharePoint 2013, Microsoft has now added a third option for SharePoint developer with the introduction of SharePoint apps.

When developing for SharePoint 2013, you must learn how to decide between using a farm solution, a sandboxed solution or a SharePoint app. First, you should learn what’s different about developing SharePoint apps. As you will see, SharePoint app development has several important strengths and a few noteworthy constraints when compared to the “old school” approach of developing solution as we have been doing for SharePoint 2010.

As you begin to get your head around what the new SharePoint app model is all about, it’s helpful to understand one of Microsoft’s key motivations behind it. SharePoint 2007 and SharePoint 2010 have gained large-scale adoption world-wide and have generated billions of dollars in revenue primarily due to companies and organization who have installed SharePoint on their own hardware using an on-premises deployment model. And while previous versions of SharePoint have been very successful products with respect to all these on-prem deployments, Microsoft’s success and adoption rate in hosted environments such as Office 365 have been far more modest.

The release of SharePoint 2013 represents a significant shift in Microsoft’s strategy for evolving the product. Microsoft’s focus is now concerned with improving how SharePoint works in the cloud and especially with Office 365. Microsoft’s investment in SharePoint 2013 has mainly been to add features and functionality that works equally well in the cloud as they do in on-prem deployments. You will find that SharePoint 2013 doesn’t add much new functionality for on-prem deployments that does not also work in the cloud.

Why SharePoint Apps?

The development model for SharePoint apps is quite different when you compare it to how we develop farms solutions and sandboxed solutions. I am going to create a series of blog posts based on following list to summarize the key differences you’ll find as you migrate from developing SharePoint solutions to developing SharePoint apps.

Once you have gained a solid understanding of these key points you will have a better appreciation for why Microsoft has introduced the new SharePoint app model. You will also have the proper perspective for selecting between a SharePoint solution and a SharePoint app when its time to start a new SharePoint development project. What you will find is that there are many scenarios where going with the new SharePoint app model will make much more sense. You will also find that there will still be plenty of scenarios which do not provide a fit for the SharePoint app model where it will make far more sense to go with a SharePoint solution.

I hope you enjoy this series of blog posts and find them useful in your journey as a SharePoint developer.

Get the custom code out of SharePoint

The server-side code you write for a SharePoint solution runs inside the SharePoint environment. For example, managed code deployed in a farm solution runs inside the main SharePoint worker process (w3wp.exe). Managed code deployed using a sandboxed solution runs inside the SharePoint sandbox worker process (SPUCWorkerProcess.exe). However, The SharePoint app model mandates that code from an app cannot run inside any process that is launched or managed by SharePoint.

There are a few simple reasons why Microsoft wants to get rid of custom code that runs inside the SharePoint environment. The first reason has to do with increasing the stability of SharePoint farms. The one is pretty obvious. Getting rid of any type of custom code running inside the SharePoint environment results in lower risk, fewer problems and greater stability for the hosting farm.

The second reason has to do with a company’s ability to upgrade to newer versions of SharePoint. The underlying problem is that SharePoint solutions which contain code that programs against the SharePoint server-side object model have been notorious at creating migration problems when a company is upgrading from one version of SharePoint to the next. More to the point, Microsoft has witnessed many of their biggest SharePoint customers postponing the upgrade of their production farm for months and sometimes years until they have had time to update and test all their SharePoint solutions on the new version of SharePoint. Since this problem negatively affects SharePoint sales revenue, you can bet it was pretty high on the fix-it priority list when Microsoft began to design SharePoint 2013.

Your custom code has to run somewhere

When you develop a SharePoint app you obviously need to write custom code to implement your business logic. It is also clear that app’s code must run some place other than the Web servers in the hosting SharePoint farm. The SharePoint app model gives you two places to run your custom code. First, a SharePoint app can contain client-side code which runs inside the browser on the user’s machine. Secondly, a SharePoint app can contain server-side code that runs in an external website that is implemented and deployed as part of the app itself.

There are many different ways in which you can design and implement a SharePoint app. For example, you could create SharePoint app that contains only client-side resources such as web pages and client-side JavaScript code which are served up by the SharePoint host. This type of app is known as a SharePoint-hosted app because it doesn’t require its own external website. If it’s late at night when there’s nobody around and your feeling a bit naughty, you could even write a SharePoint-hosted app that uses Silverlight code instead of JavaScript code to implement its client-side business logic.

Now imagine you want to create a second SharePoint app in which you want to write server-side code in a language such as C#. This type of SharePoint app will require its own external website so that your server-side code has a place to execute outside the SharePoint environment. In the new SharePoint 2013 terminology, a SharePoint app with its own external website is known as a Cloud-hosted app. The following diagram shows the key architectural difference between a SharePoint-hosted app and a cloud-hosted app.

HostingApps

From this diagram you can see that both SharePoint-hosted apps and cloud-hosted apps have a start page that represents the app’s primary entry point. With a SharePoint-hosted app, the app’s start page is served up by the SharePoint host. However, with a cloud-hosted app the start page is served up from the external website. Therefore, SharePoint must track the external URL for each cloud-hosted app that has been installed so that it can redirect users to the app’s start page. The SharePoint infrastructure creates a client-side JavaScript component known as a launcher which is used to actually redirect the user from the SharePoint host over to the external app.

When you decide to develop a cloud-hosted SharePoint app, you must take on the responsibility hosting the app’s external website. However, this responsibility of creating and deploying an external website along with a SharePoint app also comes with a degree of flexibility. You can implement the external website for a SharePoint app using any existing Web-based development platform.

For example, the external website for a cloud-hosted SharePoint app could be implemented using a non-Microsoft platform such as Java, LAMP or PHP. However, the easiest and the most common approach for SharePoint developers will be to design and implement the external website for cloud-hosted apps using Visual Studio 2012 and the ASP.NET Framework.

Let’s look at an example. Imagine you would like to develop a cloud-hosted SharePoint app. Visual Studio 2012 and the new SharePoint Tools provide you with a new project template for SharePoint apps development that quickly create the starting point you need for creating a cloud-hosted SharePoint app. This starting point is a Visual Studio solution which contains two separate projects as shown in the following screenshot.

Cloud-hosted App Projects

The first Visual Studio project in this example is named MyCloudHostedApp. This is the SharePoint app project that creates the distributable installation file named MyCloudHostedApp.app that gets installed inside a SharePoint host. As you can see from the screenshot, this project contains an important XML file named AppManifest.xml which tracks the app’s metadata that is used by SharePoint when the app is installed. The project also contains an image file named AppIcon.png that is used to add a custom icon to the page in SharePoint with the launcher that the user clicks on to navigate to the start page of the app.

The second project named MyCloudHostedAppWeb is used to develop the ASP.NET Web Application that will serve as an implementation of the cloud-hosted app’s external website. Note that Visual Studio uses the naming convention of adding “Web” to the end of the name of the first project to create the name for the second project. Therefore, the project for the SharePoint app is named MyCloudHostedApp and the project for the external website is named MyCloudHostedAppWeb. You will also find that a SharePoint app project such as MyCloudHostedApp has a project property named Web Project which can be used to reference the external website project which allows Visual Studio to recognize these two projects are used together to develop single cloud-hosted app.

From the screenshot above, you can see that the MyCloudHostedAppWeb project contains a page named default.aspx which is located inside a folder named Pages. This page will be used as the app’s start page. Now let’s examine the AppManifest.xml file in the SharePoint app project to see how the app’s metadata is configured to use default.aspx as its start page.

AppManifest

Note that the app manifest contains a top-level App element with an inner Properties element. Within the Properties element are two required elements named Title and StartPage. The Title element contains human-readable text that is displayed along with the launcher. TheStartPage element contains the URL that SharePoint uses in the launcher to redirect the user to the start page in the external website. When an app is deployed into production, the StartPage element will contain the full path to the start page on the Internet.

https://appserver.wintip.com/MyCloudHostedAppWeb/Pages/Default.aspx

When you are developing a cloud-hosted app, Visual Studio provides a convenient dynamic token named ~remoteAppUrl which eliminates your need to hardcode the path to the external website during the development phase. For example, Visual Studio created the StartPageelement with the following value.

~remoteAppUrl/Pages/Default.aspx?{StandardTokens}

The reason this works is that the SharePoint app project named MyCloudHostedApp has a Web Project property which associates it with the external website project named MyCloudHostedAppWeb. Whenever you deploy or debug your solution, Visual Studio will perform a substitution to replace ~remoteAppUrl with the current URL of the Web Project. Note that the ~remoteAppUrl token will always be replaced by Visual Studio before the app manifest is installed into a SharePoint host. Therefore, SharePoint really sees a value for the StartPageelement that looks like this.

https://localhost:44300/Pages/Default.aspx?{StandardTokens}

Note that the value of the StartPage element in this example contains a second dynamic token named {StandardTokens}. This token is different that the ~remoteAppUrl token because it is not replaced by Visual Studio. Instead, this dynamic token remains inside the app manifest after it has been installed into a SharePoint host. It is the SharePoint infrastructure and not Visual Studio that performs the substitution on this token. Whenever SharePoint uses this StartPage element to create the URL for a launcher, it replaces {StandardTokens} with a standard set of query string parameters used in SharePoint app development such as SPHostUrl and SPLangauge.

default.aspx?SPHostUrl=http%3A%2F%2Fwingtipserver&SPLanguage=en%2DUS

When you implement the code behind the start page of a SharePoint app, you can generally expect that the page is passed these two query string parameters named SPHostUrl and SPLanguage which you can use to determine the language in use and the URL back to the site in the SharePoint host. In quite a few scenarios, SharePoint will add additional query string parameters beyond these two.

What’s nice about developing a cloud-hosted app using this type of Visual Studio solution is that you can develop and debug both projects at the same time within a single session of Visual Studio 2012. This approach will be appealing to experienced .NET developers because it allows them to write the app’s server-side code using C# or VB.NET using the latest and greatest version of the .NET Framework (version 4.5). You can also leverage the libraries of the .NET Framework and benefit from essential Visual Studio support for debugging and IntelliSense. Moreover, the code runs outside of the SharePoint environment so you avoid many of the frustrating limitations and idiosyncratic SharePoint-isms that SharePoint developers have had to deal with over the years. Compare this to writing C# code for a sandboxed solution that has to deal with frustrating limitations of the SharePoint 2010 sandbox. Now that’s a good reason to get excited about developing SharePoint apps.

Using an ASP.NET application to implement the external website also provides flexibility in deployment. When deploying a cloud-hosted SharePoint app within a private network, you can host the external website on a local Web server running within the same LAN as the hosting SharePoint farm. For other scenarios that require scaling and/or accessibility from anywhere on the Internet, you can deploy the ASP.NET application in the cloud using Windows Azure Services.

A tale of three app hosting models

When you create your first SharePoint app in Visual Studio 2012, you will not see a specific option to create a cloud-hosted app. Instead, Visual Studio gives you three options for selecting the app’s hosting model. The three options you get are AutohostedProvider-hosted andSharePoint-hosted as shown in the following screenshot.

CreateNewSharePointApp

At a high-level, Autohosted apps and Provider-hosted apps are just two different variations of a cloud-hosted app. Everything I have explained in this blog post about cloud-hosted apps applies equally well to both Autohosted apps and Provider-hosted apps. So then you ask, “what’s the difference between the two?” I will first explain what an Provider-hosted app is and then I will finish by discussing the value of an Autohosted app. However, I will keep this discussion at a fairly high level and wait until later in the series to drill down into more detail.

When you decide to create a Provider-hosted app, then you will ultimately be responsible for deploying the external website and making it accessible on the Internet or on a private network. As I mentioned earlier, you have the option of deploying this external website on a local Web server or up in the cloud using Windows Azure services. What is important to see is that the external website must be deployed and made accessible to the users who will access it before you begin to install the SharePoint app that relies on this external website.

The Autohosted app can provide a better strategy for deploying the external website associated with a cloud-hosted app. The main idea is that an Autohosted app calls upon infrastructure built into Office 365 that can automatically deploy the external website when the app is installed. Note that this approach will only work in the Office 365 environment and cannot be used in scenarios in which SharePoint apps are installed within an on-prem farm.

The automated deployment model provided by Autohosted apps relies on a special implementation which integrates Windows Azure Services together with the Office 365 environment. Inside the installation file for an Autohosted app, there is extra metadata and all the ASP.NET application source files required to spin up a Web Site in Windows Azure Services in order to deploy the external website. An Autohosted app can even go one step further by allowing you to automate the creation of a SQL Azure database as part of the app installation process. There are a ton of details you need to know to make it all work, but here I just wanted to explain things at a high level so you can understand that both Provider-hosted apps and Autohosted apps are really just cloud-hosted apps that mainly differ in how their external website gets deployed.

Conclusion

So now you understand one of the key points of the SharePoint app model. Custom code never runs inside SharePoint. It runs somewhere else. You have the option of writing both client-side code and server-side code. A SharePoint-hosted app is easier to create, implement and deploy. However, it does not provide the opportunity to add server-side code. A cloud-hosted app will yield more power because you can write as much server-side code as you would like using a managed language such as C# and your code is not limited by all those frustrating limitations and issues created by running code inside the SharePoint environment. In my next post, I will dive into the details about how the SharePoint infrastructure is able to isolate SharePoint apps with respect to request processing and storing app-specific content within a SharePoint content database.

If you haven’t read the first post in the series on why SharePoint app code cannot run inside the SharePoint environment, you should consider reading it first before continuing with this post. The first post explains the basic architecture and the differences between SharePoint-hosted apps and cloud-hosted apps. This post assumes you already understanding these differences.

SharePoint apps can create pages and lists in isolated storage

Each time you install a SharePoint app, you must install it into a specific target site. If the target site is a standard site, the SharePoint app is installed at site scope. If you install a SharePoint app in a special type of site known as a catalog site, then the app is installed a tenancy scope. Installing an app at tenancy scope is valuable because a single instance of an app can be configured for use across all site collections and sites inside a tenancy.

A SharePoint app has the capability to add its own files to the SharePoint host during installation. For example, a SharePoint-hosted app will typically add a start page, a CSS file and a JavaScript file to implement the app’s user experience. The SharePoint host stores these files in the standard fashion by adding them to the content database associated with the target install site. Beyond basic pages, a SharePoint app also has the ability to create other SharePoint-specific site elements in the SharePoint host during installation such as lists and document libraries.

Let’s look at an example. Imagine you want to create a simple SharePoint app to manage customers. During installation, the app can be designed to create a customer list using the standard Contacts list type along with a set of pages designed to provide a snazzy user experience for adding and finding customers. Your app could additionally be designed to create a document library upon installation so that the app can store customer contracts as Word documents where each Word document would reference a specific customer item in the customers list.

So where does the SharePoint host store the content added by an app during installation? The answer is inside a special child site that the SharePoint host creates under the host site where the app is being installed. This child site is known as the app web. A simple example of a host site and the app web created during a site-scoped installation is shown in the following diagram.

The app web is an essential part of the SharePoint app model because it represents the isolated storage that is owned by an installed instance of a SharePoint app. The app web provides a scope for app’s private implementation details. Note that an app by default has full permissions to read and write content inside its own app web. However, an app has no other default permissions to access content from any other location in the SharePoint host. The app web is the only place an app can access content without requesting permissions that then must be granted by a user.

There is an important aspect of the SharePoint app model that deals with uninstalling an app and ensuring that all the app-specific storage is deleted automatically. In particular, a SharePoint host will automatically delete the app web for an app whenever the app is uninstalled. This provides a set of cleanup semantics for SharePoint apps that is entirely missing from the development model for SharePoint solutions. When an app is uninstalled, it doesn’t leave a bunch of junk behind. I wish I could same the same thing for all the SharePoint solutions I have created over the years.

You should understand that the installation of a SharePoint app doesn’t always result in the creation of an app web. Some apps are designed to create an app web during installation and some are not. A SharePoint-hosted app is the type of app that will always create an app web during installation. This is a requirement because a SharePoint-hosted app requires a start page that must be added to the app web.

However, things are different with a cloud-hosted app. Since a cloud-hosted app has a start page that is served up from an external website, it does not require the creation of an app web during installation. Therefore, the use of an app web in the design of a cloud-hosted app is really just an available option as opposed to a requirement as it is with a SharePoint-hosted app.

When you design a cloud-hosted app, you have a choice whether you want to create an app web during installation to store private app implementation details inside the SharePoint host. Some cloud-hosted apps will store all the content they need within their own external database and will not need to create an app web during installation. Other cloud-hosted apps can be designed to create an app web during installation in scenarios where it makes sense to store content within the SharePoint host for each installed instance of the app.

The app package and the inner solution package

A SharePoint app is packaged up for deployment using a distributable file known as an app package. An app package is a ZIP file with a .appextension. If you create a new SharePoint app project named MyFirstApp, the project will generate a app package named MyFirstApp.appas its output. Note that the file format for creating an app package is based on the Open Package Convention (OPC) format. This is the same file format that Microsoft Office begin to use with the release of Office 2007 for creating Word documents (docx) and Excel workbooks (xslx).

The primary requirement for an app package is that it contains a top-level file named AppManifest.xml which contains essential metadata for app. The SharePoint host relies on properties it discovers inside AppManifest.xml so that it can properly install, track and launch a SharePoint app. Here’s an example of the AppManifest.xml file used by a SharePoint-hosted app which contains standard app properties such as Name,ProductIDVersionTitle and StartPage.

In addition to the AppManifest.xml file, the app package often contains additional files that are used as part of the app’s implementation. For example, the app package for a SharePoint-hosted app contains a file for the app’s start page along with other resources used by the start page such as a CSS file and a JavaScript file. These are example of files that are added to the app web as part of the app installation process.

The distribution mechanism used by a SharePoint app to add pages and lists to the app web during installation is a standard solution package. Does this sound familiar? Yes, it a CAB file with a .wsp extension. It sounds familiar because the solution package file used by a SharePoint app has the exact same file format as the solution package files which we have been using to deploy SharePoint solutions in SharePoint 2007 and SharePoint 2010. The one key difference is that the solution package used by a SharePoint app is embedded as a .wsp file inside the app package as shown in the following diagram.

When a user installs a SharePoint app, the SharePoint host examines the app package to see if it contains an inner solution package. It is the presence of an inner solution package inside the app package file that tells the SharePoint host whether it needs to create an app web during installation. If the app package does not contains an inner solution package, the SharePoint host installs the app without creating an app web.

The inner solution package for a SharePoint app should contain a single Web-scoped feature. The SharePoint host activates this feature automatically on the app web immediately after the app web is created. This features is what makes it possible to add declarative elements such as pages and lists as the app is installed. However, the inner solution package for a SharePoint app cannot contain any type of DLL or any .NET code whatsoever. Therefore, you can say that the inner solution package is constrained because it must be a fully declarative solution package. This is different than the solution packages for farm solutions and sandboxed solutions which can contain DLL assemblies with custom .NET code written in either C# or VB.NET.

Processing page requests from the app web

Next, let’s turn our attention to the start page for a SharePoint-hosted app. As you have seen, the start page for a SharePoint-hosted app is added to the app web during installation. Now imagine a scenario where you have installed a SharePoint app with the name of MyFirstApp in a team site which is accessible through the following URL.

https://intranet.wingtip.com.

During app installation, the SharePoint host creates the app web as a child site under the target host site. The SharePoint host creates a relative URL for the app web based on the app’s Name property. Therefore, in our example the app web is created with a relative path of MyFirstApp. If the app’s start page named default.aspx is located in the app web inside the Pages folder, then the relative path to the start page isMyFirstApp/Pages/default.aspx. Now your intuition might be telling you that the app’s start page will be accessible through an URL that combines the base URL to the host site together with the relative path to the start page.

https://intranet.wingtip.com/MyFirstApp/Pages/default.aspx

However, this is not the case. The SharePoint host does not make the app web nor any of its pages accessible through the same domain as the host site. Instead, the SharePoint host creates a new unique domain on the fly each time time it creates a new app web as part of the app installation process. This allows the SharePoint host to isolate all the pages from an app web in its own private domain. The start page for a SharePoint-hosted app will then be made accessible through an URL that looks like this.

https://wingtiptenantee060af276f95a.apps.wingtip.com/MyFirstApp/Pages/Default.aspx

If you look back at the AppManifest.xml file shown earlier, you notice that it did not include a hard-coded path to the app’s start page. Instead, the URL to the start page contains a dynamic token named ~appWebUrl. This dynamic token is replaced by the SharePoint host when the app is installed. This makes sense because the URL that will be used to access the app web is not even known until the SharePoint host creates a new domain for the app during installation. After creating the app web, the SharePoint host can then use it to create the URL to the start page.

So why doesn’t the SharePoint host serve up pages from the app web using the same domain as the host site? At first, the reasons why the SharePoint host serves up the pages from an app web in their own isolated domain might not be obvious. There are two primary reasons why the SharePoint app model does this. Both of these reasons are related to security and the management and enforcement of permissions granted to an app.

The first reason for isolating an app web in its own private domain has to do with preventing direct JavaScript calls from pages in the app web back to the host site. This security protection of the SharePoint app model builds on the browser’s built-in support for prohibiting cross-site scripting (XSS). Since JavaScript code running on pages from an app web pages originates from a different domain, this code cannot directly call back to the host site. More specifically, calls from JavaScript running on app web pages do not run with the same identity nor the same permissions as JavaScript code behind pages in the host site.

The second reason for creating an isolated domain for each app web has to do with page processing and JavaScript callbacks that occur on the server. The SharePoint host creates a new unique domain for each app that it installs. This in turn allows the SharePoint host to determine exactly which app is calling when it sees an incoming request from a page in an app web. They key point is that the SharePoint host is able to authenticate the SharePoint app and examine its permissions any time a call originates from the domain of an app web. As you remember from earlier, an app has default permissions to access its app web but it has no default permissions anywhere else in the SharePoint host. The ability for the SharePoint host to authenticate calls from apps using the isolated app web domain is essential to enforcing this default permissions scheme.

This is huge. The idea that SharePoint 2013 introduces new authentication support for apps in addition to its existing authentication support for users is a significant part of the SharePoint app model. In effect. this is what allows SharePoint apps to become a first class security principals. This alone gives the new SharePoint app model many advantages over SharePoint solutions development. In this post I am going to keep the discussion authentication with SharePoint apps brief. I am going to create another blog post later in this series that will go into much greater detail about how, when and why SharePoint apps are authenticated.

Configuring your local on-prem farm for deploying and developing apps

If you have acquired a new beta test site in Office 365, you have an environment that has already been configured to deploy and run SharePoint apps. Everything is all set to go. However, what if you want to build out a local farm with SharePoint 2013 on your development machine so you can deploy and develop SharePoint apps locally? If you want to do this (and I recommend you do), then you must perform a few extra tasks after installation to properly configure the environment for developing SharePoint apps. This can all be done using Windows PowerShell and I will conclude this post by walking you though the steps required.

Remember that the new SharePoint app model was really designed for Office 365. Therefore, the environment for running SharePoint apps must be configured at tenancy level. The idea of tenancy-level configuration makes a great deal of sense in Office 365. However, the concept of creating and configuring tenancies in an on-prem farm can be far more confusing.

First things first. To run SharePoint apps locally you need to create an instance of a new SharePoint 2013 service application named the App Management Service Application. This step is an easy one because you can create the required instance of the App Management Service Application using the Farm Wizard right after you have created a new SharePoint 2013 farm.

Next, you need to use PowerShell to configure the root domain name for app webs. This can be done by calling a new PowerShell cmdlet namedSet-SPAppDomain and passing a base URL that the SharePoint host will use to create a new domain each time it create a new app web during app installation. For example, you can configure the root domain for app webs to be something such as apps.wingtip.com.

# assign base domain name to configure URL used to access app webs
Set-SPAppDomain "apps.wingtip.com" –confirm:$false

Next, you have to ensure that you have an instance of the Microsoft SharePoint Foundation Subscription Settings Service Application. However, this is a bit more tricky because you cannot create a new instance of this service application using the farm wizard. Nor can you create a new instance of this service application by hand in Central Administration. Instead, you have to use PowerShell. At the end of this post, I have included a complete script that does all the work for you.

Now let’s discuss the importance of creating an instance of the Subscription Settings Service Application in an on-prem farm. The Subscription Settings Service is what SharePoint uses to create and manage tenancies. Without this service, the local farm has no tenancies which means you cannot install or run SharePoint apps. However, when you create new an instance of the Subscription Settings Service Application in an on-prem farm, the service automatically creates a default tenancy. This default tenancy automatically includes all the sites and site collections in the local farm.

The important point is that you do not need to explicitly create tenancies within an on-prem farm. Instead, you simply need to create an instance of the Subscription Settings Service Application and you let it create the default tenant. After creating an instance of the Subscription Settings Service Application, you can complete the configuration for local SharePoint app development by running the following PowerShell cmdlet named to Set-SPAppSiteSubscriptionName to configure a name for the default tenant.

# assign name to default tenant to configure URL used to access app web
Set-SPAppSiteSubscriptionName -Name "WingtipTenant"

Now you know how to configure your development workstation with PowerShell so that you can begin developing apps where the testing and debugging is conducted in local sites. You should also keep I mind that the introduction of SharePoint apps places new requirements on IT Pros and developers alike to configure DNS to ensure that the domain name of a newly created app points back to the web server of the SharePoint host. Visual Studio 2012 provides assistance during development by automatically updating the local LMHOST file to configure the domain name for apps during debugging. However, you should also learn how to use wildcards in DNS so you can redirect any domain beginning with apps.wingtip.com using a single DNS entry.

I will conclude with a complete listing of a Windows PowerShell script that can be used to configure a local farm to allow for SharePoint app development. Remember that this script assumes that you have already run the farm wizard and used it to create an instance of the App Management Service Application. This script also assume that the farm wizard has created a service application pool named SharePoint Web Services Default which will be used as the service application pool with the new service. My hope is that you can copy and paste the PowerShell code in this script and just make minor adjustments to get things up and running. Note I have added a few line breaks to make things more readable online in this post but you will have to remove them before running this script.

Add-PSSnapin Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue
cls

# assign root domain name to configure URL used to access app webs
Set-SPAppDomain "apps.wingtip.com" –confirm:$false 

# Start SPSubscriptionSettingsService and wait for it to start
Write-Host "Ensure Subscription Settings Service is running" 

$service = Get-SPServiceInstance |
               where{$_.GetType().Name -eq "SPSubscriptionSettingsServiceInstance"} 

if($service.Status -ne "Online") { 
    Write-Host "Starting subscription service" 
    Start-SPServiceInstance $service 
} 

# wait for subscription service to start" 
while ($service.Status -ne "Online") {
  # delay 5 seconds then check to see if service has started   sleep 5
  $service = Get-SPServiceInstance | 
                  where{ $_.GetType().Name -eq "SPSubscriptionSettingsServiceInstance" }
} 

# create an instance Subscription Service Application and proxy if they do not exist 
if($serviceApp -eq $null) { 
  Write-Host "Subscription Service Application does not exist, time to create it" 
  $pool = Get-SPServiceApplicationPool "SharePoint Web Services Default" 
  $serviceAppName = "Setting Service Applicaton" 
  $serviceAppDbName = "Setting_Service_" + [System.Guid]::NewGuid().toString() 
  $serviceApp = New-SPSubscriptionSettingsServiceApplication # [remove line break] 
                                      -ApplicationPool $pool # [remove line break]
                                      -Name $serviceAppName  # [remove line break] 
                                      -DatabaseName $ServiceAppDbName 

  $serviceAppProxy = New-SPSubscriptionSettingsServiceApplicationProxy # [remove line break]
                                                   -ServiceApplication $serviceApp

  Write-Host "Instance of the Subscription Service has been created"
}

# assign name to default tenant to configure URL used to access web apps 
Set-SPAppSiteSubscriptionName -Name "WingtipTenant" -Confirm:$false

If you haven’t read the previous posts in the series, you should consider reading them before continuing with this post. These earlier posts explain the basic architecture and the differences between SharePoint-hosted apps and cloud-hosted apps and discuss the role of the app web. This post assumes you already understand these concepts.

Getting Started with CSOM and the REST API

SharePoint apps cannot run any server-side code inside the SharePoint host environment. Therefore, they cannot use the SharePoint server-side object model. Instead, a SharePoint app must call from across the network to communicate with the SharePoint host environment. The two options that you have to accomplish this are using the client-side object model (CSOM) and issuing Web service calls based on the new SharePoint 2013 REST API.

As you recall, a SharePoint app can contain two fundamental types of code. First, a SharePoint app can contain client-side code that runs in the browser which is most often written in JavaScript. Secondly, a SharePoint app can contain server-side code that runs in the remote web associated with the app. In this post I will demonstrate writing this type of server-side code in C# although you can alternatively write it in VB or a plethora of other languages as well.

When you are designing a SharePoint app that must communicate with the SharePoint host environment, you must make two choices. First, you must decide whether to use client-side code or server-side code. Second, you must decide between CSOM and the REST API. This means there are four permutations for writing code in a SharePoint app that programs against a SharePoint site.

  1. Client-side JavaScript that uses CSOM
  2. Client-side JavaScript that uses the REST API
  3. Server-side C# code that uses CSOM
  4. Server-side C# code that uses the REST API

As you begin to consider whether to use CSOM or the REST API, you’ll find that there is a good deal of overlap between them. Therefore, you will encounter scenarios where you could choose either one to accomplish the same goal. As a basic rule of thumb when getting started, you will find that CSOM is easier to use when programming in a managed language such as C#. You might also find that the REST API is easier to use when writing client-side JavaScript code especially when you are using today’s most popular JavaScript libraries such as jQuery. However, there are still occasions where it is beneficial or necessary to write client-side code using CSOM or server-side code against the REST API.

My goal in writing this blog post is to get you started programming with each of these four programming styles listed above. However, I don’t want to introduce too many topics at once so I will attempt to introduce the important concepts of CSOM and the REST API in isolation from other related topics. In this post I will avoid any detailed discussion of app authentication or app permissions. While these topics are essential in SharePoint app development, I think it’s best to defer introducing them until later blog posts in this series.

In this post I will demonstrate using CSOM and the REST API by programming against the app web associated with a SharePoint app. My reason for doing this is that a SharePoint app by default has full permissions on its app web. Therefore, this scenario eliminates the need to deal with explicit app permission requests. I will revisit this topic in a later post in this series and provide you with the details you need to program against the host web which will require you to modify an app with explicit permission requests.

When I discuss writing server-side code in a cloud-hosted app in this post, I will concentrate on a scenario which involves internal authentication instead of external authentication. A scenario which involves internal authentication doesn’t require explicit code to manage authentication. This will allow me to focus exclusively on the fundamentals of using CSOM and the REST API. In the next blog post in this series, I will center the discussion on app authentication and we will take a dive deep into the differences between how app authentication works in the Office 365 environment versus an on-premises farm.

I have complimented this blog post with a few sample projects I have written with the Visual Studio 2012 Release Candidate. The download is named TheCsomRestPartyPack.zip and it can be downloaded from here in the members page of the Critical Path Training website. If you are not already a member, you can sign up by supplying your email address.

Writing Client-side JavaScript using CSOM

It’s pretty easy to get started with programming client-side JavaScript using CSOM. That’s because all the code you need to get up and running is automatically added by Visual Studio 2012 and the SharePoint Tools when you create a new SharePoint-hosted app. Note that when you create a new SharePoint-hosted app project, Visual Studio also adds the JavaScript source file and required links for the jQuery core library. If you are beginning to develop SharePoint apps and you haven’t yet become familiar with jQuery, now is the time to pick up a jQuery book or to work through some of the tutorials you can find at jQuery.com.

Now imagine you have just created your first SharePoint-hosted app project in Visual Studio 2012. Let’s start off by examining the small bit of JavaScript code that Visual Studio 2012 adds into the app’s start page named default.aspx.

$(document).ready(function () {
  SP.SOD.executeFunc('sp.js', 'SP.ClientContext', function () { sharePointReady(); });
});

This code uses the jQuery document ready event handler and an anonymous function to trigger its execution just after the browser has finished loading the DOM and the elements of the page are ready to access. Inside the anonymous function, there is a single line of code that calls to a JavaScript function supplied by SharePoint Foundation named SP.SOD.executeFunc.

It’s important that you understand why the call to SP.SOD.executeFunc is necessary. It has to do with forcing the download of an essential JavaScript source file named sp.js. While the standard SharePoint master pages link to this JavaScript source file and several others, they are not linked in such a way that they are guaranteed to be downloaded and available for use in the browser before the page is displayed to the user. Instead, they are linked using a script-on-demand (SOD) mechanism.

The benefit of SOD to the user is that pages are displayed faster. More specifically, the user isn’t required to wait until a bunch of JavaScript code downloads from across the network before seeing a page. The issue caused by SOD for a developer like yourself is that you must supply code to force the download of specific JavaScript source files such as sp.js before you can call the functions they contain. The file named sp.js is particularly important because it contains the core functions of CSOM.

If we examine the parameters passed in the call to SP.SOD.executeFunc, you can see the first two parameters pass the name of thesp.js source file and a JavaScript function inside that source file named SP.ClientContext.

SP.SOD.executeFunc('sp.js', 'SP.ClientContext', function () { sharePointReady(); });

When you call SP.SOD.executeFunc, the method’s implementation downloads sp.js and then executes a function inside it namedSP.ClientContext. The execution of this function initializes the client context which represents the heart and soul of the CSOM programming model. After that, the method’s implementation executes whatever function that has been passed as the third parameter. The code supplied by Visual Studio provides an anonymous function that executes a function named sharePointReady. You can rewrite this code to simplify it and clean it up a bit to provide the generic starting point for any client-side code that uses CSOM.

$(function () {
  SP.SOD.executeFunc('sp.js', 'SP.ClientContext', sharePointReady );
});

function sharePointReady() {
  // code added here can begin to use CSOM
}

The important thing to observe here is that there is a pattern where you force the download of sp.js and then call a custom function where it is safe to use CSOM. If you use the code supplied by Visual Studio, the function where you can begin using CSOM is namedsharePointReady. Now let’s look at a longer code listing where the sharePointReady method is implemented to retrieve the Titleproperty of the app web using CSOM.

$(function () {
  SP.SOD.executeFunc('sp.js', 'SP.ClientContext', sharePointReady);
});

// create page-level variables to hold client context and web
var context;
var web;

function sharePointReady() {

  // assign values to page-level variables
  context = new SP.ClientContext.get_current();
  web = context.get_web();

  // provide CSOM with instructions to load info about current web
  context.load(web);

  // issue asynchronous call across network for CSOM to carry out instructions
  context.executeQueryAsync(onSuccess, onFail);
}

function onSuccess() {
  $("#message").text("Site title: " + web.get_title());
}

function onFail(sender, args) {
  $("#message").text("Error: " + args.get_message());
}

The code in this listing creates two page-level variables named context and web to reference two CSOM objects. The first CSOM object is the client context which is referenced using a call to new ClientContext.get_current(). You can think of the client context as your connection back to the site which served up the current page. The second CSOM object referenced by the web variable represents the current SharePoint site (the app web in this example) which is retrieved by calling the get_web method on the client context object.

One of the most important concepts in CSOM programming is that many of its objects have to be initialized by calling across the network before their properties contain meaningful values. For example, the object referenced by the web variable does not have valid property values after the call to get_web. Instead, you must call context.load(web) to provide CSOM with instructions to populate its property values and then you must call context.executeQueryAsync to make an asynchronous call across the network in which CSOM will actually retrieve the property value for the current site and populate the object referenced by the web variable.

It’s also important to observe that the call across the network in this example is made asynchronously. If client-side code running in the browser were to make a call across the network in a synchronous fashion, it would produce the undesired effect of freezing the user interface. This would result in an unacceptable user experience so it must be avoided. When writing client-side code which calls from the browser across the network you must ensure you are using asynchronous calls which is accomplished in CSOM by calling thecontext.executeQueryAsync method.

When you call context.executeQueryAsync you must pass two callback functions which I have named onSuccess and onFail. The first callback function named onSuccess is called by CSOM if the call across the network completes without errors. The second callback function named onFail is what CSOM calls if the call across the network experiences an error. In this simple example the onSuccessfunction has been written to retrieve the Title property of the app web by calling web.get_title. It also uses the jQuery style of coding to write the Title property value into the div elements with the id of message where it can be seen by the user.

$("#message").text("Site title: " + web.get_title());

In the sample code I have added to TheCsomRestPartyPack.zip, I have included a SharePoint-hosted app project namedSharePointAppCSOMDemo. This SharePoint app contains client-side JavaScript code which demonstrates getting more involved with the CSOM. Here is a screenshot of the app’s start page which shows its basic functionality.

For example, there is JavaScript code in the SharePointAppCSOMDemo project which demonstrates updating the app web’s Titleproperty, adding a new list and switching back and forth between a custom master page and the standard master page for SharePoint-hosted apps named app.master. For example, you can use CSOM to switch the master page for the current site using the following JavaScript code.

function onUseCustomMaster() {
  var masterUrl = web.get_serverRelativeUrl() + 
                  "/_catalogs/masterpage/CustomApp.master";
  web.set_masterUrl(masterUrl);
  web.update();
  ctx.executeQueryAsync(refreshPage, onError);
}

I will now conclude this section by summarizing some of the key points of programming client-side JavaScript using CSOM. First, your code must ensure that the file named sp.js has been downloaded before you can use any functions or objects provided by CSOM. Second, you must initialize certain CSOM objects before you use them. Finally, you initialize CSOM objects and perform other actions such as creating new lists by calling across the network in an asynchronous fashion using a call to executeQueryAsync.

Writing Client-side JavaScript using the REST API

As you have probably noticed over the last few years, REST-based Web services have become increasing popular throughout the IT industry and particularly within Microsoft. SharePoint 2013 introduces a new REST API that expose the much of the same functionality that is available through CSOM. This is great news for developers writing client-side JavaScript code because the new REST API often results in code that is easier to write and maintain when compared to programming with CSOM. The new REST API also provides essential entry points for servers-side code which does not run on the.NET Framework which does not have the ability to use CSOM. Because of this, you can say that the new REST API makes SharePoint 2013 a much more “open” platform.

A significant percentage of the new REST API has been created in accordance with a emerging web-based protocol known as Open Data Protocol (OData). The OData protocol has been designed to allow client applications to query and update data using standard HTTP verbs and to send and retrieve data in standardized formats such as Atom, JSON or plain XML. The OData protocol also includes provisions for common data retrieval tasks such as filtering, ordering and pagination. If you are planning to become proficient with the new REST API in SharePoint 2013, you will find that the OData website is a very useful resource.

http://www.odata.org/

Programming against the REST API in SharePoint 2013 is quite different than programming with CSOM. The first thing you will notice is that using the REST API does not require a SharePoint-specific JavaScript class library. Therefore, you do need to supply code to force the download of a JavaScript source file. Instead, the REST API requires you to parse together URLs that represents target objects such as sites, lists and items. Therefore, your first challenge is learning how to parse together these URLS according to the rules outlines by the OData protocol along with additional specifics added by SharePoint 2013. For example, you might be required to parse together an URL whose target object is a SharePoint site. Additionally, you might be required to add a query string parameter to indicate which property or properties you want to retrieve.

As you get started with the REST API, you can begin learning how to create the URLs required for querying data just using a browser. For example, you can type an URL into the address bar of the Internet Explorer and execute the request against a SharePoint site to see the results. For example, imagine there is a SharePoint 2013 site accessible at http://wingtipserver. You can type the following URL into the browser to execute an HTTP GET request to retrieve the Title property of the current site.

http://wingtipserver/_api/web/?$select=Title

The URL is made up of three basic parts. First, there is the base URL of http://wingtipserver/ that points to the site. In OData terminology this is known as the service root. The next part of the URL is the resource path that points to the target site which in this case is _api/web/. Finally, there are the query options which involve a single query string parameter in this case of ?$select=Titlewhich tells the SharePoint host environment to return the site’s Title property. When you execute a GET request through the browser using this URL, the SharePoint host environment returns the following XML result.

<entry xmlns="http://www.w3.org/2005/Atom" 
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" >

  <id>http://wingtipserver/_api/Web</id>
  <category term="SP.Web" />
  <content type="application/xml">
    <m:properties>
      <d:Title>Wingtip Test Site</d:Title>
    </m:properties>
  </content>

</entry>

By default, the SharePoint host environment responds to REST calls by returning XML which is structured according to a standard known asAtom Syndication Format. However, when making REST calls with JavaScript code it is often easier to request that results are returned in an easier-to-use format known as JavaScript Object Notation (JSON). This can be accomplished by adding the accept header to the GET request. For example, if you submit a GET request using the exact same URL and you include the accept header with a value ofapplication/JSON, the result that comes back now looks like this.

{
  "d": {
    "__metadata": {
      "id": "http://wingtipserver/_api/Web",
      "uri": "http://wingtipserver/_api/Web",
      "type": "SP.Web"},
    "Title": "Hello REST"
  }
}

When the result is returned in JSON format, it can be easily transformed into a JavaScript object. This means you can access the data returned from a REST call without any need to parse through XML. This is a significant productivity win in many scenarios. If you use thegetJSON function supplied by jQuery, you don’t even have to convert the JSON result from text into a JavaScript object because that is done for you automatically.

Now I have covered enough background information to present the ‘hello world’ JavaScript code behind the start page of a SharePoint-hosted app which uses the REST API. To be consistent with the earlier example I showed using CSOM, our first REST API example will query the Title property of the app web. Note that the code in the following listing uses a standard JavaScript variable named_spPageContextInfo which the SharePoint host environment adds to every page.

$(function () {

  // parse together URL for HTTP GET request
  var requestUri = _spPageContextInfo.webAbsoluteUrl + "/_api/Web/?$select=Title";

  // transmit GET request to SharePoint host environment
  jqhxr = $.getJSON(requestUri, null, onSuccess);
  jqhxr.error(onFail);
});

function onSuccess(data) {
  var appWebTitle = data.d.Title;
  $("#message").text(appWebTitle);
}

function onFail(errorObject, errorMessage) {
  $("#message").text("Error: " + errorMessage);
}

As you can see, the _spPageContextInfo variable exposes a property named webAbsoluteUrl which makes it possible to determine the service root of the current site. You parse together the URL required by taking this service root and appending the resource path to specify a target object (e.g. the current site) and a query string to include any query options you need. Once you have parsed together the correct URL, you can then transmit the HTTP GET request to the SharePoint host environment using the jQuery function named getJSON.

Just as in the case of programming against CSOM, you should ensure that calls across the network are made using an asynchronous technique so you do not freeze the user interface of the browser. Fortunately, all the jQuery functions such as getJSONajax and loadhave been implemented with asynchronous behavior. You just need to supply callback methods which are automatically executed when the result is returned from across the network. In this simple example, the callback method named onSuccess executes and passes a parameter named data with represents the JSON result. When using the getJSON method, you will find that the callback method passes a parameter which has already been converted from text into a JavaScript object. You can access the Title property of the SharePoint site by simply accessing the Title property of a JavaScript object.

function onSuccess(data) {
  var appWebTitle = data.d.Title;
  $("#message").text(appWebTitle);
}

The sample code in TheCsomRestPartyPack.zip contains a SharePoint-hosted app project named SharePointAppRESTDemo. This sample SharePoint app creates a Customers list in the app web at installation time and populates this list with a handful of sample customer items. I created the Customers list in this SharePoint app mainly so the app can demonstrate how to program against list items using the REST API. I also wrote all the JavaScript code in this app that is needed to demonstrate the full set of CRUD (create, read, update and delete) functionality that the REST API makes possible. Here’s a screenshot of the start page and the Add New Customer dialog which will give you an idea of what this app can do.

I will leave it to you to explore all the code in this sample app. There is far too much JavaScript code to walk through it all in this post. However, I’d like to present a few chosen listings of the JavaScript code from this app to make a few more points for those getting started.

First, I would like to discuss returning a set of data in JSON format and rendering it as HTML. This is often accomplished using a separate JavaScript library. In this sample app I am using one of my favorites which is jsrender. This JavaScript library is based on its own unique template syntax which makes it fairly easy to convert a JSON result into an HTML element such as a list or a table. Here is a slightly watered-down version of the code in the SharePointAppRESTDemo app that returns the Customers list as a JSON result and then uses the jsrender library and its powerful template syntax to convert the list items into an HTML table for display on the app’s start page.

function onDataReturnedListing(data) {

  // clear out the target element on the start page
  $("#results").empty();

  // obtain the JavaScript object array from the JSON result
  var odataResults = data.d.results;

  // create the header row for the HTML table
  var tableHeader = "<thead>" +
                      "<td>Last Name</td>" +
                      "<td>First Name</td>" +
                      "<td>Work Phone</td>" +
                    "</thead>";

  // create a new table using jQuery syntax
  var table = $("<table>", { id: "customersTable" }).append($(tableHeader));

  // create a rendering template using jsrender syntax
  var renderingTemplate = "<tr>" +
                            "<td>{{>Title}}</td>" +
                            "<td>{{>FirstName}}</td>" +
                            "<td>{{>WorkPhone}}</td>" +
                          "</tr>";

  // use the rendering template to convert JSON result to an HTML table
  $.templates({ "tmplTable": renderingTemplate });
  table.append($.render.tmplTable(odataResults));

  // write the table into a target element on the start page
  $("#results").append(table);

}

From this code you should be able to see the value of using the jsrender library. It makes it so much easier to write and maintain JavaScript code that converts data from the JSON format into HTML elements. I find that I am more impressed with the jsrender library and what it can do each time I use it. To be fair and impartial I must admit that my friends, AC and Scot, both tell me they prefer theknockout library hands down over jsrender. But then again, they are both Republican golfers and so I have to take what they say with a grain of salt. They probably just prefer knockout because they are accustom to having someone else do all the hard work for them and to have this work done out of sight where they don’t have to watch. Oh, but I digress.

I’d like to show one final code snippet from the SharePointAppRESTDemo app to give you an idea of how to write code that actually updates list data within a SharePoint site. Here is the JavaScript code that is used to add new items to the Customers list.

// get new Customer data from new customer dialog
var LastName = returnValue.LastName;
var FirstName = returnValue.FirstName;
var WorkPhone = returnValue.WorkPhone;

// parse together URL with resource path for target list
var requestUri = _spPageContextInfo.webAbsoluteUrl +
                 "/_api/Web/Lists/getByTitle('Customers')/items/";

// create JavaScript object to create headers for request
var requestHeaders = {
  "accept": "application/json",
  "X-RequestDigest": $("#__REQUESTDIGEST").val(),
}

// create JavaScript object with new customer data
var customerData = {
  __metadata: { "type": "SP.Data.CustomersListItem" },
  Title: LastName,
  FirstName: FirstName,
  WorkPhone: WorkPhone
};

// convert customer data from JavaScript object to string-based JSON format
requestBody = JSON.stringify(customerData);

// transmit HTTP POST operation to SharePoint host environment to add new list item
$.ajax({
  url: requestUri,
  type: "Post",
  contentType: "application/json",
  headers: requestHeaders,
  data: requestBody,
  success: onSuccess,
  error: onError
});

I’d like to point out that the call to the ajax function includes a header named X-RequestDigest. This header is important because it contains an essential piece of information known as the form digest value. The SharePoint host environment relies on the form digest value to protect against replay attacks. The important thing to understand is that the SharePoint host environment will reject any REST call that attempts to modify content which does not contain the X-RequestDigest header with a valid form digest value.

Fortunately, it is pretty easy to obtain the form digest value because it gets added to all pages by the standard SharePoint master pages in a div element with an id of __REQUESTDIGEST. Therefore, you can read the form digest value on any standard page served up by the SharePoint host environment using this jQuery syntax.

var formDigestValue = $("#__REQUESTDIGEST").val()

You should also observe how data for the new list item is passed from this JavaScript code to the SharePoint host environment. It is done by creating a JavaScript object that is converted into a text-based JSON format using a call to the JSON.stringify function. The JavaScript object is initialized with properties named to match the site columns in the target list along with a property named __metadata. The__metadata property must be initialized with an inner JavaScript object that contains a property named type. The type property in this example is given a value of SP.Data.CustomersListItem which is a predictable type name given by the SharePoint host environment when you create a list with a title of “Customers”. In other scenarios you might have to query a SharePoint list using the REST API in order to determine what value should be assigned to the type property when adding new items to a list.

Before moving on to server-side programming, let’s summarize some of the key points of programming client-side JavaScript using the REST API. First, you must learn how to parse together the URLs required for making REST API calls according to the OData protocol and the specifics used by SharePoint 2013 to create resource paths which can be used to reference target objects such as sites, lists and list items. Second, passing input data and returning results in JSON format usually provides the easiest way to program in JavaScript. Third, the jQuery library is your friend because it provides convenient functions to transmit HTTP requests to the SharePoint host environment using whatever HTTP verb is required for the current request at hand. Last of all, you should get to know some of the great JavaScript libraries that are available for free. I demonstrated using jsrender in this post but there is also a great deal of excitement around other libraries such as knockout and SignalR.

Writing Server-side Code in Cloud-hosted SharePoint Apps

Now we will turn our attention from client-side programming to server-side programming. One favorable aspect of server-side programming for many experienced .NET developers is that you can leave behind the loosely-typed nature of JavaScript and begin coding in C# or VB which provides the benefits of compile-time type checking, better IntelliSense and full access to the libraries of the .NET Framework.

Also keep in mind that your server-side code runs in a standard ASP.NET application and not inside the SharePoint environment. Therefore, you don’t have to worry about many of the strange constraints and SharePoint-isms that require your attention when writing server-side code in a farm solution such as crippling the local SharePoint farm’s performance by forgetting to properly dispose of SPSite objects in memory.

For the sample code I will use to demonstrate server-side programming in this post, I will use two SharePoint app projects that have been designed to use internal authentication and to programming exclusively against the app web. I am using this scenario to simplify things because a cloud-hosted SharePoint app that uses internal authentication does not require explicit programming to manage app authentication. By eliminating any code to deal with app authentication, I can focus on the core fundamentals of CSOM and REST API programming.

The other nice thing about cloud-hosted SharePoint app projects that use internal authentication is that you can just open them in Visual Studio and test them out by pressing the {F5} key. However, you should take note that you must have your development environment configured with a local SharePoint 2013 farm to run the cloud-hosted app projects I will be discussing over the next two sections. If you want to learn about how I configured these sample apps to use internal authentication, you can read my post titled Configuring a Cloud-hosted SharePoint App to Use Internal Authentication.

Writing Server-side C# code that uses CSOM

Getting started with with server-side CSOM code in a cloud-hosted app is easier than it is with client-side JavaScript code. The first reason is that you have the benefit of compile-time type checking. The second reason is that you are able to use synchronous execution instead of asynchronous execution so your server-side code doesn’t require callback methods like the JavaScript code I showed earlier.

The C# code I will show in this section is available in TheCsomRestPartyPack.zip download in a sample SharePoint app project namedCloudAppCsomDemo. While this sample app will not win any awards for user interface design, it provides some simple examples of server-side C# code and a few ideas for cloud-hosted app designs. Here is a screenshot of the app’s start page.

Let’s see how easy it is to get started with programming CSOM on the server. The CloudAppCsomDemo app contains the following server-side C# code in the Page_Load method of the app’s start page which retrieves the incoming SPAppWebUrl query string parameter with the app web URL and then uses CSOM to synchronously retrieve the app web’s Title property and display it on a ASP.NET label control named lblAppWebTitle.

protected void Page_Load(object sender, EventArgs e) {

  // retrieve app web URL from incoming query string parameter
  string appWebUrl = Page.Request["SPAppWebUrl"];

  using (ClientContext clientContext = new ClientContext(appWebUrl)) {
    Web appWeb = clientContext.Web;
    clientContext.Load(appWeb);
    clientContext.ExecuteQuery();
    lblAppWebTitle.Text = appWeb.Title;
  }
}

At this point you’re probably thinking that writing server-side code using CSOM looks pretty easy compared to writing it with client-side JavaScript. Well, in many scenarios that is indeed the case. However, there is a catch. If you add server-side CSOM code like this behind the start page of a cloud-hosted app, the user will be sitting around and waiting for the app’s start page to load while your code is making round trips between the remote web and the SharePoint host environment. If your code is doing a significant amount of initialization work with the CSOM, the wait time to load and display the start page might approach an unacceptable amount of time.

A better design can often result from avoiding server-side CSOM code behind the app’s start page because it results in a start page which loads faster without unnecessary delay. While many cloud-hosted apps will require CSOM code at start-up, this code can be moved into secondary pages and handlers which can be called from the start page asynchronously using client-side JavaScript. Let’s walk through an example of how to create such a design.

We will begin be adding code to the app’s start page Default.aspx to take the incoming SPAppWebUrl query string parameter which points to the app web URL and to cache it for other pages and handlers to use.

// code added to start page
protected void Page_Load(object sender, EventArgs e) {

  // cache url to web app for other pages
  Cache["SPAppWebUrl"] = Page.Request["SPAppWebUrl"];
}

The next step is to create a secondary page or handler which does the actual work against the CSOM. I have found that adding a Generic Handler project item (i.e. a handler with an .ashx extension) into the ASP.NET project for the remote web provides an easy and effective way to create a server-side entry point which can be called from client-side JavaScript on the start page. For example, you can create a generic handler named appWebTitle.ashx and implement it with the following code to return the app web Title property as simple text.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using Microsoft.SharePoint.Client;

namespace CloudAppCsomDemoWeb.Pages {

  public class appWebTitle : IHttpHandler {

    public void ProcessRequest(HttpContext httpContext) {

      // retrieve app web URL from cache
      string appWebUrl = httpContext.Cache["SPAppWebUrl"].ToString();

      string appWebTitle = string.Empty;
      using (ClientContext clientContext = new ClientContext(appWebUrl)) {
        Web appWeb = clientContext.Web;
        clientContext.Load(appWeb);
        clientContext.ExecuteQuery();
        appWebTitle = appWeb.Title;
      }

      // return response as simple text
      httpContext.Response.ContentType = "text/plain";
      httpContext.Response.Write(appWebTitle);
    }

    public bool IsReusable { get {return false;} }

  }
}

Once you have created a generic handler like this, you can call it and load its contents into a div element using JavaScript behind that start page which calls the jQuery load function.

$("#appwebtitle").load("/Pages/appWebTitle.ashx");

You can take this type of design one step further by implementing a generic handler to return its results in other formats such as HTML, XML or JSON. Here’s an example of a generic handler that uses CSOM to discover the lists that exist within the app web and to return the title of each of these lists using an HTML <ol> element.

public void ProcessRequest(HttpContext httpContext) {

  string appWebUrl = HttpContext.Current.Cache["SPAppWebUrl"].ToString();

  using (ClientContext clientContext = new ClientContext(appWebUrl)) {

    // use CSOM to retrieve collection of lists
    Web appWeb = clientContext.Web;
    ListCollection appWebLists = appWeb.Lists;
    clientContext.Load(clientContext.Web);
    clientContext.Load(clientContext.Web.Lists);
    clientContext.ExecuteQuery();

    // set up HtmlTextWriter to write to response output stream
    httpContext.Response.ContentType = "text/html";
    StreamWriter innerWriter = new StreamWriter(httpContext.Response.OutputStream);
    HtmlTextWriter writer = new HtmlTextWriter(innerWriter);

    // create an HTML ol element with list of lists in app web
    writer.RenderBeginTag(HtmlTextWriterTag.Ol);
    foreach (var list in appWebLists) {
      writer.RenderBeginTag(HtmlTextWriterTag.Li);
      writer.Write(list.Title);
      writer.RenderEndTag(); // </li>
    }
    writer.RenderEndTag(); // <ol>

    // flush results to output stream and clean up
    writer.Flush();
    writer.Dispose();
  }

}

Let’s look at one final example of server-side C# code which uses the CSOM to create a new list in the app web. The start page contains an ASP.NET UpdatePanel control which provides the user with the ability to add new lists to the app web. The UpdatePanel allows for a simple design where you can add server-side code behind a command button without forcing page postbacks. The code behind the Create New List command button looks like this.

// retrieve title and type for new list from server-side controls
string ListTitle = txtNewListTitle.Text;
int ListType = Convert.ToInt32(lstListType.SelectedValue);

// retrieve URL to app web
string appWebUrl = Page.Request["SPAppWebUrl"];

// use CSOM to create new list
using (ClientContext clientContext = new ClientContext(appWebUrl)) {
  ListCreationInformation newList = new ListCreationInformation();
  newList.Title = ListTitle;
  newList.Url = "Lists/" + ListTitle;
  newList.QuickLaunchOption = QuickLaunchOptions.On;
  newList.TemplateType = ListType;
  clientContext.Web.Lists.Add(newList);
  try {
    clientContext.ExecuteQuery();
    lblStatus.Text = "New " + lstListType.SelectedItem.Text + 
                     " created with title of " + ListTitle;
  }
  catch (Exception ex) {
    lblStatus.Text = "ERROR: " + ex.Message;
  }
}

// add client-side script to asynchronously reload lists
string updateScript = "$('#appweblists').load('/Pages/appWebLists.ashx');";
ScriptManager.RegisterClientScriptBlock(upNewList, 
                                        upNewList.GetType(), 
                                        upNewList.ClientID, 
                                        updateScript, true);

As you can see, it is relatively straight forward to create lists and other types of SharePoint site elements using server-side C# code which programs against the CSOM. At the end of this listing I have added a call to ScriptManager.RegisterClientScriptBlock in order to execute the client-side jQuery code required to retrieve the set of lists from the app web which includes the list that has just been created.

I will now conclude this section by summarizing some of the key points of programming server-side C# code using the CSOM. First, many programmers find this type of programming easier than using JavaScript because there is compile-time type checking and full access to the libraries of the .NET Framework. Second, the CSOM programming is a bit easier on the server because you call across the network synchronously using ExecuteQuery without having to worry about freezing the user interface as you do with client-side code. Third, there is often a need for loading content asynchronously, but this often means exposing additional entry points in the remote web project such as generic handler and web service methods and calling them from client-side JavaScript code. Finally, and best of all, you can use all the little tricks and techniques that the ASP.NET Framework has to offer without the frustrating limitations and constraints imposed on server-side code in farm solutions which run inside the SharePoint environment.

Writing Server-side C# code that uses the REST API

To say that writing server-side C# against the new REST API is more tricky than the CSOM is a bit of an understatement. Writing server-side C# code using the REST API can be a downright pain in your ASP. I think you will agree after seeing the code listings in this section.

The download named TheCsomRestPartyPack.zip contains a sample SharePoint app project named CloudAppRestDemo. This sample app provides the exact same functionality and user interface as the CloudAppCsomDemo app. The only difference is that one uses CSOM to talk to the SharePoint host environment where the other uses the REST API. The app which uses the REST API requires more C# code than the CSOM-based app to accomplish the same tasks. After seeing the comparison you will likely agree that C# code using the REST API is harder to write and maintain.

Let’s start by examining the code in the Page_Load method of the app’s start page which uses the REST API to retrieve the app web Titleproperty and display it on a ASP.NET label control named lblAppWebTitle.

// retrieve URL to app web
string appWebUrl = Page.Request["SPAppWebUrl"];

// create URL for REST call to query for app web Title property
Uri uri = new Uri(appWebUrl + "/_api/web/?$select=Title");

// transmit HTTP GET request to SharePoint host environment
HttpWebRequest requestGet = (HttpWebRequest)WebRequest.Create(uri);
requestGet.Credentials = CredentialCache.DefaultCredentials;
requestGet.Method = "GET";
HttpWebResponse responseGet = (HttpWebResponse)requestGet.GetResponse();

// retrieve Title property from XML returned by SharePoint host environment
XDocument doc = XDocument.Load(responseGet.GetResponseStream());
XNamespace ns_dataservices = "http://schemas.microsoft.com/ado/2007/08/dataservices";
lblAppWebTitle.Text = doc.Descendants(ns_dataservices + "Title").First().Value;

The code in this listing begins by parsing together the proper URL to make the REST call which returns the app web’s Title property in an ATOM-based XML result. Next, the code prepares and transmits an HTTP GET request to the SharePoint host environment using the newHttpWebRequest class that was introduced in .NET 4.0. When the call to the GetResponse method returns, you have to extract the Titleproperty value from the returned XML document. If you are not familiar with LINQ to XML and the XDocument class, you should get up to speed on them because they make this type of programming much easier than using the older XML-based APIs of the .NET Framework.

As you can see in the listing above, the Descendants method of the XDocument class makes it much easier to extract the namespace-qualified Title property out of the following XML result.

<entry xmlns="http://www.w3.org/2005/Atom" 
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" >

  <id>http://big-long-url-to-app-web/_api/Web</id>
  <category term="SP.Web" />
  <content type="application/xml">
    <m:properties>
      <d:Title>Wingtip Test Site</d:Title>
    </m:properties>
  </content>

</entry>

Now let’s look at the generic handler which has been written to use the REST API discover the set of lists in the app web and to generate an HTML list element which can be used for display on the start page. Here is the code inside the ProcessRequest method of the generic handler that accomplishes this work.

public void ProcessRequest(HttpContext context) {

  // prepare response as HTML and set up HtmlTextWriter
  context.Response.ContentType = "text/html";
  StreamWriter innerWriter = new StreamWriter(context.Response.OutputStream);
  HtmlTextWriter writer = new HtmlTextWriter(innerWriter);

  // get URL for app web
  string appWebUrl = context.Cache["SPAppWebUrl"].ToString();

  // create URL for REST API to retrieve lists from app web
  Uri uri = new Uri(appWebUrl + "/_api/web/lists/?$select=Title");

  // transmit HTTP GET request to SharePoint host environment
  HttpWebRequest requestGet = (HttpWebRequest)WebRequest.Create(uri);
  requestGet.Credentials = CredentialCache.DefaultCredentials;
  requestGet.Method = "GET";
  HttpWebResponse responseGet = (HttpWebResponse)requestGet.GetResponse();

  // load XML result in XDocument object    
  XDocument doc = XDocument.Load(responseGet.GetResponseStream());
  XNamespace ns_dataservices = 
             "http://schemas.microsoft.com/ado/2007/08/dataservices";

  // create an HTML ol element with list of lists in app web
  writer.RenderBeginTag(HtmlTextWriterTag.Ol);
  foreach (var list in doc.Descendants(ns_dataservices + "Title")) {
    writer.RenderBeginTag(HtmlTextWriterTag.Li);
    writer.Write(list.Value);
    writer.RenderEndTag(); // </li>
  }
  writer.RenderEndTag(); // </ol>

  // flush generated HTML to response stream and clean up
  writer.Flush();
  writer.Dispose();

}

Once again, the REST API requires that you parse together the URL for a GET request that queries the app web for the current set of lists. The code in this listing prepares an HTTP GET request that is sent and received using HttpWebRequest and HttpWebResponse objects. At the end there is code written using the XDocument class which enumerates through the returned XML document to create an HTML list element which contains a list item with the Title property of each list which is written into the generic handler’s output stream.

When it comes time to modify content in a SharePoint site such as creating a list is when programming C# against the REST API gets pretty grungy. For example, you need to acquire the form digest value that was discussed earlier this post. However, the form digest value is not readily available as it was in the previous example which involved writing JavaScript behind a page served up from a SharePoint site. Instead, you must make an HTTP POST request with an URL that queries the REST API for context information using a URL that ends with_api/contextinfo. Here is an example of a utility function I wrote named GetFormDigest which calls to the SharePoint host environment to acquire a Form Digest value that can then be used in subsequent requests that modify content.

private string GetFormDigest(){
  string appWebUrl = Cache["SPAppWebUrl"].ToString();
  Uri uri = new Uri(appWebUrl + "/_api/contextinfo");
  HttpWebRequest requestPost = (HttpWebRequest)WebRequest.Create(uri);
  requestPost.Credentials = CredentialCache.DefaultCredentials;
  requestPost.Method = "POST";
  requestPost.ContentLength = 0;
  HttpWebResponse responsePost = (HttpWebResponse)requestPost.GetResponse();
  XDocument doc = XDocument.Load(responsePost.GetResponseStream());
  XNamespace ns_dataservices = 
             "http://schemas.microsoft.com/ado/2007/08/dataservices";
  return doc.Descendants(ns_dataservices + "FormDigestValue").First().Value;
}

In addition to acquiring a form digest value, creating a new list with the REST API requires you to parse together the payload for the request body using either an ATOM-based XML format or JSON. In our scenario the XML payload must contain information about the new list that is being created. Since we are working with C# instead of JavaScript, it is easier to use the ATOM-based XML format instead of JSON. The code behind Default.aspx contains a protected string constant named AtomXmlForNewList which provide a template for creating the XML required to create a new list.

protected string AtomXmlForNewList = @"
<entry xmlns='http://www.w3.org/2005/Atom' 
	xmlns:d='http://schemas.microsoft.com/ado/2007/08/dataservices' 
	xmlns:m='http://schemas.microsoft.com/ado/2007/08/dataservices/metadata' >

  <category term='SP.List' 
            scheme='http://schemas.microsoft.com/ado/2007/08/dataservices/scheme' />

  <content type='application/xml'>
    <m:properties>
      <d:Title>@Title</d:Title>
      <d:BaseTemplate m:type='Edm.Int32'>@ListTypeId</d:BaseTemplate>
    </m:properties>
  </content>

</entry>";

Using a string-based template like this, your code just needs to do a search-and-replace operation on the two placeholders named @Titleand @ListTypeId. Then you write the resulting XML document into the body of a POST request that you transmit to the SharePoint host environment. Here’s the code in the CloudAppRestDemo app that pulls everything together to create new list in the app web using the REST API.

// create URL with resource path referencing app web's list collection
string appWebUrl = Cache["SPAppWebUrl"].ToString();
Uri uri = new Uri(appWebUrl + "/_api/web/lists/");

// create HttpWebRequest for POST operation with Windows authentication credentials
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
request.Method = "POST";
request.Credentials = CredentialCache.DefaultCredentials;

// add header with form digest value
request.Headers["X-RequestDigest"] = GetFormDigest();

// set format of response body
request.Accept = "application/atom+xml";

// create ATOM-based XML document for creating new list
request.ContentType = "application/atom+xml";
string body = AtomXmlForNewList;
body = body.Replace("@Title", txtNewListTitle.Text);
body = body.Replace("@ListTypeId", lstListType.SelectedValue);

// write create ATOM-based XML document to request body
request.ContentLength = body.Length;
StreamWriter writer = new StreamWriter(request.GetRequestStream());
writer.Write(body);
writer.Flush();

try { 
  // send synchronous HTTP POST request to SharePoint host environment
  HttpWebResponse response = (HttpWebResponse)request.GetResponse();
  lblStatus.Text = "New " + lstListType.SelectedItem.Text + 
                   " created with title of " + ListTitle;  
}
catch (Exception ex) {
  lblStatus.Text = "ERROR: " + ex.Message;
}

So now you have seen a direct comparison between server-side C# code using both CSOM and the REST API. Most developers will agree that using the CSOM is significantly easier. That’s because CSOM manages the form digest for you behind the scenes and it doesn’t require you to parse together URLs and XML documents. I will prefer using CSOM over the REST API for server-side C# code until someone is able to show me that the REST API has performance advantages or offers functionality not available through the CSOM. But then again, Microsoft’s big investment in the REST API was not made for this scenario. Microsoft was incented to create the new REST API for the benefit of client-side JavaScript code and for server-side code not running on the .NET Framework which has no access to CSOM.

Summary

You have just read through a long post which I wrote to get you started with developing SharePoint apps which communicate with the SharePoint host environment using CSOM and the new REST API. As you have seen, there are four basic styles. I typically prefer using the REST API over CSOM when writing client-side JavaScript code because it allows me to work with JSON which integrates well with other JavaScript libraries such as jQuery, jsrender and knockout. However, there are some scenarios where you will find that using CSOM is just as easy or easier. I find it’s when I am writing server-side code with C# that there is such a drastic difference in productivity. I will always prefer the CSOM over the REST API in this scenario.

For the purposes of creating a smoother learning path, I avoided any discussion of app authentication and app identity in this post. However, these are essential topics that must be understood by anyone developing cloud-hosted SharePoint apps. Therefore, they will be the focus of the next post in this series that will pick up where this post leaves off.

Tools used for Unit Testing SharePoint 2010

Once you ’ ve done some smoke testing on your dev machine, it is important to perform more formal testing of your code before deploying it. This is where unit, capacity, and load testing come into play. There are a couple of new tools available when it comes to testing. Let ’ s take a look at the new tools.

Visual Studio 2010 Test Tools –

All versions of Visual Studio include some test tools. Depending on which version you buy, you may get more than just unit testing. For example, the Ultimate edition of Visual Studio includes unit testing, code coverage, impact analysis, coded UI testing, web performance testing, and load testing. When it comes to capacity and load testing, you will spend most of your time working on web tests, which allow you to record your keystrokes through a web browser, create validation rules and
dynamic parameters, and create user loads from those tests that you can scale to multiple agents that simulate different connectivity speeds or multiple browser types.
While it is too big a topic to cover in this book, the test tools in Visual Studio, beyond the web tests,will help you write better code. One tool to look at immediately is the coded UI test. It will record your actions on the screen and then create code in VS that performs those actions. It allows you to automate tests that you would otherwise have to perform manually through the user interface.

Load Testing Kit –

As part of the Administration Toolkit released for SharePoint 2010, Microsoft will be releasing a Load Testing Kit (LTK). This kit will contain pre – built web tests for the most common SharePoint scenarios, such as team collaboration, web content management, and social networking applications. The nice thing about these web and load tests is that you can customize them for your own needs. They are just Visual Studio tests. Using the LTK tests as a template will make the creation of your own tests much faster. Another component of the LTK is a data generation utility. As you will see in the best practices section, trying to simulate your production environment is the best way to understand how your code will run in that environment under load and also with different users and different commands being
sent to it. Many times, though, you can ’ t get your production data into your testing environment, so you need to mimic that data in a reasonable way.

Other Useful Tools for Debugging and Testing –
Beyond VS, there are other useful tools to help you with debugging and testing in SharePoint. Following are some recommended ones, but there are more on popular sites like codeplex -http://www.codeplex.com.

SPDisposeCheck
The SharePoint APIs allocate COM – based memory that the Common Language Runtime (CLR) garbage collector does not release. For this reason, you need to explicitly call the Dispose() method on certain objects such as the SPSite and SPWeb objects. If you don ’ t, you will get memory leaks in your application, and it can be hard to track down which pieces of your code are causing the leaks.

Internet Explorer 8 Developer Tools

Sometimes the best debugging tools are the ones built right into the product. Internet Explorer 8 includes the ability to browse your HTML, script, and Cascading Style Sheets (CSS) code right inside of its developer tools.

FireFox and Firebug
If you use FireFox as your browser, you can use Firebug as your HTML development and debugging tool. Firebug provides very similar functionality to the IE8 developer tools in the FireFox environment.

Visual Round Trip Analyzer
The Visual Round Trip Analyzer (VRTA) sits on top of the network monitor tool from Microsoft and is a free add – on. It visualizes how long it takes a client to talk to a server — information that you can then use to understand if you are making excessive round trips, if your code is slowing down the pages (for example, because of loading many small JavaScript or CSS fi les), or if there are network issues causing any problems between your application and the server.

Fiddler
No discussion of debugging tools would be complete without mentioning Fiddler. Fiddler is a web debugging proxy that logs all HTTP traffi c between your computer and the Internet. Fiddler allows you to inspect all HTTP traffi c, set breakpoints, and view your incoming and outgoing data.

List Definitions versus List Templates and deciding on the correct customization approach

List Definitions

A list template Feature includes a Schema.xml file that serves as the base file for a list definition. The List element is the root element of a Schema.xml file, which contains default view definitions, definitions for special fields used in the list, the toolbar definition for list views, content type declarations, and other metadata for the list.

 

A list definition includes a Feature.xml Files file, an element manifest file (see List Template Files), and a Schema.xml file within a Feature folder (\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES). For an example that shows how to create a custom list definition, see how to: Create a Custom List Definition: http://msdn2.microsoft.com/en-us/library/ms466023.aspx

Lists can be created or modified programmatically through the object model (for example, members of the SPList and SPListCollection classes), through the Lists Web service (methods of the Lists class), and through Remote Procedure Call (RPC) protocol (see Microsoft Windows SharePoint Services RPC Methods).

 

Introduction to Listshttp://office.microsoft.com/en-us/sharepointtechnology/HA100242741033.aspx?pid=CH101787241033

List Schemahttp://msdn2.microsoft.com/en-us/library/aa543477.aspx

Major Schema Definition Fileshttp://msdn2.microsoft.com/en-us/library/ms479188.aspx

 

List Templates

A list template is something the end user can create by using the web interface to configure the list. This list can then be saved as a list template. This list template is stored as an *.STP file in the list templates gallery of the Site Collection. This *.STP file is stored in the content database the Site Collection resides.

 

This file contains all the customizations made to the original List Definition, such as CAML and XML that describes the lists. The customizations require the same list definition to be installed on the server that was used to configure the list templates.

It is not as performant as a pure list definition as list definitions are cached on start of IIS on the web front ends while list templates are stored in the Content Database, They need to be fetched from the content database and merged with the list definition code at runtime to render the list.

 

Deciding Between List Definitions and List Templates

Custom list definitions hold the following advantages over list templates:

  • Data is stored directly on the Web servers, so performance is typically better.
  • A higher level of list customization is possible through direct editing of a Schema.xml file.
  • Certain kinds of customization to lists require use of site and list definitions.

 

List definition disadvantages include the following:

  • Customization of list definition requires more effort than configuring list templates.
  • Editing a list definition after it has been deployed is difficult.
  • Doing anything other than adding code can break existing sites.
  • Customizing list definitions requires access to the file system of the front-end Web server.

 

List templates hold the following advantages over customization of list definitions:

  • List templates are easy to create.
  • Almost anything that can be done in the user interface can be preserved in the template.
  • List templates can be modified without affecting existing sites that have been created from the templates.
  • List templates are easy to deploy.

 

List template disadvantages include the following:

  • List templates are not created in a development environment.
  • List templates are less efficient in large-scale environments.
  • If the List definition on which the list template is based does not exist on the front-end server or servers, the list template does not work.

Site Features vs Site Templates vs Site Definitions

Site Definitions versus Site Templates and deciding on the correct customization approach

Site Definitions

l  A site definition is the core definition of what a site is in SharePoint.

l  A site definition is installed on file system of web front ends, located at ..\12\Template\SiteTemplates. This directory is language-neutral.

l  A site definition consists of .aspx pages and .xml files with Collaborative Application Mark-up Language (CAML).

l  A major benefit is that the Page and List definition is read locally from the file system, not from Content Database.

l  A site definition Page and List definition are cached at IIS process startup

l  Customizations made to site definition are stored in content database, not on the file system. This can be performed via SharePoint Designer, or when custom site templates are saved.

l  are developer created

l  Localization: WSS 3.0 supports full site template localization (based on ASP.Net 2.0 via XML files and .ASPX files pulling strings from RESX files. Therefore solutions can be shipped “language packs” of resource files.

l  “Global Template” defines commonality across site definitions; it gets called before any other template. It works by injecting common provisioning content into all new sites. ONET.XML file defines base types, galleries, mobile redirects

Site definitions

Site Template

A site template (*.stp file) is created through the user interface or through implementation of the object model. It is a package containing a set of differences and changes from a base site definition.

 

The site template package is stored as a CAB-based file that can be downloaded or uploaded to site collections by users with the appropriate rights. As before, site templates offer a measure of portability to SharePoint Applications.

It is not as performant as a pure site definition as site definitions are cached on start of IIS on the web front ends while site templates are stored and hence need to be fetched from the content database and merged with the site definition code at runtime to render the site.

Also note that if you plan to transfer a site template to separate farm, that the farms have the same versions installed of SharePoint installed.  (hotfixes,etc.) This is due to the dependence site templates have on the original base site definition they were created from.

Deciding Between Site Definitions and Custom Site Templates

See : http://msdn2.microsoft.com/en-us/library/aa979683.aspx

When choosing whether to create a site template or a site definition, first consider the following issues:

  • Are the changes you need to make simple or complex? If, for example, you need to make only minor changes in the look of certain pages and add a few fields in particular lists, you should create a custom site template. However, if you need to create new content types, add new Web Part definitions, and significantly restructure sites, you should create a custom site definition.
  • Can you deploy changes to the front-end Web server? If you do not have access to the file system of the computers running Windows SharePoint Services, you have no choice but to create a custom site template.

Custom site definitions hold the following advantages over custom templates:

  • Data is stored directly on the Web servers, so performance is typically better.
  • A higher level of list customization is possible through direct editing of a Schema.xml file.
  • Certain kinds of customization to sites or lists require use of site definitions, such as introducing new file types, defining view styles, or modifying the Edit menu.

Site definition disadvantages include the following:

  • Customization of site definition requires more effort than creating custom templates.
  • Editing a site definition after it has been deployed is difficult.
  • Doing anything other than adding code can break existing sites.
  • Users cannot apply a SharePoint theme through a site definition.
  • Users cannot create two lists of the same type with different default content.
  • Customizing site definitions requires access to the file system of the front-end Web server.

Custom templates hold the following advantages over customization of site definitions:

  • Custom templates are easy to create.
  • Almost anything that can be done in the user interface can be preserved in the template.
  • Custom templates can be modified without affecting existing sites that have been created from the templates.
  • Custom templates are easy to deploy.

Custom template disadvantages include the following:

  • Custom templates are not created in a development environment.
  • Custom templates are less efficient in large-scale environments.
  • If the site definition on which the custom template is based does not exist on the front-end server or servers, the custom template does not work.

There is a lot of debate around what is the best approach to provision a Site Collection in an environment.

The three techniques listed below show the pros and cons of these. Each technique gives the ability to automatically provision various elements in a Site Collection which gives:

  • Configuration Management control – each environment will be built the same based on the defined scripts
  • Encourages Change Control Management – can control releases via scripts
  • Time to Production – once the scripts are written, can be released in multiple environments by administrators with little effort. A lot more efficient than manual deployment steps which have to be repeated each time
  • Build Server – with the ability to release to an environment, automated testing scripts can be run on provisioned environment

Site Features

Pro Con
Leverages Feature framework Requires knowledge various programming technologies e.g. C#/VB.NET
Strong site upgrade path (how you upgrade from WSS to MOSS) Requires knowledge of SharePoint Object Model and schemas (and XML)

Site Templates

Pro Con
Working in UI and SharePoint Designer Reliant on UI to create base .stp as hard to create from scratch
Doesn’t support Publishing Features
No Feature Stapling
Doesn’t package all settings (Content Type visibility)

Site Definitions

Pro Con
Great for provisioning Poor upgrade path ( Can’t change site def to another one once created)
Havoc if OOTB defs edited
Workarounds required for particular things (Devs out there editing stored procs and adding triggers!)
Requires knowledge of the Site Definition schema and XML

Alternative to Site Definitions

  • SharePoint Site Configurator Feature on CodePlex

    SharePoint Site Configurator Feature is a small framework for taking care of all configurations, settings and featurestapling you need for transforming a standard blank site definition into your own full blown site, without the hassle of creating a complex custom site definition.

An alternative to using a straight site definition is to combine the site features method with the site definitions method. This involves creating a minimal site definition and putting all the functionality that is required into features. Then tell your site definition configurations what features each should use. This way you still have the benefits around the easy provisioning of your site, but have the flexibility to turn on and off features to add/remove functionality from a site definition. Also it then becomes easy to identify sites that were based on specific definitions, allowing for an easy way to find these sepcific sites to add/remove features from them at a later date.

NOTE: It is very important that you don’t change the list or order of the features listed in the custom site definition. If you do, you will break all the sites that depend on that definition. As an alternative, you can use a “feature queuer”. This is simply a feature that uses a feature receiver to activate other features. As far the site definition is concerned, you have not modified the list of features and thus will not break your existing sites. But you can modify the list of activations in the “feature queuer” for any new sites that would be created from that site definition. It’s kind of a workaround changing the provisioning behavior of the original site definition. You can read more about it here Extending Site Definitions with Web Features

An example of how this method could be used is with a customised publishing portal. It has a site definition that contains 4 configurations (1 for the root site, and 3 different sub site models that could represent the different areas of a business and their specific requirements for example) and each use a combination of features to build thier functionality up what goes in to each site. Some of the features that each site uses can be shared (for example, a customised document library might be required in all 3 sub sites, but this is still done with a single feature) while there might be some features that are used in only a specific sub site. After the site is deployed and has been in production for a while you might find you need to upgrade the sites for one of the business areas to add or remove a feature. The site definition can be upgraded and deployed with a new WSP to ensure new sub sites meet the new design, and existing sites can be updated programatically to have the features modified. These sites can be easily identified (through the SPWeb.WebTemplate property) to ensure that only they are upgraded and the other sites are left alone.

So the pros and cons of this variation of the site definitions method are:

Pro Con
Great for provisioning Workarounds required for particular things (Devs out there editing stored procs and adding triggers!)
Sites can be easily identified to upgrade later Can’t change a site definition once created (although features can still be enabled/disabled)
Leaverages feature framework
OOTB Site Definitions are left alone

External References

SharePoint 2010 – SQL 2012 Reporting Services

With the release of SQL 2012, Reporting Services got a remake specifically for SharePoint 2010. Reporting Services can now be configured as a service application specifically to allow for scaling within your infrastructure. To enable this in SharePoint you must first have installed the SharePoint component from SQL 2012. You can find this by running the installer for SQL and selecting the following:

Once this is done you need to load the “SharePoint 2010 Management Shell” and run the following command:

This will install the core services into the SharePoint Farm. Once done, run the following command which will provision the service proxy.

You should now be able to run the following command and see a provisioned instance.

This allows us to actually create the Service Application as we would with any of the other out of the box ones. Simply access, “Central Administration > Manage Service Applications > New > SQL Server Reporting Services Service Application“.

As with all service applications you need to provide some base configuration.

Once the top section is complete you are then able to associate it directly with web applications, in my case I do not have any as this is a “vanilla” virtual machine.

Now it is time to watch the magic wheel, spinning away J

Once it has finished it will present you with a completion message and then a link to some further configuration, which will present a message letting you know if the SQL Server Agent service is running.

To start the SQL Agent access SQL management and right click the “SQL Server Agent” node and choose “Start“.

Once done, you can refresh the page and it should show the correct running status.

In order for the service application work as expected certain permissions need to be assigned to the application pool account. Click the “Download Script” command to get a dynamically generated script that you must then run in the SQL management studio.

The script looks as follows and is simply adding the “RSExecRole” and adding permissions within various databases to the application pool account.

This needs to and should complete successfully.

SQL Reporting Services needs to access the SQL Agent through an account, you must now set this.

Once you have it all completed, I found that I needed to reboot the server to stop myself getting the following error:

The server was unable to process the request due to an internal error. For more information about the error, either turn on IncludeExceptionDetailInFaults (either from ServiceBehaviorAttribute or from the <serviceDebug> configuration behavior) on the server in order to send the exception information back to the client, or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation and inspect the server trace logs.

Once it was rebooted I could then access the service application by going to “Central Administration > Manage Service Applications > SQL Server Reporting Services

So now we have our service application created we are ready to use it within our SharePoint Web Applications, I will cover this in a further post.

So in the last post we looked at just setting it all up and making SharePoint use the service application to provide reporting services to the farm. In this post we will now look at using it in our site collection.

Firstly we are going to create a “Report Library” by selecting “Site Actions > More Options“, then selecting “Library > Report Library“.

For this example I am going to call my list “SSRS Reports“, aptly named I think.

Once created we need to access the “Library Settings” and modify the content types that are assigned to it.

From the list of content type groups, select the “SQL Server Reporting Services Content Types” group.

Now simply add, “Report Builder Model, Report and Report Data Source” to the list.

I have also removed the standard two “Report and Web Part Page with Status List” just to make it nice and clean.

So now we have them added we can access the “New Document” link and see the three new report content types.

Let’s look at creating a “Report Data Source“. Select the corresponding content type from the “New” menu and then complete the details as shown below. Of course you may decide to use a windows account, SQL account, pass through or even prompt for authentication. I am using SQL authentication for this demo. The connection string is to my local server and is using the Adventure Works Database for SQL 2012.

Once completed you can use the “Test Connection” link to validate it work and should render in green text if it successful.

So we have our data source now we need to create a model so we can use this in our report builder tool Select the “Report Builder Model” from the “New” menu then give it a name.

The data source link has a picker that will display all the data sources in the site whether in the same site or in the current site collection.

Simply select the data source we created earlier and press okay.

Now we have it configured, press “OK” and it will save back into the library and should look as below.

We now have the core components configured, now time to use the report builder. Access the “New” menu and select “Report Builder Report“; you should then be promoted to run the application.

The application should then download and finally launch (like watching paint dry) J

Once the application opens you get various options to create reports as shown below.

We will select the “Table or Matrix Wizard” as the example.

The report requires a dataset that we can use so we can select the “Create Dataset” as we do not have any already created. Upon pressing “Next” we are asked to select the data source for the dataset.

Use the picker to select either the data source or the data model, either will work.

I chose the “Report Builder Model“, and selected the “Test Connection” to check that it worked.

For me I was prompted as per my configuration for the password of my SQL account.

So we have our data source defined, we are going to create a new dataset and tested it. So now we need to select the tables, views or stored procedures that will populate my report.

I chows the “Vendor with Addresses” view as my test.

Once selected you are then able to drag and drop the fields into the columns that you wish to use as shown below.

Finally your layout can be defined by following through the rest of the wizard, selecting the layouts and the style.

Once done you will be returned to the design canvas where you can make further changes or as I did, simply press “Run” to see the data returned.

And there you have it a fully built report inside of SharePoint 2010 using SQL 2012 Reporting Services. Once last step though, press the “Save” icon and save it back to the report library we created earlier.

As you can see once everything is configured and working it is very easy to create and access reports in SharePoint 2010.

SharePoint 2010 Custom Welcome Control

Recently while answering a few questions I got faced with the need to use a specific claim in the welcome control. As you may all be aware sometimes when using Membership and Role Provider or custom Identity Providers the welcome display name can get a little messed up and not display the correct details, this is true more so with Identity Providers such as ADFS where the primary claim is used in the control. I decided that I wanted to create a custom welcome control that would allow me in code to set what the display test should be so something like: “Welcome: {Selected Claim}“.

This post will show some basic code for doing this. Firstly create a new solution and SharePoint Project. I always use the “Empty SharePoint Project“. For this example I called the solution “Helloitsliam” and the project “Helloitsliam.WelcomeControl“.

Now we have the project we need to right click and select to add a new user control.

I named my control “HelloitsliamWelcome.ascx“.

We then need to add the following code to the “ASCX” markup:

We also need to add some other markup that use “<asp:Panel>” controls for hiding and showing the relevant controls.

These panels will be for hiding and showing the correct logic depending on whether it is some sort of forms based login or windows login. So now we need to add the following base code to the panels:

<asp:Panel runat=”server” ID=”idpHelloitsliamPanel” style=”display:inline;”>

<SharePoint:PersonalActions accesskey=”<%$Resources:wss,personalactions_menu_ak%>”ToolTip=”<%$Resources:wss,open_menu%>” runat=”server” id=”ExplicitLogout” Visible=”false”>

<CustomTemplate>

<SharePoint:FeatureMenuTemplate runat=”server”

FeatureScope=”Site”

Location=”Microsoft.SharePoint.StandardMenu”

GroupId=”PersonalActions”

id=”ID_PersonalActionMenu”

UseShortId=”true”

>

<SharePoint:MenuItemTemplate runat=”server” id=”ID_PersonalInformation”

Text=”<%$Resources:wss,personalactions_personalinformation%>”

Description=”<%$Resources:wss,personalactions_personalinformationdescription%>”

MenuGroupId=”100″

Sequence=”100″

ImageUrl=”/_layouts/images/menuprofile.gif”

UseShortId=”true”

/>

<SharePoint:MenuItemTemplate runat=”server” id=”ID_LoginAsDifferentUser”

Text=”<%$Resources:wss,personalactions_loginasdifferentuser%>”

Description=”<%$Resources:wss,personalactions_loginasdifferentuserdescription%>”

MenuGroupId=”200″

Sequence=”100″

UseShortId=”true”

/>

<SharePoint:MenuItemTemplate runat=”server” id=”ID_RequestAccess”

Text=”<%$Resources:wss,personalactions_requestaccess%>”

Description=”<%$Resources:wss,personalactions_requestaccessdescription%>”

MenuGroupId=”200″

UseShortId=”true”

Sequence=”200″

/>

<SharePoint:MenuItemTemplate runat=”server” id=”ID_Logout”

Text=”<%$Resources:wss,personalactions_logout%>”

Description=”<%$Resources:wss,personalactions_logoutdescription%>”

MenuGroupId=”200″

Sequence=”300″

UseShortId=”true”

/>

<SharePoint:MenuItemTemplate runat=”server” id=”ID_PersonalizePage”

Text=”<%$Resources:wss,personalactions_personalizepage%>”

Description=”<%$Resources:wss,personalactions_personalizepagedescription%>”

ImageUrl=”/_layouts/images/menupersonalize.gif”

ClientOnClickScript=”javascript:ChangeLayoutMode(true);”

PermissionsString=”AddDelPrivateWebParts,UpdatePersonalWebParts”

PermissionMode=”Any”

MenuGroupId=”300″

Sequence=”100″

UseShortId=”true”

/>

<SharePoint:MenuItemTemplate runat=”server” id=”ID_SwitchView”

MenuGroupId=”300″

Sequence=”200″

UseShortId=”true”

/>

<SharePoint:MenuItemTemplate runat=”server” id=”MSOMenu_RestoreDefaults”

Text=”<%$Resources:wss,personalactions_restorepagedefaults%>”

Description=”<%$Resources:wss,personalactions_restorepagedefaultsdescription%>”

ClientOnClickNavigateUrl=”javascript:SP.SOD.execute(‘browserScript’, ‘MSOWebPartPage_RestorePageDefault’)”

MenuGroupId=”300″

Sequence=”300″

UseShortId=”true”

/>

</SharePoint:FeatureMenuTemplate>

</CustomTemplate>

</SharePoint:PersonalActions>

<SharePoint:ApplicationPageLink runat=”server” id=”ExplicitLogin”

ApplicationPageFileName=”Authenticate.aspx” AppendCurrentPageUrl=true

Text=”<%$Resources:wss,login_pagetitle%>” style=”display:none” Visible=”false” />

</asp:Panel>

<asp:Panel runat=”server” ID=”windowsHelloitsliamPanel” style=”displa:inline;”>

<wussuc:Welcome id=”wExplicitLogout” runat=”server” />

</asp:Panel>

Now to add some “C#” code that will tie it all together. First we need to add a reference to “Microsoft.IdentityModel” so we can grab the current claims for the user. Now we need to add the following code to the “Page_Load” event of the user control. We need to check if the current login process is using Windows or not. If it is windows then we show or hide the appropriate panel.

If the login method is something other than windows then we can use the following custom code. We first check that the user is actually authenticated, then validate that it is not a post back.

Next we grab the “IClaimsPrinciple” for the current user, check if it is “null” and then if okay, grab the current identity. Next we grab the claims from the current user object and grab a specific claim in this case we are using “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.

Now need to mess around with the “PostCacheSubstitutionText” object for the welcome control. Using this method we overwrite the current rendering and have it output “Welcome {Claim}”.

Finally we add a check at the end and modify the rendering slightly if the user is not authenticated yet.

So we need to package the component now and deploy. We then need to check that it has been deployed, for this demo I validated this by checking here:

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\CONTROLTEMPLATES

Now modify the master page for the site and make the following changes to the master page, by replacing the current link to the welcome control to the custom one that has been deployed.

Now when we access the site the welcome control is rendering the following in my example:

Of course we could use any of the claims that are being sent to the server or even concatenate them to make something else. Using the claims viewer web part from the previous post I could use of the following:

SharePoint 2010 – Tips for dealing with performance issues

There can be a number of reasons for your SharePoint installation suffering from performance issues. Checkout the following tips and tricks to see if they can help get your system healthy again:

General tips

  • Get to know your application, it’s usage, and it’s response times by studying the IIS logs. One of the ways to do this is to use the free SharePoint Flavored Weblog Reader (SFWR) tool.
  • Monitor performance counters that are relevant for SharePoint. This gallery post gives an overview of a set of relevant performance counters that have been established after careful research, and a small PowerShell script for reading them. Also see for a different perspective.
    • Even if your environment is already up and running, do capacity planning. This way you can check if you’re crossing any important limits that might threaten performance. Check out here and here. Do remember that content database limits include remote BLOBs (if you use them) and that auditing has a great impact on capacity planning.
  • Use the SharePoint Diagnostic Data Provider/Logging database to get more insight into your environment. Check out here and here for more info. Also see this technet article.
  • More often than not, performance problems are caused by custom software. Demand that each piece of custom software gets shipped with a configurable diagnostics system that can be used to determine any pain points in there.
  • Study other performance and capacity test results and recommendations. See here and here.
  • The first authenticated user may experience a very poor response time. Consider warming up SharePoint.
  • Follow best practices when using the Content Query Web Part (CQWP).
SharePoint settings
  • Enable BLOB cache. See here and here.
  • Enable output cache.
  • Enable IIS compression.
  • Limit the maximum upload file size.
SQL Server
  • Use SQL DMVs to analyze the state of your SQL database server, also taking into consideration the performance of other applications unrelated to SharePoint, but hosted on the same database server.
  • If you’re allowed to: enable SQL Profiler to check SQL Server database problems on the fly.

 

  • Study the set up of the database environment, which is crucial for the success of your SharePoint environment. The SharePoint 2010 Administrator’s Companion contains an excellent chapter about this ( available on Amazon)

 

Useful SharePoint tools
  • Use System Center Operations Manager for monitoring SharePoint or a 3rd party tool like Quest Foglight for ASP. Foglight can capture trends like page load times as well as consolidate performance counters.
  • Get the SharePoint Administration Toolkit. It contains a load testing kit that can be employed to determine if an environment is able to handle the current load. It also contains SharePoint Diagnostic Studio 2010, a tool used by Microsoft personnel for troubleshooting. It’s able to capture lots of information about performance counters, ULS log files, and so on. See here for more information.
  • Get PAL, a tool for troubleshooting performance troubles. See here and here.

 

Office365
  • Use MSOCAF to check code before submitting it to Microsoft for BPOS/Office365.
Browser tools 

Add Rating Stars to the Search Results

In this article I will explain to how to add ‘Rating Stars’ to the search results. Please let me know if you find any issues while implementing it.

 

Create a custom list and enable rating

We will start with creating the list with some dummy columns and insert some data in it. I have created a ‘Employee List’ whose structure looks something like this:

 

Now we need to enable the rating to the list. Click on the list settings from the ribbon under the ‘List Tools’ Group and ‘List’ tab:

 

Now click on the ‘Rating Settings’ link under the ‘General Settings’ category:

 

Select ‘Yes’ under ‘Allow items in this list to be rated?’ and click ‘Ok’. This has successfully enabled ratings on the list and added following two columns required for rating to work.

 

  • Rating (0-5)    /   Number of Ratings
  • Rating (0-5)    /  Number of Ratings

 

If you go back to the list it would have added the Rating Column to the list:

 

Rate some entries and run the rating services

Now add rating to these entries. It wont be reflected immediately on the list, it will get updated once ‘User Profile Service Application – Social Data Maintenance Job’ and ’User Profile Service Application – Social Rating Synchronization Job’ jobs are executed. These jobs are scheduled to run every hour (By default) by the sharepoint timer services. However we can change the frequency of the this jobs. Go to:

 

Central Administration -> Monitoring -> Timer Jobs -> Review job definitions

 

Scroll down to locate the above services:

 

Click on each of the job and schedule it to run for every 1 min (Just so that we don’t have to wait for our ratings to get updated, in normal scenario running every one hour is just fine. Once this jobs are executed successfully, the ratings that you entered previously would have started reflecting:

 

Start a full crawl of the site

Now once we have to prepare our FAST search server to include the ratings in our search indexing. So go to the crawled property categories and select ‘Sharepoint’ category. Now search for ‘rating’. It should return following to crawled properties:

  • ows_averagerating(Decimal)
  • ows_ratingcount(Integer)

If it does not return the above two crawled properties, You need to start full crawl of the site where your list is located. Once the crawl is successful, sharepoint will automatically create the above crawled properties

 

Create a managed property for the ratings

As we have the crawled property created we can create a managed property for each of them and map it to crawled property. So you need to create following two managed property:

  • Rating
  • RatingCount

Below are the details of the managed property that will help you to create a managed property:

 

Start a full crawl of the site

After creating the managed property we need to full crawl the site ‘AGAIN’. Yes, When we earlier crawled the site it just recognised that two more fields are available for crawling. But managed properties were not mapped so it didnt knew where to index the data. So start the full crawl of the site, leave it as it is and proceed to the next step.

 

Modify core result webpart and it’s XSLT

Now we need to modify the search webpart of our site to display the rating stars in our search. So go to your results.aspx and then edit the page. Now edit your core results webpart. Under:

coreresultswebpart properties->Core Result -> Display Properties -> Fethced Properties

include the following lines before the </Column> tag:

 

4 <Column Name="Rating"/>
5
6 <Column Name="RatingCount"/>

 

Open the XSL Editor of the webpart by clicking on ‘XSL Editor’ button. Add the below lines of code after the Div tag of ‘<div class=”srch-Title2″>’

 

4 <div class="srch-Description">
5
6 <xsl:if test="rating &gt; 0">
7
8 <b>
9
10 <xsl:call-template name="DisplayRating">
11
12 <xsl:with-param name="theRating" select="rating" />
13
14 <xsl:with-param name="theRatingCount" select="ratingcount" />
15
16 </xsl:call-template>
17
18 </b>
19
20 <br />
21
22 </xsl:if>
23
24 </div>

 

Copy the following code before the </xsl:stylesheet> tag

 

4 <xsl:template name="DisplayRating">
5
6 <xsl:param name="theRating"/>
7
8 <xsl:param name="theRatingCount"/>
9
10 <xsl:if test="$theRating > 0">
11
12 <div style="display: inline-block; padding-left: 8px;">
13
14 <div>
15
16 <xsl:variable name="tempTitle" select="concat($theRating, ' Stars (')"/>
17
18 <xsl:variable name="tempTitle2" select="concat($theRatingCount, ' Ratings)')"/>
19
20 <xsl:variable name="ratingTitle" select="concat($tempTitle, $tempTitle2)"/>
21
22 <xsl:attribute name="title">
23
24 <xsl:value-of select="$ratingTitle"/>
25
26 </xsl:attribute>
27
28 <xsl:choose>
29
30 <xsl:when test="round($theRating) = 0 and $theRating &gt; 0">
31
32 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:
33 default;height:16px;margin:0px;background-repeat:no-repeat;background-position:-368px 0px;
34 width:16px;</xsl:attribute>
35
36 </xsl:when>
37
38 <xsl:when test="round($theRating) = 1 and round($theRating) &lt;= $theRating">
39
40 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:
41 default;height:16px;margin:0px;background-repeat:no-repeat;background-position:-352px 0px;
42 width:16px;</xsl:attribute>
43
44 </xsl:when>
45
46 <xsl:when test="round($theRating) = 2 and round($theRating) &gt; $theRating">
47
48 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:
49 default;height:16px;margin:0px;background-repeat:no-repeat;background-position:-352px 0px;
50 width:32px;</xsl:attribute>
51
52 </xsl:when>
53
54 <xsl:when test="round($theRating) = 2 and round($theRating) &lt;= $theRating">
55
56 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:
57 default;height:16px;margin:0px;background-repeat:no-repeat;background-position:-336px 0px;
58 width:32px;</xsl:attribute>
59
60 </xsl:when>
61
62 <xsl:when test="round($theRating) = 3 and round($theRating) &gt; $theRating">
63
64 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:default;
65 height:16px;margin:0px;background-repeat:no-repeat;background-position:-336px 0px;width:48px;
66 </xsl:attribute>
67
68 </xsl:when>
69
70 <xsl:when test="round($theRating) = 3 and round($theRating) &lt;= $theRating">
71
72 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:default;
73 height:16px;margin:0px;background-repeat:no-repeat;background-position:-320px 0px;width:48px;
74 </xsl:attribute>
75
76 </xsl:when>
77
78 <xsl:when test="round($theRating) = 4 and round($theRating) &gt; $theRating">
79
80 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:default;
81 height:16px;margin:0px;background-repeat:no-repeat;background-position:-320px 0px;width:62px;
82 </xsl:attribute>
83
84 </xsl:when>
85
86 <xsl:when test="round($theRating) = 4 and round($theRating) &lt;= $theRating">
87
88 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:default;
89 height:16px;margin:0px;background-repeat:no-repeat;background-position:-304px 0px;width:64px;
90 </xsl:attribute>
91
92 </xsl:when>
93
94 <xsl:when test="round($theRating) = 5 and round($theRating) &gt; $theRating">
95
96 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:default;
97 height:16px;margin:0px;background-repeat:no-repeat;background-position:-304px 0px;width:80px;
98 </xsl:attribute>
99
100 </xsl:when>
101
102 <xsl:when test="round($theRating) = 5">
103
104 <xsl:attribute name="style">background-image:url(/_layouts/images/Ratings.png);cursor:default;
105 height:16px;margin:0px;background-repeat:no-repeat;background-position:-160px 0px;width:80px;
106 </xsl:attribute>
107
108 </xsl:when>
109
110 </xsl:choose>
111
112 </div>
113
114 </div>
115
116 </xsl:if>
117
118 </xsl:template>

Click ‘Ok’ and save the page.

 

Search Results

You are ready to search for the results now! My search page something like this:

Replace “HTTP” with “HTTPS” and different URL’s for internal/external access

Working with a client recently I had the old issue of them using “http://sharepoint” for internal users and then “https://sharepoint.domain.com” for external access. Of course as you would expect SharePoint takes care of most of the issues with ensuring the URL’s for links are correct such as automatic navigation links, search results etc. However what it did not take care of as we all know is the hardcoded and manually added links to the pages and the ones that are were manually added to the master page so they were consistent across the board. This meant that when users came in from inside or outside it would either work or they would get redirected to the wrong URL for the zone they came in from. So how do we fix it? This time around I decided to use jQuery, to modify the links as then page was rendered. First I needed to ensure that the URL’s were modified with either “HTTP” or “HTTPS” depending on which URL you came in from.

 

 

This code checks whether we are using “HTTP” or “HTTPS” then iterates through the “<a>” tag references and updates them accordingly. So this fixed half but I needed to make sure that if it was using “HTTP” then the URL’s would change to the shortened “http://sharepoint“. So I used the following code:

 

 

This code ran if the current protocol was “HTTP” then for any links that contain the FQDN it stripped them out to the shortened link, this was for the “http://mysite.sharepoint.domain.com” URL’s . A similar approach was used for the URL’s that contained just the “domain.com“, also notice I added in the “HTTPS” link to “HTTP” change in the same line.

 

 

Of course these are all separate blocks of code but you can easily add them into one single loop that would check everything and modify accordingly. I found that due to me needing to check what the “HREF” contained and the order that I needed it I still needed to use one loop if running “HTTPS“, as all the links that are hardcoded are using the FQDN, and for regular “HTTP” I needed two loops in this order to modify the main ones and then the second layer of links:

 

 

I am sure there are cleaner ways of doing this, could have written something in “C#” to modify the page etc. but had to use a “no-code” solution. So does that mean that jQuery is not code?? Just kidding!