The Ribbon is completely extensible in that you can add new tabs or controls, or you can remove the out-of-the-box (OOB) controls on existing tabs. In fact, you can entirely replace the Ribbon just by using your own custom Master Page. The Ribbon does support backward compatibility in that any custom actions you created for 2007 toolbars will appear in a custom commands tab in the Ribbon.

To understand how to customize the Ribbon, look through the different actions you normally would want to perform and the way to achieve those actions. Before diving in, though, you need to get a little bit of grounding in how the architecture of the Ribbon works.

The architecture of the Ribbon allows you to perform your customizations by creating XML definition files. At runtime, the Ribbon runtime merges your XML definitions with its own to add your custom Ribbon elements and code to handle interactions. For more complex customizations, such as writing more complex code, you will want to look at using a JavaScript Page Component. The section below looks at both options.

If you want to understand how SharePoint implements its Ribbon XML elements, go to %Program Files%Common FilesMicrosoft SharedWeb Server Extensions14TEMPLATEGLOBALXML on your SharePoint Server and find the file cmdui.xml. In that file, you will see the SharePoint default Ribbon implementation, and it is a good template to look at as you implement your own Ribbon controls, because it will help you to understand how certain controls work inside of the SharePoint environment.

If all the different types, elements, and attributes get confusing, take a look at the XSD for the Ribbon by browsing to %Program Files%Common FilesMicrosoft SharedWeb Server Extensions14TEMPLATEXML and looking at cui.xsd and wss.xsd. These XSD files will help you understand what SharePoint is expecting in terms of structure and content to make your custom user interface.

The first way you will look at customizing the Ribbon is by using only XML. When you write your custom XML to define your Ribbon, SharePoint combines your XML changes with its own definitions in cmdui.xml and the merged version is used to display the new Ribbon interface. Even though you are using XML, you want to deploy your custom Ribbon XML using a SharePoint feature. So, the easiest way to get started creating a feature is by using Visual Studio 2010. Make sure to create an Empty SharePoint Project and customize the feature name and deployment path. Ribbon extensions can be Sandbox Solutions, which you will learn about later, so they can run in a restricted environment.

Once you have created your Visual Studio project, you want to create a new feature. Add a new file to your project and create an empty elements file. This is where you will place the XML for your new Ribbon interface. To understand the XML, break it down piece by piece. The snippet that follows shows some XML from a custom Ribbon:

<?xml version="1.0" encoding="utf-8"?>

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

  <CustomAction

    Id="CustomRibbonTab"

    Location="CommandUI.Ribbon.ListView"

    RegistrationId="101"

    RegistrationType="List"

Title="My Custom UI"

    Sequence="5"

>



  </CustomAction>

</Elements>

First, all of your XML for the Ribbon will be wrapped in a CustomAction node. This tells SharePoint that you want to perform customization of the user interface. For the node, there are attributes that you can set to specify the specifics for your customization. One key one is the Location attribute. The Location attribute tells SharePoint where your customization should appear, such as on a list view, on a form, or everywhere. The pattern match for the Location attribute is Ribbon.[Tab].[Group].Controls._children. Table 4-2 outlines the options for the Location attribute.

One other piece to notice in the XML is the RegistrationID. Combined together, the registration ID and the registration type define what set of content you want your custom UI to appear for. The registration type can be a list, content type, file type, or a progID. The registration ID is mostly used with the content type registration type, and it's where you specify the name of your content type. This allows you to customize even further when your custom UI will appear, depending on what is displayed in SharePoint.

The Sequence attribute, which is optional, allows extensions to be placed in a particular order within a set of subnodes of a node. The built-in tab controls use a sequence of 100, so you want to avoid using any multiples of 100 for your sequence in tabs, and groups use a sequence in multiples of 10, so avoid multiples of 10. For example, if there is a Ribbon tab with the following groups: Clipboard, Font, Paragraph, then their sequence attributes could be set to 10, 20, and 30, respectively. Then, a new group could be inserted between the Clipboard and the Font groups via the feature framework by setting its sequence attribute to 15. A node without a Sequence attribute is sorted last.

Let's expand the XML a bit more, since the current XML does nothing because you haven't added any new commands to the user interface. To add commands, you want to create a CommandUIExtension element. This CommandUIExtension is a wrapper for a CommandUIDefinitions element, which is a container for a CommandUIDefinition.

The CommandUIDefinition element has an attribute that allows you to set the location for your UI. In the example, you're adding a new button to the new set of controls in a document library. You can see _children as part of the location that tells SharePoint to not replace a control, but instead add this as a child control on that user interface element.

The CommandUIDefinition element is where you create your user interface elements, whether they are tabs, groups, or individual controls. In this simple example, you create a button that has the label Click me!, has two images for use depending on whether it's rendered in 16x16 or 32x32, and calls some JavaScript code to perform the action when the button is pressed. The attributes are self-explanatory, except for 1 - TemplateAlias. TemplateAlias controls whether your control is displayed in 16x16 or 32x32. If you set it to o1, you will get a 32x32 icon, and o2 makes it 16x16. You can define your own template, but most times you will use the built-in values of o1 or o2.

So, how do you call code from your Ribbon code? You will want to wrap your code in a CommandUIHandler, where you can put in the CommandAction attribute, which is inline JavaScript that will handle the action for your button. If you do not want to place your JavaScript inline, you can instead use the ScriptSrc attribute and pass a URL to your JavaScript file. Figure 4-3 shows our new custom button.

Figure 4.3. Figure 4-3

<CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition Location="Ribbon.Documents.New.Controls._children">
          <Button
              Id="Ribbon.Documents.New.RibbonTest"
              Alt="Test Button"
              Sequence="5"
              Command="Test_Button"
              LabelText="Click me!"
              Image32by32="/_layouts/images/ribbon_blog_32.png"
              Image16by16="/_layouts/images/ribbon_blog_16.png"
              TemplateAlias="o1" />
        </CommandUIDefinition>
      </CommandUIDefinitions>

      <CommandUIHandlers>
        <CommandUIHandler
          Command="Test_Button"
          CommandAction="javascript:alert('I am a test!')," />
      </CommandUIHandlers>

    </CommandUIExtension>

Replacing Existing Controls

There may be times when you want to replace existing, built-in controls from your SharePoint deployment and put your own control in its place. In fact, you can replace the entire Ribbon if you want. The way to replace an existing control is to insert your own custom control that overwrites the ID of the control you want to replace and also has a lower sequence number. The key thing is you have to get the Location attribute set to the exact same ID as the control ID you want to replace.

The following code replaces the new folder button for a document library. There are a couple of things to highlight in this code. First, notice the Location attribute in the CommandUIDefinition element. It maps exactly to an ID in the cmdUI.XML file. SharePoint will parse both files and if the same ID is found, the one with the lower sequence will be put into the final XML that is parsed and used to create the Ribbon layout. Also, notice the use of the $Resources for globalization and pulling from a compressed image. If you look at the formatmap on your server, you will see that it contains lots of icons and the XML code contains the coordinates to pull the new folder icon from the larger image.

<CustomAction Id="Ribbon.Documents.New.NewFolder.ReplaceButton"
      Location="CommandUI.Ribbon"
      RegistrationId="101"
      RegistrationType="List"
      Title="Replace Ribbon Button"
  >
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition
          Location="Ribbon.Documents.New.NewFolder">
          <Button Id="Ribbon.Documents.New.NewFolder.ReplacementButton"

Command="MyNewButtonCommand"
            Image16by16="/_layouts/$Resources:core,Language;/images/
            formatmap16x16.png?vk=4536"
            Image16by16Top="-240" Image16by16Left="-80"
            Image32by32="/_layouts/$Resources:core,Language;/images/
            formatmap32x32.png?vk=4536"
            Image32by32Top="-352" Image32by32Left="-448"
            ToolTipTitle="Create a New Folder"
            ToolTipDescription="Replaced by XML Custom Action"
            LabelText="My New Folder"
            TemplateAlias="o1" />
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler
          Command="MyNewButtonCommand"
          CommandAction="javascript:alert('New Folder Replaced.')," />
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>

Figure 4-4 shows our replaced button. Even though the icon image is the same, the action performed when the user clicks on the icon is our custom code.

Figure 4.4. Figure 4-4

<CustomAction
      Id="SimpleAction"
      RegistrationType="List"
      RegistrationId="104"
      ImageUrl="/_layouts/images/saveas32.png"
      Location="NewFormToolbar"
      Sequence="10"
      Title="Custom Button"
      Description="This is an announcement button."
                         >
    <UrlAction Url="javascript:alert('Itemid={ItemId} and Listid={ListId}'),"/>

  </CustomAction>

<HideCustomAction
    Id="HideNewMenu"
    Location="Microsoft.SharePoint.StandardMenu"
    GroupId="NewMenu"
    HideActionId="NewMenu">
  </HideCustomAction>

using (SPSite site = new SPSite("http://intranet.contoso.com"))
            {
            using (SPWeb web = site.RootWeb)
                {
                SPUserCustomAction action = web.UserCustomActions.Add();
                action.Location = "EditControlBlock";
                action.RegistrationType =
                SPUserCustomActionRegistrationType.FileType;
                action.RegistrationId = "docx";
                action.Title = "Custom Edit Command For Documents";
                action.Description = "Custom Edit Command for Documents";
                action.Url = "{ListUrlDir}/forms/editform.aspx?Source={Source}";
                action.Update();
                web.Update();
                site.Close();
                }
            }

Creating New Tabs and Groups

Beyond just creating buttons, you may want to add new tabs and groups. To do this, you just need to create Tab and Group elements in your code. The process is close to the same as adding a button with some minor tweaks, as you will see. Figure 4-5 shows a custom tab and group with three controls: two buttons and a combobox.

Figure 4.5. Figure 4-5

The code below shows the beginning of the new tab and group. As you can see, the XML looks very similar to earlier XML in creating a button. There is a tab defined that you will learn more about.

<!--Create new Tab and Group-->
  <CustomAction
  Id="MyCustomRibbonTab"
  Location="CommandUI.Ribbon.ListView"
  RegistrationId="101"
  RegistrationType="List">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition
          Location="Ribbon.Tabs._children">
          <Tab
            Id="Ribbon.CustomTabExample"
            Title="My Custom Tab"
            Description="This holds my custom commands!"
            Sequence="501">
            <Scaling
              Id="Ribbon.CustomTabExample.Scaling">
              <MaxSize

Id="Ribbon.CustomTabExample.MaxSize"
                GroupId="Ribbon.CustomTabExample.CustomGroupExample"
                Size="OneLargeTwoMedium"/>
              <Scale
                Id="Ribbon.CustomTabExample.Scaling.CustomTabScaling"
                GroupId="Ribbon.CustomTabExample.CustomGroupExample"
                Size="OneLargeTwoMedium" />
            </Scaling>
            ...

First, tabs support scaling, so if the page is resized, you can control how your buttons look. Scaling has a MaxSize node that is the maximum size your buttons will be and a Scaling node that will be used if the page is resized. A couple of things about the Scaling node. It has a GroupID attribute, which should point to the group that the scaling will affect. Second, it has a Size attribute, which has a descriptor of the style of your group. For example, you can have LargeLarge if you have two buttons and want both to be large buttons, or LargeMedium if you want a large and a medium button.

After creating the tab, the code then creates the group, as you can see below. A group can have commands, descriptions, and all the standard attributes that other controls have. A group is a logical container for your controls and will physically lay out the controls in your group with your description at the bottom of the group user interface. Your Group node will contain the definition for your controls that live within that group.

<Groups Id="Ribbon.CustomTabExample.Groups">
              <Group
                Id="Ribbon.CustomTabExample.CustomGroupExample"
                Description="This is a custom group!"
                Title="Custom Group"
                Sequence="52"
                Template="Ribbon.Templates.CustomTemplateExample">
          <Controls>
...

Once you have your tab and group, you create your controls just as you would if the control were an extension of an existing group. The code earlier showed how to create a button, so the code below shows you how to create a combobox as a control in your group.

A combobox has more commands than a button, since users can interact more with a combobox by selecting options from its list. Also, either you can populate a combobox box statically, as the code does, by creating menu options in the XML, or you can pass a function that SharePoint will call to populate the combobox dynamically. Look at the PopulateDynamically, PopulateOnlyOnce, and PopulateQueryCommand sections of the code, since these combined operate the combobox options.

In addition, you can set attributes, such as AllowFreeForm and InitialItem, to control whether users can type values into the combobox and select the initial item in the combobox.

<ComboBox
 Id="Ribbon.CustomTabExample.CustomGroupExample.
 Combobox"  Sequence="18"
 Alt="Ribbon.CustomTabExample.CustomGroupExample.
 Combobox_Alt"
 Command="Ribbon.CustomTabExample.CustomGroupExample.

Combobox_CMD"
 CommandMenuOpen="Ribbon.CustomTabExample.
  CustomGroupExample.Combobox_Open_CMD"
 CommandMenuClose="Ribbon.CustomTabExample.
  CustomGroupExample.Combobox_MenuClose_CMD"
 CommandPreview="Ribbon.CustomTabExample.
  CustomGroupExample.Combobox_Preview_CMD"
CommandPreviewRevert="Ribbon.CustomTabExample.
 CustomGroupExample.Combobox_PreviewRevert_CMD"
                                InitialItem="StaticComboButton1"
                                AllowFreeForm="true"
                                PopulateDynamically="false"
                                PopulateOnlyOnce="true"
                                PopulateQueryCommand="Ribbon.CustomTabExample.
                                CustomGroupExample.Combobox_PopQuery_CMD"
                                Width="125px"
                                TemplateAlias="cust3">
                    <Menu Id="Ribbon.CustomTabExample.CustomGroupExample.
                     Combobox.Menu">
                      <MenuSection
                        Id="Ribbon.CustomTabExample.CustomGroupExample.Combobox.
                         Menu.MenuSection"
                        Sequence="10"
DisplayMode="Menu32">
                        <Controls Id="Ribbon.CustomTabExample.CustomGroupExample.
                          Combobox.Menu.MenuSection.Controls">
                          <Button
                            Id="Ribbon.CustomTabExample.CustomGroupExample.
                            Combobox.Menu.MenuSection.Button1"
                            Sequence="10"
                            Command="Ribbon.CustomTabExample.CustomGroupExample.
                             Combobox.Menu.MenuSection.Button1_CMD"
                            CommandType="OptionSelection"
                            Image16by16="/_layouts/$Resources:core,Language;
                            /images/formatmap16x16.png?vk=4536"
                            Image16by16Top="-48" Image16by16Left="-112"
                            Image32by32="/_layouts/$Resources:core,Language;
                            /images/formatmap32x32.png?vk=4536"
                            Image32by32Top="-192" Image32by32Left="-32"
                            LabelText="StaticComboButton1"
                            MenuItemId="StaticComboButton1"/>
                          <Button
                            Id="Ribbon.CustomTabExample.CustomGroupExample.
                            Combobox.Menu.MenuSection.Button2"
                            Sequence="20"
                            Command="Ribbon.CustomTabExample.CustomGroupExample.
                            Combobox.Menu.MenuSection.Button2_CMD"
                            CommandType="OptionSelection"
                            Image16by16="/_layouts/$Resources:core,Language;
                           /images/formatmap16x16.png?vk=4536"
                           Image16by16Top="-32" Image16by16Left="-112"
                            Image32by32="/_layouts/$Resources:core,Language;
                            /images/formatmap32x32.png?vk=4536"
                            Image32by32Top="-384" Image32by32Left="-352"
                            LabelText="StaticComboButton2"
                            MenuItemId="StaticComboButton2"/>

</Controls>
                      </MenuSection>
                    </Menu>
                  </ComboBox>

After your controls, you can handle the commands that your controls need to respond to in your CommandUIHandlers node. For the complete listing for all the code for the commands, the tab, and the group, please refer to the sample code for this chapter.

ToolTipTitle="Tooltip Title"

ToolTipDescription="Tooltip Description"

ToolTipShortcutKey="Ctr-V, P"

ToolTipImage32by32="/_layouts/images/PasteHH.png"

ToolTipHelpKeyWord="WSSEndUser"

Writing a Page Component

So far, you have seen writing code inline in your XML in order to handle your control commands. However, SharePoint does allow you to write more complex handlers for your user interface if you need to. You should default to trying to keep your code in the XML definition if you are creating simple buttons with simple code. However, if you are creating Ribbon extensions that are dynamically populated via code; your Ribbon requires variables beyond the default ones you can get with {SiteUrl}, {ItemId}, or other similar placeholders; or your code is so long that it may make sense from a manageability standpoint to break it out separately, then you will want to look at creating a page component.

A page component is a set of JavaScript code that can handle commands from your user interface customizations. Your JavaScript has to derive from the CUI.Page.PageComponent and implement the functions in the prototype definition of the RibbonAppPageComponent. As part of this code, you can define the global commands that your page component works with. These are the tabs, groups, and commands, such as buttons, that you will handle in your page component. Additionally, you can define whether your global commands should be enabled or not through the canHandleCommand function. This is the function you want to use to enable or disable your control. For example, you may want to only enable your control if the context is correct for your control to work, such as an item being selected in the user interface or the right variables are set. If you return false to this function, your user interface will be grayed out.

Lastly, the page component allows you to handle the command so if someone clicks on your button, you can run code to handle that click.

Once you have defined all this JavaScript, you need to register your script with the PageManager that SharePoint creates so that SharePoint knows to call the script when actions are performed on the user interface.

A couple of points about the following code. First, notice how to get the selected items by using the SP.ListOperation.Selection.getSelectedItems() method. This is a good way to determine if any items are selected in the user interface so that you can enable or disable your control. You can go a step further and look for particular properties or item types by writing some more code.

Second, you could write more functions to do things like populate your drop-downs dynamically or change the buttons on your user interface. In fact, you can write your Ribbon component to perform a postback to the server that a custom .NET program can handle, so that you can avoid writing JavaScript. If you do this, you will want the command action be a postback command such as CommandAction="javascript:__doPostBack('CustomButton', '{ItemUrl}')". Then, on the backend that captures the postback, you can handle the postback in two different ways. First, you can look at the __EVENTTARGET variable in the page request variables to see if your custom command caused the postback. The other way is to spin up a Ribbon object — make sure to reference Microsoft.SharePoint.WebControls — and implement the IPostBackHandler interface. Then, you can check to see if your custom button generated the postback by deserializing the postback event using the SPRibbonPostBackCommand.DeserializePostBackEvent method, and then checking the ID of the control that generated the event to the ID of the control you were looking for. If they match, handle the event. The first method is simpler and requires less code than the second method.

Figure 4-6 shows the custom button on the Ribbon. Also, notice that there are a custom color picker and other buttons in the figure. You can see the code to implement these other buttons in the sample code for this chapter.

Figure 4.6. Figure 4-6

<CustomAction
  Id="SharedDocAction"
  RegistrationType="List"
  RegistrationId="101"
  Location="CommandUI.Ribbon.ListView">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition
         Location="Ribbon.Documents.New.Controls._children">
          <Button
           Id="CustomContextualButton"
           Alt="MyDocumentsNew Alt"
           Command="MyDocumentsNewButton"
           LabelText="ScriptBlock Button"
           ToolTipTitle="Tooltip Title"
           Image16by16="/_layouts/$Resources:core,Language;
           /images/formatmap16x16.png?vk=4536" Image16by16Top="-80"
           Image16by16Left="0"
           Image32by32="/_layouts/$Resources:core,Language;
           /images/formatmap32x32.png?vk=4536"
           Image32by32Top="-96" Image32by32Left="-64"
           ToolTipDescription="Tooltip Description"
           TemplateAlias="o1"/>
        </CommandUIDefinition>
      </CommandUIDefinitions>
    </CommandUIExtension>
  </CustomAction>

  <CustomAction
   Id="MyScriptBlock"
   Location="ScriptLink"
   ScriptBlock="
ExecuteOrDelayUntilScriptLoaded(_registerMyScriptBlockPageComponent,
 'sp.ribbon.js'),

function _registerMyScriptBlockPageComponent()
{
    Type.registerNamespace('MyScriptBlock'),

    MyScriptBlock.MyScriptBlockPageComponent =
function MyScriptBlockPageComponent_Ctr() {
        MyScriptBlock.MyScriptBlockPageComponent.initializeBase(this);
    };

    MyScriptBlock.MyScriptBlockPageComponent.prototype = {

        init: function MyScriptBlockPageComponent_init() {
        },

        _globalCommands: null,


        buildGlobalCommands:
function MyScriptBlockPageComponent_buildGlobalCommands() {

if (SP.ScriptUtility.isNullOrUndefined(this._globalCommands)) {
                this._globalCommands = [];
                this._globalCommands[this._globalCommands.length] = 'DocumentTab';
                this._globalCommands[this._globalCommands.length]
                 = 'DocumentNewGroup';
                this._globalCommands[this._globalCommands.length]
                 = 'MyDocumentsNewButton';
            }
            return this._globalCommands;
        },

        getGlobalCommands: function MyScriptBlockPageComponent_getGlobalCommands()
        {
            return this.buildGlobalCommands();
        },

        canHandleCommand: function
MyScriptBlockPageComponent_canHandleCommand(commandId) {
            var items = SP.ListOperation.Selection.getSelectedItems();
            if (SP.ScriptUtility.isNullOrUndefined(items))
                return false;
            if (0 == items.length)
                return false;
            if (commandId === 'DocumentNewTab'){
                return true;
            }
            if (commandId === 'DocumentNewGroup'){
                return true;
            }
            if (commandId === 'MyDocumentsNewButton'){
                return true;
            }
            return false;
        },

        handleCommand: function
        MyScriptBlockPageComponent_handleCommand(commandId, properties, sequence) {
            alert('You hit my button!'),
            return true;
        }
    }

    MyScriptBlock.MyScriptBlockPageComponent.get_instance =
     function MyScriptBlockPageComponent_get_instance() {
        if (SP.ScriptUtility.isNullOrUndefined(MyScriptBlock.
          MyScriptBlockPageComponent._singletonPageComponent)) {
            MyScriptBlock.MyScriptBlockPageComponent._singletonPageComponent
             = new MyScriptBlock.MyScriptBlockPageComponent();
        }
        return MyScriptBlock.MyScriptBlockPageComponent._singletonPageComponent;
    }
    MyScriptBlock.MyScriptBlockPageComponent.registerWithPageManager
         = function MyScriptBlockPageComponent_registerWithPageManager() {
        SP.Ribbon.PageManager.get_instance().addPageComponent

(MyScriptBlock.MyScriptBlockPageComponent.get_instance());
    }
    MyScriptBlock.MyScriptBlockPageComponent.unregisterWithPageManager =
    function MyScriptBlockPageComponent_unregisterWithPageManager() {
        if (false == SP.ScriptUtility.isNullOrUndefined(
         MyScriptBlock.MyScriptBlockPageComponent._singletonPageComponent)) {
            SP.Ribbon.PageManager.get_instance().removePageComponent(
         MyScriptBlock.MyScriptBlockPageComponent.get_instance());
        }
    }

    MyScriptBlock.MyScriptBlockPageComponent.registerClass(
    'MyScriptBlock.MyScriptBlockPageComponent', CUI.Page.PageComponent);
    MyScriptBlock.MyScriptBlockPageComponent.registerWithPageManager();
}">
  </CustomAction>

Adding Buttons with SPD

The easiest way to add a button to the Ribbon or your items is to use SharePoint Designer. Built right into SPD is the ability to add custom actions to your list. SPD can create these actions on the Ribbon forms, such as the display, edit, or new form for a list item, and also on a list item drop-down menu. You can customize the action performed by the button, for example, navigating to a form such as the edit form for the item, initiating a workflow, or launching a URL. In addition, you can use SPD to assign graphics to your icons, set your sequence number, and even set your Ribbon location in the same way you set the Location attribute in the Ribbon XML you saw earlier. Figure 4-7 shows the form used to tell SPD how to customize the Ribbon for your list.

Figure 4.7. Figure 4-7

public WebPartContextualInfo WebPartContextualInfo
        {
            get
            {
                WebPartContextualInfo info = new WebPartContextualInfo();
                info.ContextualGroups.Add(
                    new WebPartRibbonContextualGroup
                    {
                        Id = "Ribbon.MyContextualGroup",
                        VisibilityContext = "WebPartSelectionTest",
                        Command = "MyContextualGroupCMD"
                    }
                );
                info.Tabs.Add(
                    new WebPartRibbonTab
                    {
                        Id = "Ribbon.MyContextualGroup.MyTab",
                        VisibilityContext = "WebPartSelectionTest"
                    }
                );

                info.PageComponentId = SPRibbon.GetWebPartPageComponentId(this);
                return info;
            }
        }

private string DelayScript
        {
            get
            {
                string wppPcId = SPRibbon.GetWebPartPageComponentId(this);
                return @"
<script type=""text/javascript"">
//<![CDATA[

            function _addCustomPageComponent()
            {
                SP.Ribbon.PageManager.get_instance().addPageComponent(new
 CustomPageComponent.TestPageComponent(" + wppPcId + @"));
            }

            function _registerCustomPageComponent()

{
                RegisterSod(""testpagecomponent.js"",
""/_layouts/TestPageComponent.js"");
                var isDefined = ""undefined"";
                try
                {
                    isDefined = typeof(CustomPageComponent.TestPageComponent);
                }
                catch(e)
                {
                }
                EnsureScript(""testpagecomponent.js"",isDefined,
_addCustomPageComponent);
            }
            ExecuteOrDelayUntilScriptLoaded(_registerCustomPageComponent,
""sp.ribbon.js"");
//]]>
</script>";
            }
        }

private void AddCustomTab()
        {

            Microsoft.Web.CommandUI.Ribbon ribbon = SPRibbon.GetCurrent(this.Page);
            XmlDocument xmlDoc = new XmlDocument();

            //Contextual Tab
            xmlDoc.LoadXml(this.CuiDefinitionCtxTab);
            ribbon.RegisterDataExtension(xmlDoc.FirstChild,
"Ribbon.ContextualTabs._children");
            xmlDoc.LoadXml(this.CuiDefinitionScaling);
            ribbon.RegisterDataExtension(xmlDoc.FirstChild,
"Ribbon.Templates._children");
            exists = true;

        }

protected override void OnPreRender(EventArgs e)
        {
            base.OnPreRender(e);

            //RegisterDataExtensions; add Ribbon XML for buttons
            this.AddCustomTab();

            ClientScriptManager csm = this.Page.ClientScript;
            csm.RegisterClientScriptBlock(this.GetType(),
"custompagecomponent", this.DelayScript);
        }

Type.registerNamespace('CustomPageComponent'),

////////////////////////////////////////////////////////////////////////////////
// CustomPageComponent.TestPageComponent
var _myWpPcId;
CustomPageComponent.TestPageComponent = function
CustomPageComponent_TestPageComponent(webPartPcId) {
    this._myWpPcId = webPartPcId.innerText;
    CustomPageComponent.TestPageComponent.initializeBase(this);
}
CustomPageComponent.TestPageComponent.prototype = {

    init: function CustomPageComponent_TestPageComponent$init() {
    },

    getFocusedCommands: function
CustomPageComponent_TestPageComponent$getFocusedCommands() {
        return ['MyTabCMD', 'MyGroupCMD', 'CommandMyJscriptButton'];
    },

    getGlobalCommands: function
CustomPageComponent_TestPageComponent$getGlobalCommands() {
        return [];
    },

    isFocusable: function CustomPageComponent_TestPageComponent$isFocusable() {
        return true;
    },

    receiveFocus: function CustomPageComponent_TestPageComponent$receiveFocus() {
        return true;
    },

    yieldFocus: function CustomPageComponent_TestPageComponent$yieldFocus() {
        return true;
    },

    canHandleCommand: function
CustomPageComponent_TestPageComponent$canHandleCommand(commandId) {

//Contextual Tab commands
        if ((commandId === 'MyTabCMD') || (commandId === 'MyGroupCMD') ||
(commandId === 'CommandMyButton') ||
        (commandId === 'CommandMyJscriptButton')) {
            return true;
        }
    },

    handleCommand: function CustomPageComponent_TestPageComponent$handleCommand
(commandId, properties, sequence) {

        if (commandId === 'CommandMyJscriptButton') {
            alert('Event: CommandMyJscriptButton'),
        }
    },

    getId: function CustomPageComponent_TestPageComponent$getId() {
        return this._myWpPcId;
    }
}


CustomPageComponent.TestPageComponent.registerClass(
'CustomPageComponent.TestPageComponent', CUI.Page.PageComponent);
if(typeof(NotifyScriptLoadedAndExecuteWaitingJobs)!="undefined")
NotifyScriptLoadedAndExecuteWaitingJobs("testpagecomponent.js");

The status bar is extensible through both client- or server-side code. The message you can deliver in the bar is HTML, so it can be styled and contain links and images. In addition, the bar can have four different preset colors, depending on the importance of the message. To work with the status bar, you want to use the SP.UI.Status class. It is a pretty simple client-side API, since it contains only five methods, and you can find their definitions in SP.debug.js. On the server side, you will want to use the SPPageStatusSetter class, which is part of the Microsoft.SharePoint.WebControls namespace. That API is even simpler in that you call one method — AddStatus. You can also use the SPPageStateControl class to work with the status bar on the server side. Table 4-3 outlines the five methods for the client side.

Programming the status bar is straightforward. The sample code with this chapter includes a snippet that you can add to the HTML source for a content editor web part. Once you do this, you will see what appears in Figure 4-8.

Figure 4.8. Figure 4-8

<script type="text/javascript">

var sid;
var color="";

function AppendStatusMethod()
{
   SP.UI.Status.appendStatus(sid, "Appended:", "<HTML><i>My Status Append to "
+ sid + " using appendStatus</i></HTML>");
}

function UpdateStatus()
{
   SP.UI.Status.updateStatus(sid, "Updated: HTML updated for " + sid +
" using updateStatus");
}

function RemoveStatus()
{
   SP.UI.Status.removeStatus(sid);
}

function RemoveAllStatus()
{
   SP.UI.Status.removeAllStatus(true);
}


function SetStatusColor()
{
   if (color=="")
   {
     color="red";
   }
   else if (color=="red")
   {
     color="green";
   }
   else if (color=="green")
   {
     color="yellow";
   }
   else if (color=="yellow")
   {
     color="blue";
   }
   else if (color=="blue")
   {
     color="red";
   }

   SP.UI.Status.setStatusPriColor(sid, color);
}

function AppendStatus()
{

SP.UI.Status.addStatus("Appended:", "<HTML><i>
My Status Message Append using atBeginning</i></HTML>", false);
}


function CreateStatus()
{
    return SP.UI.Status.addStatus(SP.Utilities.HttpUtility.htmlEncode(
"My Status Bar Title"), "<HTML><i>My Status Message</i></HTML>", true);
}

}
</script>
<input onclick="sid=CreateStatus();alert(sid);" type="button" value="
Create Status"/> <br/>
<input onclick="AppendStatus()" type="button"
value="Append Status using atBeginning"/> <br/>
<input onclick="AppendStatusMethod()" type="button"
value="Append Status using appendStatus"/> <br/>
<input onclick="UpdateStatus()" type="button"
value="Update Status using updateStatus"/> <br/>
<input onclick="SetStatusColor()" type="button" value="Cycle Colors"/> <br/>
<input onclick="RemoveStatus()" type="button" value="Remove Single Status"/> <br/>
<input onclick="RemoveAllStatus()" type="button" value="Remove All Status"/> <br/>

Beyond working with status information, you can also customize the notification area on the upper-right side of the screen below the Ribbon. Given that SharePoint is now leveraging a lot of AJAX, there was a need to give users feedback that their pages and actions were completed. The notification area does this by telling the user that the page is loading or that a save was successful, which used to be indicated by a postback and page refresh.

The notification API is limited in that you can just create and remove notifications. Table 4-4 describes the methods for SP.UI.Notify that work with notifications, with sample code below the table.

<script type="text/javascript">

var notifyid;
function CreateNotification()
{
   notifyid = SP.UI.Notify.addNotification("My HTML Notification", true,
"My Tooltip", "HelloWorld");
   alert("Notification id: " + notifyid);
}

function RemoveNotification()
{
   SP.UI.Notify.removeNotification(notifyid);
}
</script>
<input onclick="CreateNotification()" type="button"
value="Create Notification"/><br/>
<input onclick="RemoveNotification()" type="button" value="Remove Notification"/>

If you look in SP.UI.Dialog.debug.js, you will see the implementation for the dialog framework. The framework has a JavaScript API that you can program against to have SharePoint launch and load your own dialogs. The way you do this is by calling the SP.UI.showModalDialog method and passing in the options you want for your dialog, such as height, width, page to load, and other options. You can see the full set of options in Table 4-5.

Now that you know the options you can pass to the showModalDialog function, programming a dialog is straightforward. A couple of tips before you look at the code. First, if you are going to use URLs, take a look at the SP.Utilities.Utility namespace. This namespace has a number of utilities to help you find the right places from which to grab your URLs no matter where your code is running. One utility you will see used in the code is SP.Utilities.Utility.getLayoutsPageUrl('customdialog.htm'), which gets the URL to the _layouts folder so that the custom dialog HTML file can be retrieved.

Another tip is that dialogs support the Source=url querystring variable like the rest of SharePoint. So, if you want to have SharePoint redirect to another page, you can specify the source along the query string and SharePoint will respect that.

Looking at the following code, you will see the function OpenDialog. As part of this function, a variable called options is created, which uses the SP.UI.$create_DialogOptions method. This method returns a DialogOptions object that you can use to specify your options. In the code, all the options are specified, including the creation of the delegate that points to the function — CloseCallback — that will be called after the dialog is called. Then, the code calls the SP.UI.ModalDialog.showModalDialog with the options object that contains the specified options for the dialog.

If you look at the CloseCallback function, you will see that it gets the result and any return value. The result will be the button the user clicked. SharePoint has an enumeration for the common buttons OK and Cancel that you can check against with the result value — for example, SP.UI.DialogResult.OK or SP.UI.DialogResult.cancel.

function OpenDialog()
{
  var options = SP.UI.$create_DialogOptions();

  options.url = SP.Utilities.Utility.getLayoutsPageUrl('customdialog.htm'),
  options.url += "?Source=" + document.URL;
  alert('Navigating to dialog at: ' + options.url);
  options.width = 400;
  options.height = 300;
  options.title = "My Custom Dialog";

  options.dialogReturnValueCallback = Function.createDelegate(null, CloseCallback);
  SP.UI.ModalDialog.showModalDialog(options);
}

function CloseCallback(result, returnValue)
{
  alert('Result from dialog was: '+ result);
  if(result === SP.UI.DialogResult.OK)
  {
    alert('You clicked OK'),
  }
  else if (result == SP.UI.DialogResult.cancel)
  {
    alert('You clicked Cancel'),
  }
}

Now that you have seen the code for calling the dialog and evaluating the result, look at what the HTML for the dialog body looks like. The code that follows is the code for the dialog loaded by SharePoint. A couple of things to note in the code: First, there are two buttons for OK and Cancel, respectively. If you look at the onclick event handlers for the button, you will notice that they use methods from the window.frameElement object. By using this object, you can get methods from the dialog framework. As you can see, commitPopup will return OK, and cancelPopUp will return Cancel as the result of your dialog. Table 4-6 shows the methods you want to use from the frameElement.

<p>
<img src="/_layouts/1033/images/DefaultPageLayout.gif" alt="Default Page"
style="vertical-align: middle"/>
<B>Text for your dialog goes here</B>
</p>

<input type="button" name="OK" value="OK"
onclick="window.frameElement.commitPopup();
return false;" accesskey="O" class="ms-ButtonHeightWidth" target="_self" />

<input type="button" name="Cancel" value="Cancel"
onclick="window.frameElement.cancelPopUp();
return false;" accesskey="C" class="ms-ButtonHeightWidth" target="_self" />

To work with themes, there is a new class in the Microsoft.SharePoint.Utilities namespace, called ThmxTheme, that provides methods and properties that make programming with themes easier. This class allows you to create new themes and query existing themes in the system. Table 4-8 outlines the important methods and properties of the ThmxTheme class with supporting sample code below the table to show you how to use this class.

using (SPSite site = new SPSite("http://intranet.contoso.com"))
            {
                //Get all the themes for the site

                foreach (ThmxTheme theme in ThmxTheme.GetManagedThemes(site))
                {
                    //Get Azure hyperlink color
                    if (theme.Name == "Azure")
                    {
                        MessageBox.Show(theme.HyperlinkColor.DefaultColor.Name +
" " + theme.HyperlinkColor.DefaultColor.ToString());
                    }
                }

//Upload a new theme from the file system
                FileStream fs = File.Open(
"c:\users\administrator\desktop\test.thmx",FileMode.Open);


                ThmxTheme newtheme = ThmxTheme.Open(
fs,FileMode.Open, FileAccess.ReadWrite);
                newtheme.Name = "My Test Theme";
                newtheme.HyperlinkColor.DefaultColor = Color.Black;

                newtheme.Save();
}

Before diving into the new enhancements in lists, you need to first look at the tools used to create your lists. The tools of choice are SharePoint Designer (SPD) and Visual Studio (VS). Both are good choices, depending on what you are trying to do. If you want barebones, down to the metal, XML-style creation of lists, then Visual Studio will be your choice. If you would rather work with a GUI, SPD provides a nice interface to work with your lists, whether it is creating columns or views, or customizing your list settings. Of course, you can use the built-in list settings in SharePoint to work with your lists, but SPD would be a better choice if you are interested in a GUI editor.

Diving into SPD, SPD makes it easy to work with your lists, whether it's creating new lists or modifying your existing lists. SPD can make quick work of your columns, views, forms, content types, workflows, and even custom actions for your list. If you need to rapidly create a list or list definition, SPD is going to be the fastest and easiest way to work with your SharePoint lists. You will have to give up some control, since SPD does not allow you to get down to the same level of customization that Visual Studio does, but you trade customizability for speed when you work with SPD. Figure 4-11 shows the List Settings user interface for SPD.

Figure 4.11. Figure 4-11

With Visual Studio, you can create list definitions and list instances. List definitions are a built-in project type for Visual Studio.

One common complaint about SharePoint is how it does not behave like a relational database. For example, if you have a lookup between two lists and you want to have some referential integrity, SharePoint previously would not block or cascade your deletes between your lists. With 2010, SharePoint now can block or cascade your deletes between lists automatically. Now, don't think SharePoint is going to become your replacement for SQL Server with this functionality. It is implemented more to make simple relationships work, and if you have a very complex data model, you will want to use SQL Server and surface SQL Server through SharePoint, using Business Connectivity Services (BCS) and external lists.

The way that list relationships work is you create a lookup between your lists. One new thing about lookups in a list is that you can retrieve more than just the identifier and can retrieve additional properties from the list such as built-in or custom fields. On the list where you create your lookup, you can enforce the relationship behavior to either restrict deleting parent list items if items exist in the list that are related to the parent item, or cascade the delete from the parent list to the child list. Figure 4-12 shows the user interface for setting the properties of the lookup column to enforce relationship behaviors.

Figure 4.12. Figure 4-12

If you restrict the delete, SharePoint will throw an error telling the user that there is an item in the related list that exists and will cancel deleting the error, as shown in Figure 4-13.

Figure 4.13. Figure 4-13

If you cascade the delete, SharePoint will perform a transacted delete of the related items in the related list.

Please note that through the user interface you cannot create cross-web lookups, but through the object model and by using Site Columns, you can. Cross-web lookups will not support the referential integrity features such as cascading delete. Also, referential integrity will not be enforced for a lookup that you allow to have multiple values.

When working with the object model, you want to use the RelationshipDeleteBehavior property on your SPFieldLookup object. This property takes a value from the SPRelationshipDeleteBehavior enumerator of which the possible values are None, Cascade, or Restrict.

If you look at the SPWebApplication class, you will see two properties that affect relationships. The first property is CascadeDeleteMaximumItemLimit, which allows you to specify as an integer the maximum number of cascaded items that SharePoint will delete. By default, this value is 1000 items. The other property is CascadeDeleteTimeoutMultiplier, which allows you to specify as an integer the timeout, which is 120 seconds by default.

To find lookup fields, you can use the GetRelatedFields method of your list, which returns a SPRelatedFieldCollection collection. From this collection, you can iterate through each related field. From there, you can retrieve properties, such as the LookupList that the field is related to, the ListID, the FieldID, or the relationship behavior when something is deleted from the list.

using (SPSite site = new SPSite("http://intranet.contoso.com"))
            {


                SPList list = site.AllWebs[""].Lists["Orders"];
                SPRelatedFieldCollection relatedFields = list.GetRelatedFields();
                foreach (SPRelatedField relatedField in relatedFields)
                {
                    //Lookup the list for each

                    SPList relatedList = relatedField.LookupList;
                    MessageBox.Show(relatedField.ListId + " " +
 relatedField.FieldId);
                    //MessageBox.Show("List Name: " +
relatedList.Title + " Relationship Behavior: " +
relatedField.RelationshipDeleteBehavior.ToString());


                }
}

Another new list feature is the ability to do list validation using formulas. This is more of an end user or power user feature, but for simple validation scenarios, developers will find this feature easy to use, and quick to write formulas rather than writing code. You can write validation at either the list level or the column level, depending on your needs. SharePoint also supports this approach for site columns that you add to your content types. Figure 4-14 shows setting the formula, and Figure 4-15 shows the custom error message that appears when the formula does not validate.

Figure 4.14. Figure 4-14

Figure 4.15. Figure 4-15

One of the easiest ways to understand what formulas you can enter into the validation rules is to connect Microsoft Access to your SharePoint list and use the formula editor in Access. SharePoint supports the same formula functions as Access, so you can use string manipulation, logic, financial, conversion, and date/time functionality. In the API, you will use the SPList.ValidationFormula and SPField.ValidationFormula properties to get and set your formulas.

Another new feature of lists is the ability to ensure uniqueness for the values in your columns. SharePoint would previously allow you to not require unique values so that multiple items could have the same value for a field. With uniqueness, SharePoint can use the field as an index to make lookups faster because the field is guaranteed to have a unique value.

Just like a database, SharePoint supports list joins. Again, SharePoint won't provide as much functionality as a relational database, since its data model sits above the bare-metal database, but compared to 2007 the join functionality is a welcome addition. SharePoint can perform left and inner joins but not right joins. An inner join is where you combine the values from the datasources based on the join predicate, such as "show me all employees who are in a particular department based on their department ID," which joins an employee list and a department list, both of which have department IDs in them. A left join or left outer join just means that anything that appears in the leftmost list, even if it does not exist in the other list, will be returned in the result set.

The code below performs a join across two lists on a lookup field. You need to set the Joins property on your SPQuery object with the join you want to perform. In the code, you are joining on the Customers list, where the customer is the same as the Customer in the Orders list.

Beyond setting the Joins property, you must specify a value for the ProjectedFields property. This property gets fields from the lookup list. You can alias the field by using the Name attribute and tell SharePoint the field name by using the ShowField attribute. Once you get back your results, you will have to use the SPFieldLookupValue object to display the values for your projected fields.

SPList OrderList = web.Lists["Orders"];
            SPQuery CustomerQuery = new SPQuery();
            CustomerQuery.Joins =
                "<Join Type='INNER' ListAlias='Customers'>" +
                        "<Eq>" +
                            "<FieldRef Name='Customer' RefType='Id' />" +
                            "<FieldRef List='Customers' Name='ID' />" +
                        "</Eq>" +
                "</Join>";
            StringBuilder ProjectedFields = new StringBuilder();
            ProjectedFields.Append("<Field Name='CustomerTitle'
Type='Lookup' List='Customers' ShowField='Title' />");
            ProjectedFields.Append("<Field Name='CustomerAddress'
Type='Lookup' List='Customers' ShowField='CustomerNum' />");
            CustomerQuery.ProjectedFields = ProjectedFields.ToString();
            SPListItemCollection Results = OrderList.GetItems(CustomerQuery);
            foreach (SPListItem Result in Results)
                {
                SPFieldLookupValue CustomerTitle = new
 SPFieldLookupValue(Result["CustomerTitle"].ToString());
                SPFieldLookupValue CustomerAddress = new
 SPFieldLookupValue(Result["CustomerAddress"].ToString());

                MessageBox.Show(Result.Title + " " + CustomerTitle.LookupValue + "
 " + CustomerAddress.LookupValue);

                }

One of the new features for lists is the ability to customize the default forms for your list items. SharePoint 2010 moves to using web part pages for the default forms, so your customization can be as easy as adding new web parts to the existing default forms, or you can even replace the default forms with your own custom InfoPath forms. With 2010, you can modify the New, Display, and Edit forms. For more on forms, take a read through Chapter 9.

When you use the Ribbon option to edit the form in InfoPath, InfoPath will automatically be launched, connect to your list, and display your form as shown in Figure 4-16.

Figure 4.16. Figure 4-16

The first step in getting starting with SPLINQ is generating the entity classes and properties for your lists. Rather than writing these by hand, you can use the command-line tool that ships with SharePoint, called SPMetal. SPMetal will parse your lists and generate the necessary classes for you that you can import into your Visual Studio projects. You can find SPMetal at %ProgramFiles%Common FilesMicrosoft Sharedweb server extensions14 BIN. You can run SPMetal from the command prompt, but if you prefer, you can write a batch file that you have Visual Studio run as part of your pre-build for your project so that the latest version of your entity classes are always included.

Using SPMetal is straightforward for the common scenarios that you will want to do. It does support XML customization, but most of the time you will find that you do not need to customize the default code generation. Table 4-11 shows the SPMetal command-line parameters that you can pass.

The following code snippet shows you some of the generated code, but to give you an idea of the work SPMetal does for you, the complete code for even a simple SharePoint site is over 3000 lines long! You will definitely want to use SPMetal to generate this code and tweak SPMetal as you need to in order to meet your requirements.

/// <summary>
        /// Use the Announcements list to post messages on the home page of your site.
        /// </summary>
        [Microsoft.SharePoint.Linq.ListAttribute(Name="Announcements")]
        public Microsoft.SharePoint.Linq.
EntityList<AnnouncementsAnnouncement> Announcements {
               get {
                       return this.GetList<AnnouncementsAnnouncement>("Announcements");

}
        }

/// <summary>
/// Create a new news item, status or other short piece of information.
/// </summary>
[Microsoft.SharePoint.Linq.ContentTypeAttribute(Name="Announcement", Id="0x0104")]
[Microsoft.SharePoint.Linq.DerivedEntityClassAttribute
(Type=typeof(AnnouncementsAnnouncement))]
public partial class Announcement : Item {

       private string _body;

        private System.Nullable<System.DateTime> _expires;

       #region Extensibility Method Definitions
       partial void OnLoaded();
       partial void OnValidate();
       partial void OnCreated();
       #endregion

       public Announcement() {
               this.OnCreated();
        }

        [Microsoft.SharePoint.Linq.ColumnAttribute(Name="Body",
Storage="_body", FieldType="Note")]
        public string Body {
               get {
                       return this._body;
               }
               set {
                       if ((value != this._body)) {
                              this.OnPropertyChanging("Body", this._body);
                              this._body = value;
                              this.OnPropertyChanged("Body");
                      }
               }
       }

        [Microsoft.SharePoint.Linq.ColumnAttribute(Name="Expires", Storage="_expires",
FieldType="DateTime")]
       public System.Nullable<System.DateTime> Expires {
               get {
                      return this._expires;
               }
               set {
                      if ((value != this._expires)) {
                              this.OnPropertyChanging("Expires", this._expires);
                              this._expires = value;
                              this.OnPropertyChanged("Expires");
                      }
               }
       }
}

One thing you may realize is that SPMetal, by default, does not generate all the fields for your content types. So, you may find that fields such as Created or ModifiedBy do not appear in the types created by SPMetal. To add these fields, you can specify them in a Parameters.XML. The example that follows adds some new fields to the contact content type.

<?xml version="1.0" encoding="utf-8"?>
<Web xmlns="http://schemas.microsoft.com/SharePoint/2009/spmetal">
  <ContentType Name="Contact" >
    <Column Name="CreatedBy" />
    <Column Name="ModifiedBy"/>
  </ContentType>
  </Web>

Once you have your generated SPMetal code imported into VS, it's time to make sure you have the right references set up to use that code. You will want to add two references at a minimum. The first is a reference to Microsoft.SharePoint, which is the general SharePoint namespace. The second is a reference to the specific SharePoint LINQ assembly using Microsoft.SharePoint.Linq. This will add all the necessary dependent LINQ assemblies to your project.

The DataContext object is the object that provides the heart of your LINQ programming. Your DataContext object will be named whatever you named the beginning of your generated file from SPMetal. For example, if you had SPMetal create a LINQDemo.cs file for your outputted code, your DataContext object will be LINQDemoDataContext. To create your DataContext object, you can pass along the URL of the SharePoint site to which you want to connect.

Once you have your DataContext object, you can start working with the methods and properties of that object. The DataContext will contain all your lists and libraries as EntityList properties. You can retrieve these lists and libraries and then work with them. Table 4-12 lists the other methods and properties you will use from the DataContext object.

As part of SPMetal, you will get autogenerated typed data classes and relationships using the Association attribute. This allows you to use strongly typed objects for your lists and also to do queries across multiple lists that are related by lookup fields. As you will see in the examples, this makes programming much cleaner and also allows you catch compile-time errors when working with your objects, rather than runtime errors.

To query and enumerate your data, you need to write LINQ queries. When you write your queries, you need to understand that LINQ translates the query into CAML, so if you try to perform LINQ queries that cannot be translated into CAML, SharePoint will throw an error. SharePoint considers these inefficient queries, and the only way to work around them is to use LINQ to Objects and perform the work yourself. The following is a list of the unsupported operators that SharePoint will error on:

The simplest query you can write is a select from your list. The following code performs a select from a list and then enumerates the results:

var context = new LinqDemoDataContext("http://intranet.contoso.com");
var orderresults = from orders in context.Orders
                   select orders;

foreach (var order in orderresults)
{
    MessageBox.Show(order.Title + " " + order.Customer);
}

As you can see in the code, you first need to get your DataContext object. From there, you define your LINQ query as you do against any other datasource. Once you have the results, you can enumerate them using a foreach loop. If you want, you can also use the ToList method to return a generic list that you can perform LINQ to Object operations on.

You can add where clauses to your queries to perform selection. For example, if in the query above you wanted to select only orders that were more than $1000 dollars, you would change the query to the following one:

var orderresults = from orders in context.Orders
                               where orders.Total > 1000
                               select orders;

For the next example, the query will perform a simple INNER join between two lists that share a lookup field. Since CAML now supports joins, this is supported in LINQ as well. A couple of things to note. First, you'll notice that you get the EntityList objects for the two lists that you will join, so you can use them in the query. Then, in the query, you just use the join operator to join the two lists together on a lookup field. From there, the code uses the ToList method on the query results so that you can get back a LINQ to Object collection that you can iterate over.

var context = new LinqDemoDataContext("http://intranet.contoso.com");


            EntityList<OrdersItem> Orders = context.GetList<OrdersItem>("Orders");

EntityList<CustomersItem> Customers = context.GetList<CustomersItem>
("Customers");

            var QueryResults = from Order in Orders
                               join Customer in Customers on Order.Customer.Id
 equals Customer.Id
                               select new { CustomerName = Customer.Title,
 Order.Title, Order.Product };

            var Results = QueryResults.ToList();
            if (Results.Count > 0)
            {

                Results.ForEach(result => MessageBox.Show(result.Title + " " +
 result.CustomerName + " " + result.Product));
            }
            else
            {
                MessageBox.Show("No results");
            }

                }

LINQ allows you to add, delete, and update your data in SharePoint. Since LINQ is strongly typed, you can just create new objects that map to the type of the new objects you want to add. Once the new object is created, you can call the InsertOnSubmit method and pass the new object or the InsertAllOnSubmit method and pass a collection of new objects. Since LINQ works asynchronously from the server with a local cache, you need to call SubmitChanges after all modifications to data through LINQ.

To update items, it's a matter of updating the properties on your objects and then calling SubmitChanges. For deleting, you need to call DeleteOnSubmit or DeleteAllOnSubmit, passing either the object or a collection of objects, and then call SubmitChanges.

Since LINQ does not directly work against the SharePoint store, changes could be made to the backend while your code is running. To handle this, SharePoint LINQ provides the ability to catch exceptions if duplicates are present, if conflicts are detected, or general exceptions. The code that follows shows how to code for all of these cases. One thing to note is that the code uses the ChangeConflict exception and then enumerates all the ObjectChangeConflict objects. Then, it looks through the MemberConflict objects, which contain the differences between the database fields and the LINQ object fields. Once you decide what to do about the discrepancies, you can resolve the changes with the ResolveAll method. The ResolveAll method takes a RefreshMode enumeration, which can contain one of three values: KeepChanges, KeepCurrentValues, or OverwriteCurrentValues. KeepChanges keeps the new values since retrieval, even if they are different than the database values, and keeps other values the same as the database. Another choice is KeepCurrentValues, which keeps the new values since retrieval, even if they are different from the database values and keeps other values the same as they were retrieved, even if they conflict with the database values. OverwriteCurrentValues keeps the values from the database and discards any changes since retrieval. You need to call SubmitChanges after resolving any conflicts to save changes.

try
            {
                EntityList<OrdersItem> Orders =
 context.GetList<OrdersItem>("Orders");
                OrdersItem order = new OrdersItem();
                order.Title = "My LINQ new Order";
                order.Product = "Chai";

                //Add a lookup to Customers
                EntityList<CustomersItem> Customers =
context.GetList<CustomersItem>("Customers");
                var CustomerTempItem = from Customer in Customers
                               where Customer.Title == "Contoso"
                               select Customer;

                CustomersItem CustomerItem = null;
                foreach (var Cust in CustomerTempItem)
                    CustomerItem = Cust;

                order.Customer = CustomerItem;

                Orders.InsertOnSubmit(order);
                context.SubmitChanges();

                //Delete the item
                Orders.DeleteOnSubmit(order);
                context.SubmitChanges();

            }
            catch (ChangeConflictException conflictException)
            {
                MessageBox.Show("A conflict occurred: " +
 conflictException.Message);
                foreach (ObjectChangeConflict Items in context.ChangeConflicts)
                {
                    foreach (MemberChangeConflict Fields in Items.MemberConflicts)
                    {
                        StringBuilder sb = new StringBuilder();
                        sb.AppendLine("Item Name: " + Fields.Member.Name);
                        sb.AppendLine("Original Value: " + Fields.OriginalValue);
                        sb.AppendLine("Database Value: " + Fields.DatabaseValue);
                        sb.AppendLine("Current Value: " + Fields.CurrentValue);
                        MessageBox.Show(sb.ToString());
                    }
                }

                //Force all changes
                context.ChangeConflicts.ResolveAll(RefreshMode.KeepChanges);
                context.SubmitChanges();

            }

catch (SPDuplicateValuesFoundException duplicateException)
            {
                MessageBox.Show("Duplicate value found: " +
 duplicateException.Message);
            }
            catch (SPException SharePointException)
            {
                MessageBox.Show("SharePoint Exception: " +
 SharePointException.Message);
            }
            catch (Exception ex)
            {
                MessageBox.Show("Exception: " + ex.Message);
            }

        }

If you want to inspect the CAML query that LINQ is generating for you, you can use the Log property and set that to a TextWriter or an object that derives from the TextWriter object, such as a StreamWriter object. If you are writing a console application, the easiest way to set the Log property is to set it to the Console.Out property. From there, you can retrieve the CAML query that SharePoint LINQ would execute on your behalf. The following code shows how to write a log file for your LINQ query using the Log property, and then shows the CAML query that is generated by LINQ.

var context = new LinqDemoDataContext("http://intranet.contoso.com");

            context.Log = new StreamWriter(File.Open("C:\SPLINQLog.txt",
FileMode.Create));



            EntityList<OrdersItem> Orders = context.GetList<OrdersItem>("Orders");
            EntityList<CustomersItem> Customers =
context.GetList<CustomersItem>("Customers");

            var QueryResults = from Order in Orders
                               join Customer in Customers on Order.Customer.Id
 equals Customer.Id
                               select new { CustomerName = Customer.Title,
 Order.Title, Order.Product };

            context.Log.WriteLine("Results :");

            var Results = QueryResults.ToList();
            if (Results.Count > 0)
            {

                Results.ForEach(result => context.Log.WriteLine(result.Title

+ " " + result.CustomerName + " " + result.Product));
            }
            else
            {
                context.Log.WriteLine("No results");
            }

            context.Log.Close();
            context.Log = null;

OUTPUT:

<View><Query><Where><And><BeginsWith><FieldRef Name="ContentTypeId" /><Value
Type="ContentTypeId">0x0100</Value></BeginsWith><BeginsWith><FieldRef
Name="CustomerContentTypeId" /><Value
Type="Lookup">0x0100</Value></BeginsWith></And></Where><OrderBy
Override="TRUE" /></Query><ViewFields><FieldRef Name="CustomerTitle"
 /><FieldRef Name="Title" /><FieldRef Name="Product"
/></ViewFields><ProjectedFields><Field Name="CustomerTitle" Type="Lookup"
List="Customer" ShowField="Title" /><Field Name="CustomerContentTypeId"
Type="Lookup" List="Customer" ShowField="ContentTypeId"
/></ProjectedFields><Joins><Join Type="INNER" ListAlias="Customer"><!--List
Name: Customers--><Eq><FieldRef Name="Customer" RefType="ID" /><FieldRef
List="Customer" Name="ID" /></Eq></Join></Joins><RowLimit
Paged="TRUE">2147483647</RowLimit></View>

One best practice is to turn off object tracking if you are just querying the list and are not planning to add, delete, or update items in the list. This will make your queries perform better, since LINQ will not have the overhead of trying to track changes to the SharePoint objects. The way to turn off object tracking is to set the ObjectTrackingEnabled property to false on your DataContext object.

If you do need to make changes to the list, you can open another DataContext object to the same list with object change tracking enabled. LINQ allows two DataContext objects to point at the same website and list, so you can have one DataContext object for querying and another for writing to the list.

There are still definite times when you should revert to using CAML directly. One scenario is where performance is paramount. LINQ makes CAML programming much easier, but no matter how LINQ is optimized, it will add some overhead to your code. Another example is if you have large amounts of adds, deletes, or updates that you need to perform. CAML will provide better performance in this scenario.

Before diving into writing code with the client OM and adding references in VS, you first need to understand where these DLLs are located and some of the advantages of the DLLs, especially size. As with other SharePoint .NET DLLs, you will find the .NET DLLs for the client OM located under %Program Files%Common FilesMicrosoft SharedWeb Server Extensions14ISAPI. There are two DLLs for the managed OM, Microsoft.SharePoint.Client and Microsoft.SharePoint.Client.Runtime. If you look at these DLLs in terms of size, combined they are under 1MB. Compare that with Microsoft.SharePoint, which weighs in at over a hefty 15MB.

Since the ECMAScript implementation is different from the .NET one and needs to live closer to the web-based code for SharePoint, this DLL is located in %Program Files%Common FilesMicrosoft SharedWeb Server Extensions14TEMPLATELAYOUTS. There, you will find three relevant JS files, SP.js, SP.Core.js, SP.Ribbon.js, and SP.Runtime.js. Of course, when you are debugging your code, you will want to use the debug versions of these files, such as SP.debug.js, since the main versions are crunched to save on size and bandwidth. Also, you can set your SharePoint deployment to use the debug versions of these files automatically by changing the web.config file for your deployment located at %inetpub%wwwrootwssVirtualDirectories80 and adding to the system.web section the following line <deployment retail="false" />. Again, these files are less than 1MB.

Lastly, Silverlight is a little bit different in that it has its own implementation of the client OM for Silverlight specifically. You can find the Silverlight DLLs at %Program Files%Common FilesMicrosoft SharedWeb Server Extensions 14TEMPLATELAYOUTSClientBin. You will find two files, Microsoft.SharePoint.Client.Silverlight and Microsoft.SharePoint.Client.Silverlight.Runtime. Combined the files also come under 1MB in size.

Microsoft is finalizing the distribution of these files, since on client machines you may need to be able to distribute the files, depending on whether the machine has the required DLLs already installed from other applications, such as Microsoft Office 2010. Until this is finalized, for your development machines, you can either develop on your server or copy the correct files to your development machine.

Depending on the type of application you are writing, the way you reference the different client OMs will vary. With WPF or WinForms, you use the VS Add Reference user interface to add a reference to the DLLs discussed earlier. From there, you can use the proper statements to leverage the namespaces in your code. The same process is true for Silverlight. Figure 4-21 shows adding a reference inside of Visual Studio.

Figure 4.21. Figure 4-21

When it comes to the ECMAScript object model, the way you will reference this is by using the ScriptLink control, which is part of the Microsoft.SharePoint.WebControls namespace, to add a reference to the ECMAScript files. The following code snippet shows you how to do this:

<SharePoint:ScriptLink ID="ScriptLinkSPDebug" Name="sp.debug.js"
LoadAfterUI="true" Localizable="false" runat="server" />

Before you write your first line of code, you need to understand the context your code will run in. With the client OM, by default, your code will run in the context of the Windows authenticated user. Since many web applications support forms-based authentication, the client OM supports this as well. You will have to provide the username and password for the client OM to use and also set the authentication mode to forms-based authentication on your ClientContext object. The following code shows you how to set the client OM to use forms-based authentication and set the correct properties to send a username and password:

clientContext.AuthenticationMode = ClientAuthenticationMode.FormsAuthentication;
 FormsAuthenticationLoginInfo formsAuthInfo = new
FormsAuthenticationLoginInfo("User", "Password");
clientContext.FormsAuthenticationLoginInfo = formsAuthInfo;

At the heart of all your code is the ClientContext object. This is the object that you will instantiate first to tell SharePoint what site you want to connect to in order to perform your operations. With the .NET API, you must pass an absolute URL to the client context in order to open your site, but with the ECMAScript API, you can pass a relative or blank URL in your constructor and SharePoint will either find the relative site or use the current site as the site you want to open.

One quick note on ClientContext is that, if you look at the implementation, you will notice that it inherits from IDisposable. This means that you will want to properly dispose of your ClientContext objects either by wrapping your code with using statements or by calling Dispose explicitly. If you don't dispose correctly, you may run into memory leaks and issues.

Looking at the constructor for the ClientContext, you can pass in either a string that is the URL to your site or a URI object that contains the URL to your site.

Table 4-15 shows the important methods and properties for the ClientContext class.

As you will see in the sample code throughout this section, you will use the Load or LoadQuery method on the ClientContext object and then call the ExecuteQuery or executeQueryAsync method to execute your query. The rest of this section goes through the different programming tasks you will want to perform with the client OM, to show you how to use it.

To retrieve items from SharePoint, the easiest way to get back your list is to just use the Load method to load the object into the client OM. For example, if you wanted to load a Web object into the client OM and then access the properties from it, you would use the following code.

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
       "http://intranet.contoso.com");
            Web site = context.Web;
            context.Load(site);
            context.ExecuteQuery();
            MessageBox.Show("Title: " + site.Title + " Relative URL: " +
 site.ServerRelativeUrl);
context.Dispose();

One thing to note is that if you try to use any of the other objects below the requested site, you will get an error saying that the collection is not initialized. For example, if you try to retrieve the lists in the site, you will get an error. With the client OM, you need to be explicit about what you want to load. The following modified sample shows you how to load the list collection and then iterate over the objects in the collection:

//Load the List Collection
                ListCollection lists = context.Web.Lists;
                context.Load(lists);
                context.ExecuteQuery();

                MessageBox.Show(lists.Count.ToString());


                foreach (Microsoft.SharePoint.Client.List list in lists)
                {
                    MessageBox.Show("List: " + list.Title);
                }

By default, SharePoint will return a large set of properties and hydrate your objects with these properties. For performance reasons, you may not want to have it do that if you are only using a subset of the properties. Plus, certain properties are not returned by default, such as permission properties for your objects. As a best practice, you should request the properties that you need rather than letting SharePoint retrieve all properties for you. This is similar to the best practice of not doing a SELECT * in SQL Server.

The way to request properties is in your load method. As part of this method, you need to request the properties you want to use in your LINQ code. The following example changes the previous site request code to retrieve only the Title and ServerRelativeURL properties, and for our lists only the Title property, since that is all we use in the code.

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
"http://intranet.contoso.com");

                Web site = context.Web;
                context.Load(site, s => s.Title, s => s.ServerRelativeUrl);
                ListCollection lists = site.Lists;
                context.Load(lists, ls => ls.Include(l => l.Title));

                context.ExecuteQuery();



                MessageBox.Show("Title: " + site.Title + " Relative URL: " +
 site.ServerRelativeUrl);


                MessageBox.Show(lists.Count.ToString());

foreach (Microsoft.SharePoint.Client.List list in lists)
                {
                    MessageBox.Show("List: " + list.Title);
                }


                context.Dispose();

You may be wondering what the difference is between Load and LoadQuery. Load hydrates the objects in-context, so if you pass a Web object to your Load method, SharePoint will fill in that object with the properties of your SharePoint web. LoadQuery does not fill in the objects in-context, so it returns an entirely new collection. The LoadQuery method is more complex, but it also is more flexible. In certain cases, it allows the server to be more effective in processing your queries. Plus, you can query the same object collection multiple times and have different result sets for each query. For example, you can have one query that returns all lists with a certain title, while another collection returns lists with a certain number of items. You can destroy these objects also out of context. With the Load method, the objects are tied to the client context, so they are only destroyed and are eligible for garbage collection when the client context is destroyed.

The LoadQuery method is very similar to the Load method, except that it returns a new collection. The other key difference is that the properties for objects off the client context are not populated with LoadQuery after your LoadQuery call. You need to call Load method to populate these. The following code shows you a good example of this:

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
"http://intranet.contoso.com");

                Web site = context.Web;
                ListCollection lists = site.Lists;


                IEnumerable<List> newLists = context.LoadQuery(lists.Include(
                 list => list.Title));
                context.ExecuteQuery();

                foreach (List list in newLists)
                {
                    MessageBox.Show("Title: " + list.Title);
                }

                //This will error out because lists is not populated
                MessageBox.Show(lists.Count.ToString());

                context.Dispose();

In your LoadQuery calls, you can nest Include statements so that you can load fields from multiple objects in the hierarchy without making multiple calls to the server. The following code shows how to do this:

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
 "http://intranet.contoso.com");

                Web site = context.Web;
                ListCollection lists = site.Lists;


                IEnumerable<List> newLists = context.LoadQuery(lists.Include(
        list => list.Title, list => list.Fields.Include(Field => Field.Title)));
                context.ExecuteQuery();

                foreach (List list in newLists)
                {
                    MessageBox.Show(" List Title: " + list.Title);
                    foreach (Field field in list.Fields)
                    {
                        MessageBox.Show("Field Title: " + field.Title);
                    }
                }

                context.Dispose();

In the client OM, you can use CAML to query the server as part of the GetItems method. As you see in the code that follows, you create a new CamlQuery object and pass into the ViewXml property the CAML query that you want to perform. From there, you call the GetItems on your ListCollection object and pass in your CamlQuery object. You still need to call the Load and ExecuteQuery methods to have the client object model perform your query. Also, CAML does support row limits, so you can also pass a <RowLimit> element in your CAML query and page over your results. In the OM, on the ListItemCollection object, there is a property ListItemCollectionPosition. You need to set your CAMLQuery object's ListItemCollectionPosition to your own ListItemCollectionPosition object to keep track of your paging and then you can position your query starting point before querying the list, and iterate through the pages until there are no pages of content left, as shown here:

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
"http://intranet.contoso.com");


            List list = context.Web.Lists.GetByTitle("Announcements");

            ListItemCollectionPosition itemPosition = null;
            while (true)
            {

CamlQuery camlQuery = new CamlQuery();
                camlQuery.ListItemCollectionPosition = itemPosition;
                camlQuery.ViewXml = @"
                    <View>
                        <Query>
                            <Where>
                                <IsNotNull>
                                    <FieldRef Name='Title' />
                                </IsNotNull>
                            </Where>
                        </Query>
                        <RowLimit>1000</RowLimit>
                    </View>";
                ListItemCollection listItems = list.GetItems(camlQuery);
                context.Load(listItems);
                context.ExecuteQuery();

                itemPosition = listItems.ListItemCollectionPosition;

                foreach (ListItem listItem in listItems.ToList())
                {
                    MessageBox.Show("Title: " + listItem["Title"]);
                }


                if (itemPosition == null)
                {
                    break;
                }

                MessageBox.Show("Position: " + itemPosition.PagingInfo);

            }

If you don't want to use CAML to query your lists, you can also use LINQ to query your lists. To do this, you create your query and put it in a variable. Next, using the LoadQuery method you pass your LINQ query. Then, you can call the ExecuteQuery method to execute your query and iterate through the results.

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
"http://intranet.contoso.com");

            var query = from list
                        in context.Web.Lists
                        where list.Title != null
                        select list;

            var result = context.LoadQuery(query);
            context.ExecuteQuery();

            foreach (List list in result)

{
                MessageBox.Show("Title: " + list.Title);
            }

            context.Dispose();

Using the client OM, you can create lists and items. To do this, you need to use the ListCreationInformation object and set the properties for your list, such as the title and the type. Your ListCollection object has an Add method that you can call and pass your ListCreationInformation object to in order to create your list.

To create a field, use the Fields collection for your list and define the XML in the AddFieldAsXml property. This property takes your XML, a Boolean that specifies whether to add the field to the default view, and AddFieldOptions, such as adding the field to the default content type.

Once you have added your field, you can create list items by first creating a ListItemCreationInformation object, and pass that to the AddItem method, which will return a ListItem object representing your new item. Using this object, you can set the properties for your item. Make sure to call the Update method when you are done modifying your properties.

When you are done with all your changes, make sure to call the ExecuteQuery method to have the client OM send your changes back to the server.

ClientContext context = new Microsoft.SharePoint.Client.ClientContext
("http://intranet.contoso.com");
            Web site = context.Web;

            ListCreationInformation listCreationInfo = new
ListCreationInformation();

            listCreationInfo.Title = "New List";
            listCreationInfo.TemplateType = (int)ListTemplateType.GenericList;
            List list = site.Lists.Add(listCreationInfo);

            Field newField = list.Fields.AddFieldAsXml(@"
                 <Field Type='Text'
                        DisplayName='NewTextField'>
                 </Field>", true, AddFieldOptions.AddToDefaultContentType);

            ListItemCreationInformation itemCreationinfo = new
ListItemCreationInformation();
            ListItem item = list.AddItem(itemCreationinfo);
            item["Title"] = "My New Item";
            item["NewTextField"] = "My Text";
            item.Update();



            context.ExecuteQuery();

            context.Dispose();

To delete lists and items, you can use the DeleteObject method. One caveat is that when you are deleting items from a collection, you will want to materialize your collection into a List<T> object, using the ToList method, so you can iterate through the list and delete without errors.

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
"http://intranet.contoso.com");


            List list = context.Web.Lists.GetByTitle("New List");

            CamlQuery camlQuery = new CamlQuery();

            camlQuery.ViewXml = @"
                <View>
                    <Query>
                        <Where>
                            <IsNotNull>
                                <FieldRef Name='Title' />
                            </IsNotNull>
                        </Where>
                    </Query>
                </View>";
            ListItemCollection listItems = list.GetItems(camlQuery);

            context.Load(listItems, items => items.Include(item => item["Title"]));
            context.ExecuteQuery();
            foreach (ListItem listItem in listItems.ToList())
            {
                listItem.DeleteObject();
            }

            context.ExecuteQuery();
            context.Dispose();

Another feature of the client OM, beyond working with lists, libraries, and items, is the ability to work with users and groups. The client OM includes the GroupCollection, Group, UserCollection, and User objects to make working with users and groups easier. Just as you iterate on lists and items, you can iterate on users and groups using these collections. The client OM also has access to built-in groups such as the owners, members, and visitors groups. You can access these off your context object using the AssociatedOwnerGroup, AssociatedMemberGroup, and AssociatedVisitorGroup properties, which return a Group object. Remember to hydrate these objects before trying to access properties or User collections on the objects.

To add a user to a group, you use the UserCreationInformation object and set the properties on that object, such as Title, LoginName, and other properties. Then, you call the Add method on your UserCollection object to add the user, and ExecuteQuery to submit the changes. Since this is very similar to the steps to create items, the sample code that follows shows you how to query users and groups but not create users.

ClientContext context = new Microsoft.SharePoint.Client.ClientContext(
"http://intranet.contoso.com");

            GroupCollection groupCollection = context.Web.SiteGroups;

            context.Load(groupCollection,
                groups => groups.Include(
                    group => group.Users));

            context.ExecuteQuery();

            foreach (Group group in groupCollection)
            {

                UserCollection userCollection = group.Users;

                foreach (User user in userCollection)
                {
                    MessageBox.Show("User Name: " + user.Title + " Email: " +
 user.Email + " Login: " + user.LoginName);

                }
            }
            //Iterate the owners group
            Group ownerGroup = context.Web.AssociatedOwnerGroup;

            context.Load(ownerGroup);
            context.Load(ownerGroup.Users);
            context.ExecuteQuery();
            foreach (User ownerUser in ownerGroup.Users)
            {
                MessageBox.Show("User Name: " + ownerUser.Title + " Email: " +
 ownerUser.Email + " Login: " + ownerUser.LoginName);
            }

            context.Dispose();

All of the code so far that we have looked at is synchronous code running in a .NET client, such as a WPF, console, or Windows Forms application. You may not want to write synchronous code, even in your .NET clients, so your application can be more responsive to your users, rather than having them wait for operations to complete before continuing to use your application. ECMAScript and Silverlight are asynchronous by default, so you will see how to program them separately, but for .NET clients, you need to do a little bit of work to make your code asynchronous. The main change is that you need to use the BeginInvoke method to execute your code and pass a delegate to that method, which .NET will call back on when your code is done executing asynchronously. Then, you can do other work while you are polling to see if the asynchronous call is complete. Once it's complete, you call the EndInvoke method to get back the result.

public delegate string AsyncDelegate();

        public string TestMethod()
        {
            string titleReturn = "";
            using (ClientContext context = new
 Microsoft.SharePoint.Client.ClientContext("http://intranet.contoso.com"))
            {

                List list = context.Web.Lists.GetByTitle("Announcements");
                context.Load(list);
                context.ExecuteQuery();
                titleReturn = list.Title;
            }
            return titleReturn;
        }

        private void button1_Click(object sender, EventArgs e)
        {

            // Create the delegate.
            AsyncDelegate dlgt = new AsyncDelegate(TestMethod);

            // Initiate the asychronous call.
            IAsyncResult ar = dlgt.BeginInvoke(null, null);

            // Poll while simulating work.
            while (ar.IsCompleted == false)
            {
                //Do work
            }

            // Call EndInvoke to retrieve the results.
            string listTitle = dlgt.EndInvoke(ar);

            //Print out the title of the list
            MessageBox.Show(listTitle);

Using ECMAScript with the client object model is very similar to the .NET object model. The main differences are that you use server-relative URLs for your ClientContext constructor and the ECMAScript object model does not accept LINQ syntax for retrieving items from SharePoint. Instead, you will use string expressions to define your basic queries. Also, ECMAScript is always asynchronous, so you have to use delegates and create callback functions for the success and failure of your call into the client OM. The final piece, as you see in the code that follows, is that you need to reference the WebControls namespace from the Microsoft.SharePoint assembly, reference the ECMAScript client OM in SP.js or SP.debug.js, using a SharePoint:ScriptLink control, and finally put a SharePoint:FormDigest on your page for security reasons, if you want to be able to write or update to the SharePoint database.

<%@ Page Language="C#" %>
<%@ Register Tagprefix="SharePoint"
    Namespace="Microsoft.SharePoint.WebControls"
    Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>ECMAScript Client OM</title>
      <script type="text/javascript">


          function CallClientOM() {
              var context = new SP.ClientContext.get_current();
              this.website = context.get_web();
              this.listCollection = website.get_lists();

              context.load(this.listCollection, 'Include(Title, Id)'),
              context.executeQueryAsync(Function.createDelegate(this,
 this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
          }


          function onQuerySucceeded(sender, args) {

          var listInfo = '';

          var listEnumerator = listCollection.getEnumerator();

          while (listEnumerator.moveNext())
          {
              var list = listEnumerator.get_current();
              listInfo += 'List Title: ' + list.get_title() + ' ID: ' +
 list.get_id() + '
';
          }
    alert(listInfo);

          }

          function onQueryFailed(sender, args) {
              alert('request failed ' + args.get_message() + '
' +
 args.get_stackTrace());
          }

      </script>
  </head>
  <body>
    <form id="form1" runat="server">
      <SharePoint:ScriptLink ID="ScriptLink1" Name="sp.debug.js" LoadAfterUI="true"

Localizable="false" runat="server" />

<a href="#" onclick="CallClientOM()">Click here to Execute</a>

      <SharePoint:FormDigest runat="server" />
    </form>
  </body>
</html>

Working with Silverlight is also similar to working with the .NET client, except for two major differences. First is that you will want to perform all your operations asynchronously, so this requires you to create delegates and program success and failure methods. Second, since your code runs on a background thread, you will need to get on the user interface thread before you attempt to write to the UI. The easiest way to do this is to wrap your code with the BeginInvoke method of the Dispatcher object. This method guarantees that your code will run on the Silverlight UI thread. If you do not do this, you will receive a threading error. One other thing to remember is to use the right client OM DLLs. Silverlight has special DLLs in the %Program Files%Common FilesMicrosoft SharedWeb Server Extensions14TEMPLATELAYOUTSClientBin directory for the core OM and the runtime.

The last bit you need to know about Silverlight is how to get your applications deployed. They need to run in a trusted area of SharePoint, which could be in a SharePoint library or in the ClientBin directory. For the ClientBin, the easiest way to get your code there is to make the output of your project go to this directory. For deploying to SharePoint document libraries, you could manually upload your XAP file to SharePoint and point the Silverlight Web Part at your manually uploaded XAP. Another way is to use a Sandbox Solution, which you will learn about later, to create a feature that copies the file up to your SharePoint site using a Module with a File reference in your Elements manifest.

One thing to watch out for is caching of your Silverlight application while you are developing it. Make sure that an old version is not loaded by updating the AssemblyVersion and FileVersion in your AssemblyInfo file in VS. You may also have to clear your browser cache. Another recommendation is to change something in the UI to make sure that your application is the latest; this allows you to tell visually.

Also, if you are working across domains, you will need to understand how to create cross-domain policies using a ClientAccessPolicy.XML file that you host at the root of your website. If you are working in the same domain, you do not have to write this policy file, but if you go across domains (for example, if your Silverlight application runs in your domain but calls a service in another domain) you will have to use the ClientAccessPolicy.XML file to allow those calls. Figure 4-22 shows the Silverlight application in action.

Figure 4.22. Figure 4-22

using SP = Microsoft.SharePoint.Client;

namespace SPSilverlight
{
    public partial class MainPage : UserControl
    {

        IEnumerable<SP.List> listItems = null;
        public MainPage()
        {
            InitializeComponent();
        }

        private void getItemsSucceeded(object sender,
 Microsoft.SharePoint.Client.ClientRequestSucceededEventArgs e)
        {
            Dispatcher.BeginInvoke(() =>
            {
                //Code to display items
                //Databind the List of Lists to the listbox

                listBox1.ItemsSource = listItems;
                listBox1.DisplayMemberPath = "Title";
            });

}


        private void getItemsRequestFailed(object sender,
 Microsoft.SharePoint.Client.ClientRequestFailedEventArgs e)
        {
            Dispatcher.BeginInvoke(() =>
            {
                MessageBox.Show("Error:  " + e.ErrorCode + " " + e.ErrorDetails + "
 " + e.Message + " " + e.StackTrace.ToString());
            });
        }

        private void button1_Click(object sender, RoutedEventArgs e)
        {

            ClientContext context = null;

            if (App.Current.IsRunningOutOfBrowser)
            {
                context = new ClientContext(
                    "http://intranet.contoso.com");
            }
            else
            {
                context = ClientContext.Current;
            }

            var query = from listCollection
        in context.Web.Lists
                        where listCollection.Title != null
                        select listCollection;

            listItems = context.LoadQuery(query);


                ClientRequestSucceededEventHandler success = new
ClientRequestSucceededEventHandler(getItemsSucceeded);
                ClientRequestFailedEventHandler failure = new
ClientRequestFailedEventHandler(getItemsRequestFailed);
                context.ExecuteQueryAsync(success, failure);

            }

        }
    }

With SharePoint 2010, you can program against SharePoint and Excel Services using Representational State Transfer (REST). This section covers the core SharePoint REST Services.

SharePoint REST services are implemented using the ADO.NET Data Services, formerly known as Astoria. If you don't know what REST is, the easiest way to think about REST is that it provides URL-accessible functionality, so you can query, create, and delete lists and items using just the standard HTTP protocol.

Here are a couple of best practices before getting started with REST in SharePoint 2010. First, you will want to make sure you install the ADO.NET data services on the SharePoint 2010 Server where you are developing using REST. REST is implemented in your _vti_bin directory by accessing http://yourserver/_vti_bin/ListData.svc, so if you connect to that URL and get a 404 error, you do not have the ADO.NET Data Services technologies installed. Second, if you are connecting to your REST services for SharePoint from Internet Explorer (IE), you will want to turn off Feed Reading View in IE so that you get the raw XML returned from SharePoint. You can find this under Tools

The easiest way to get started with REST in SharePoint is to look at what is returned when you connect to http://yourserver/yoursite/_vti_bin/ListData.svc, as shown in Figure 4-23. You will see the XML returned for all your lists in your site.

Figure 4.23. Figure 4-23

If you have never worked with REST before, there are two ways in SharePoint that you can return your data. First, there is ATOM, which returns XML and is a standard. Then, there is JavaScript Object Notation (JSON), which returns your data using JSON markup so that you can parse that data using JavaScript objects. JSON is good if you want to turn the returned data into Javascript objects. You can specify the type of data you want returned by using the Content-Type header in your request. The tools that work with REST, such as Visual Studio, use ATOM, not JSON, so you need to request JSON specifically if you want your results in that format.

Since REST uses a standard URL-addressable format and uses standard HTTP methods, such as GET, POST, PUT, and DELETE, you get a predictable way to retrieve or write items in your SharePoint deployment. Table 4-16 lists some examples of URL addresses.

Using REST in Visual Studio

Since Visual Studio has built-in support for using ADO.NET Data Services, programming with REST starts with adding a service reference in your code. In this reference, point to your ListData.svc URL in _vti_bin. Please note that in the beta, you will have to change the reference VS adds from System.Data.Service.Client to Microsoft.Data.Services.Client by removing the reference and adding a new reference to %Program Files (x86)ADO.NET Data Services V1.5 CTP2in. Then, you will have to create new proxy classes by running in a command prompt DataSvcUtil.exe /uri:"http://URL/_vti_bin/ListData.svc" /out:Reference.cs. This will create a C# file that you will use to replace the existing Reference.cs in your project, which you will find in the file directory for your project, not in the user interface, unless you turn on Show All Files in Solution Explorer.

From there, you should see your lists in the Data Source window inside of Visual Studio, as shown in Figure 4-24. If you do not see your datasource in the window, right-click your service reference and select Update Service Reference. You will have to go back and change the System.Data.Services.Client reference again to Microsoft.Data.Services.Client.

Figure 4.24. Figure 4-24

From there, you can add a new Object datasource to your project, so you can work with a subset of the lists, such as binding the datasource to a datagrid in your code. You can do this by creating a new Object datasource and selecting the lists you are interested in, as shown in Figure 4-25.

Figure 4.25. Figure 4-25

You can drag and drop your datasource onto your form, and Visual Studio will create and bind a grid to your datasource. You can also use LINQ to program against your REST datasource. Figure 4-26 shows a databound grid against a SharePoint REST datasource.

Figure 4.26. Figure 4-26

Since the code for programming using REST is very similar to programming using the rest of the client OM, there is a quick example below of adding an item to your SharePoint list using REST. You will notice a call to generate a context for the rest of your calls to leverage so that you can batch commands and send them to server when you need to. For adding, you call the specific AddTo method for your list, such as AddToAnnouncements. For updating and deleting, you use the UpdateObject and DeleteObject methods and pass in the object you want to delete, which is derived from your item type, such as AnnouncementItem.

RESTReference.HomeDataContext context = new RESTReference.HomeDataContext(
new Uri("http://intranet.contoso.com/_vti_bin/listdata.svc"));

        private void button1_Click(object sender, EventArgs e)
        {
            //Populate grid using LINQ
            context.Credentials = CredentialCache.DefaultCredentials;

            var q = from a in context.Announcements
                    select a;

            this.announcementsItemBindingSource.DataSource = q;
        }

        private void button2_Click(object sender, EventArgs e)
        {
            //Add a new Announcement
            RESTReference.AnnouncementsItem newAnnounce = new
 RESTReference.AnnouncementsItem();

newAnnounce.Title = "My New Announcement! " + DateTime.Now.ToString();

            context.AddToAnnouncements(newAnnounce);
            context.SaveChanges();
        }

<script src="http://ajax.microsoft.com/ajax/jquery/jquery-1.3.2.js"
type="text/javascript"></script>

Sandbox does implement a subset of the Microsoft.SharePoint namespace. Sandbox Solutions do allow you to use full trust proxies to access other APIs or capabilities, for example, accessing network resources, but OOB the following capabilities from the Microsoft.SharePoint namespace are supported:

One common question you may be asking yourself is "If I can't access local resources such the hard drive on the server or network resources except for SharePoint, how do I get at external data like a database or Twitter or some other external datasource?" Well, you can use external lists and BCS in SharePoint to access external data, since Sandbox Solutions can access external lists. Of course, you need to have permissions to set up BCS and external lists, but if there are already BCS solutions set up with access to the external datasources that you need, you can quickly use the external lists in your Sandbox Solutions to read and write to that external data.

Sandbox Solutions do support iframes, so you can add a literal control to your nonvisual web part and make the text the iframe that you want to display in the control. This allows you to connect to many solutions on the Internet, such as Silverlight or web pages that expose information that you want to display in your environment. Using Sandbox Solutions for this, rather than content editor web parts, makes the control reusable and easier to distribute.

You can find a lot of information about Sandbox Solutions under the UserCode folder in your SharePoint root. If you look at the web.config file located there, you will see that Sandbox Solutions are restricted by an OOB CAS policy. By default, you cannot access anything outside of the SharePoint object model. You should not modify these permission levels and instead should use full trust proxies to allow your sandbox code to perform allowed operations that it does not have by default. The exact permission levels are:

Beyond the default CAS policy, SharePoint also implements an API block list. Imagine the scenario where you find some code exploiting your sandbox using a particular API from SharePoint. You may want to block API across your environment. This is where the API block list comes in. A new object was added to SPWebService called RestrictedObjectModel. This object contains a collection of restricted types that implements an add method, so you can add new API methods to block. For the add method, you need to pass in the type and method you want to block. For example, if you wanted to block the Update method of the SPWeb object you would call SPWebService.RestrictedObjectModel.RestrictedTypes.Add(typeof(SPWeb), "Update"). By default, nothing is blocked.

One of the nice features of VS 2010 is that it supports Sandbox Solutions. When you create a new SharePoint project, for projects that support Sandbox Solutions, VS will give you the option of deploying your solution as a Sandbox Solution, as shown in Figure 4-27. In addition, VS will limit the API set in IntelliSense to just the APIs that work for Sandbox Solutions. VS does not do a compile-time check if you are using restricted APIs, since you program against the full SharePoint namespace and at runtime, your code is limited. So, if you ignore IntelliSense and write to APIs that are not supported in the sandbox, you will not get a compile-time error but instead will get a runtime error. One trick around this is to reference the Microsoft.SharePoint.dll under the Assemblies folder under the UserCode folder in the SharePoint hive. That will limit the APIs you can use. You MUST change back the reference to the full Microsoft.SharePoint.dll before deployment. This may be fixed in the released version of Visual Studio 2010.

Figure 4.27. Figure 4-27

In terms of monitoring, SharePoint tracks 14 different counters and tries to normalize across them. For example, how many points should be a millisecond of CPU execution time as compared to the number of SharePoint database queries you make? How do you normalize across different counters to make an aggregate that makes sense? Well, it's easy to see how SharePoint attempts to do it. You can look at using PowerShell by using the SPUserCodeService object. The following PowerShell code returns all the counters measured by Sandbox Solutions:

$snapin = Get-PSSnapin | where-object { $_.Name -eq
 'Microsoft.SharePoint.PowerShell' }
if ($snapin -eq $null){
 write-host "Loading SharePoint PowerShell Snapin..." -foregroundcolor Blue
 add-pssnapin "Microsoft.SharePoint.PowerShell"
 write-host "SharePoint PowerShell Snapin loaded." -foregroundcolor Green
}

[Microsoft.SharePoint.Administration.SPUserCodeService]::Local.ResourceMeasures

# The ReadKey functionality is only supported at the console (not is the ISE)

if (!$psISE)

{

   Write-Host -NoNewLine "Press any key to continue. . . "

   $null = $Host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")

   Write-Host ""

}

write-host "Completed Run" -foregroundcolor Blue

If you bubble up this list, you get the counters and metrics in the bulleted list below. The way to read the list is as the type of counter and then how many counts must occur or the time to count as a single resource point. For example, if you make 20 SharePoint database calls through your calls to different SharePoint APIs, that counts as one resource point.

The counters are customizable in that you could bump them up or down using the object model any of the counters. For example, if you wanted to allow 40 database calls, you could change that by using the SharePoint object model. However, it's a little like changing search relevancy algorithms yourself; it may cause unintended consequences, so try the default restrictions to see if they meet your needs before you modify them.

Also, there are absolute limits. Absolute limits will terminate a solution even if the resource limits have not been hit. For example, UnresponsiveprocessCount has an absolute limit of 1. This means that, if your Sandbox Solution is not responding, it will be terminated immediately. Then, two points will be added to the aggregate. The solution could try to run again, but it will be terminated if it becomes unresponsive and again two resource points will be added to the aggregate.

If there are solutions that just keep breaking, administrators can block them from running either by using the object model or, more easily, by selecting the solution by browsing for it and putting in a message that tells the user why the solution can't run.

To work with solution validation, you just need to inherit from the SPSolutionValidator class. Once you write your code for this class, you add it to the SPUserCodeService SolutionValidators collection using either the API or PowerShell. Following is sample code for the solution validator:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Runtime.InteropServices;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
using Microsoft.SharePoint.UserCode;
using System.IO;


namespace SolutionValidation
{
    [Guid("7158c574-9881-42b3-9116-2575485af534")]
    public class SolutionValidator : SPSolutionValidator
    {

        //Create constant to pass to constructor
        private const string solutionValidatorName = "Solution Validator";
        //Create constant for Validator Signature
        private const int sigValue = 1;


        public SolutionValidator()
        {
            //Blank Constructor
        }


         public SolutionValidator(SPUserCodeService userCodeService)
            :base(solutionValidatorName, userCodeService)
       {
           this.Signature = sigValue;

       }

         public override void ValidateSolution(
SPSolutionValidationProperties properties)
         {
             //Validate your solution such as checking the code files in
the solution
             foreach (SPSolutionFile solutionFile in properties.Files.Where(
                f => String.Equals(
                        Path.GetExtension(f.Location), ".dll",
                            StringComparison.InvariantCultureIgnoreCase)))
             {
                 //Perform Validation of files
             }

             base.ValidateSolution(properties);

             properties.Valid = false;

properties.ValidationErrorMessage = "Illegal Solution";
             properties.ValidationErrorUrl =
"/_layouts/SolutionValidation/SolutionValidationError.aspx";

         }

         public override void ValidateAssembly(
SPSolutionValidationProperties properties, SPSolutionFile assembly)
         {
             //You can open the assembly using OpenBinary
             base.ValidateAssembly(properties, assembly);
             properties.Valid = true;
         }
    }
}

A couple of things in the code: First, you can see where the code inherits from the SPSolutionValidator class. In addition, you need to create your own GUID to assign to your class, since you will use that GUID when you remove the solution validator from SharePoint in your feature deployment.

From there, you can see the blank constructor and another constructor that overloads the base constructor to assign a signature value to your validator. If you update the validator, you will want to update the signature number.

For the implementation, the code has ValidateSolution and ValidateAssembly methods. The ValidateSolution method gets passed a SPSolutionValidationProperties collection, which contains a number of properties for your SharePoint solutions, such as the files in the solution. You can perform validation in this method and, if the solution is valid, set the Boolean Valid property to True. If the solution is not valid, set the Valid property to False. You can also specify the ValidationErrorMessage and ValidationErrorUrl, which is the message to display and, if you want, the URL of the error message page. You can use the mapped folder feature in Visual Studio to add a custom ASP.NET page to your Layouts folder to display your error message.

For the ValidateAssembly method, you can validate individual assemblies in the solution. You get the assembly, and you can open it using the OpenBinary method, write all the bytes, and look at the bits contained in it. If the assembly is valid, set the Valid property to True.

Once you have your implemented class, you need to create a feature that deploys your solution validator. It must be a farm-level solution, since you want to validate all solutions in your farm. As part of the feature, you will want to write code for your feature event receiver to turn on your solution validator and turn it off when the feature is activated. The following code does this. Note how the same GUID is used in the FeatureDeactivating event that you used to mark up your class. Figure 4-29 shows the solution validator in action, denying a solution the right to activate.

public override void FeatureActivated(SPFeatureReceiverProperties properties)
        {
            //Add solution Validator using our class name
             SPUserCodeService.Local.SolutionValidators.Add(

new SolutionValidator(SPUserCodeService.Local));

        }



        public override void FeatureDeactivating(
SPFeatureReceiverProperties properties)
        {
            //Remove our solution validator using our GUID
            SPUserCodeService.Local.SolutionValidators.Remove(new Guid(
"7158c574-9881-42b3-9116-2575485af534"));

        }

Figure 4.29. Figure 4-29

The last area we will look at is creating full-trust proxies. Full-trust proxies allow you to extend Sandbox Solutions without throwing everything out of the sandbox. For example, you may need to access a network resource to get at data but not want to make the full solution a fully trusted solution; instead you want to provide a limited proxy to just that network resource. With full-trust proxies, you can provide an API just to the network resource and allow your Sandbox Solutions to call through that API to your resource.

To create a full-trust proxy, you need to implement a class that inherits from the SPProxyOperation class. Then, you need to figure out the arguments that you want passed to your proxy by creating a serializable class that inherits from the SPProxyOperationsArgs class. Once you have done this, generate the DLL and put this DLL into the global assembly cache (GAC). Then, you can register the DLL with SharePoint and call it using the SPUtility.ExecuteRegisteredProxyOperation method.

The following code creates a class that mimics accessing a network resource. It passes a fake username and password, and the full-trust proxy returns an array of data. You could imagine that you make a call to ADO.NET or other data access technologies to perform a real database call. Notice in the code that you need to create a serializable class that implements the proxy arguments. The calling Sandbox Solution then displays the data from the datasource that is accessed by using the full-trust proxy.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.SharePoint.UserCode;

namespace FullTrustProxyDLL
{
    public class AccessDatabase : SPProxyOperation
    {
        public override object Execute(SPProxyOperationArgs args)
        {
            if (args != null)
            {


                ProxyArgs proxyArgs = args as ProxyArgs;

                //Get the user name
                string userName = proxyArgs.userName;

                //Get the password
                string password = proxyArgs.password;

                //Access the datasource here
                string[] results = { "A", "B", "C" };


                return results;
            }
            else return null;

        }

    }

    [Serializable]
    public class ProxyArgs : SPProxyOperationArgs

{
        public string userName { get; set; }

        public string password { get; set; }

    }
}

In order to make your proxy callable from partially trusted code applications, you need to add a line to your AssemblyInfo.cs, as shown here:

//Allow partially trusted callers
[assembly: System.Security.AllowPartiallyTrustedCallers]

Once you have compiled your proxy DLL, you need to register it in the GAC. Once that is done, you can register it with SharePoint. The following PowerShell script performs this step:

$snapin = Get-PSSnapin | where-object { $_.Name -eq
 'Microsoft.SharePoint.PowerShell' }
if ($snapin -eq $null){
 write-host "Loading SharePoint PowerShell Snapin..." -foregroundcolor Blue
 add-pssnapin "Microsoft.SharePoint.PowerShell"
 write-host "SharePoint PowerShell Snapin loaded." -foregroundcolor Green
}


$userCodeService = [Microsoft.SharePoint.Administration.SPUserCodeService]::Local
$assemblyName = "FullTrustProxyDLL, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=3098f04d94800e33"
$typeName = "FullTrustProxyDLL.AccessDatabase"
$proxyOperationType = new-object -typename
 Microsoft.SharePoint.UserCode.SPProxyOperationType -argumentlist
$assemblyName, $typeName
userCodeService.ProxyOperationTypes.Add($proxyOperationType)
$userCodeService.Update()

Now you can use the proxy in your Sandbox Solution. The following code and Figure 4-30 below shows the full trust proxy being used and how to call the proxy class from your sandbox code:

ProxyArgs proxyA = new ProxyArgs();
            proxyA.userName = "TestUser";
            proxyA.password = "Password";

            string assemblyName = "FullTrustProxyDLL, Version=1.0.0.0,
Culture=neutral, PublicKeyToken=3098f04d94800e33";
            string typeName = "FullTrustProxyDLL.AccessDatabase";

            accessDatabaseButton.Click += (object sender, EventArgs e) =>
            {
                string[] results;
                results = (string
[])SPUtility.ExecuteRegisteredProxyOperation(assemblyName, typeName, proxyA);

lbl.Text = "First result: " + results[0];
            };

            Controls.Add(accessDatabaseButton);
            Controls.Add(lbl);

Figure 4.30. Figure 4-30