Contents
About the Author ..................................................................................................................... xv
About the Technical Reviewer ................................................................................................... xvii
Acknowledgments .................................................................................................................... xix
Introduction ............................................................................................................................. xxi
■■Chapter 1: Introduction to SharePoint Apps ...................................................................1
Introduction to the Cloud App Model ............................................................................................1
Developing Solutions in Previous Versions of SharePoint ............................................................... 2
Developing Apps for SharePoint 2013 .......................................................................................... 3
Designing Cloud App Solutions .....................................................................................................4
Client-Side Code Pattern ............................................................................................................. 5
Server-Side Code Pattern ............................................................................................................ 6
Deployment Options ....................................................................................................................6
Distributing SharePoint Apps ....................................................................................................... 8
Development Environment .......................................................................................................... 9
SharePoint App Components .......................................................................................................10
App Organization and Terminology .............................................................................................. 10
Installation Scopes ......................................................................................................................13
Client API Libraries ......................................................................................................................15
Connecting Tiers of the App ........................................................................................................ 16
User Interface Components ......................................................................................................... 17
Security .......................................................................................................................................19
Authentication .............................................................................................................................19
Introduction to OAuth 2.0 ............................................................................................................ 20
Authorization in SharePoint Apps .................................................................................................. 21
Benefits of the Cloud App Model ....................................................................................................27
Classroom Online Sample App .......................................................................................................28
Summary .....................................................................................................................................29
■■Chapter 2: Creating and Debugging Apps ........................................................................31
Setting Up Your Development Environment ...................................................................................31
Choosing a Set of APIs .................................................................................................................31
Choosing a Development Tool ..................................................................................................... 32
Choosing a Target SharePoint Environment .................................................................................. 33
Deploying the Developer Site Template ........................................................................................ 34
Creating Apps with Napa ..............................................................................................................35
Creating Apps in Visual Studio 2012 ..............................................................................................40
Summary .....................................................................................................................................47
■■Chapter 3: Managing the App Life Cycle ..........................................................................49
Life Cycle Overview ......................................................................................................................49
App Packaging .............................................................................................................................50
Distribution ..................................................................................................................................52
Publishing to a Private App Catalog ............................................................................................... 53
Publishing to the Office Store ........................................................................................................ 57
Installation ....................................................................................................................................59
Distributing Updates .......................................................................................................................63
Uninstallation .................................................................................................................................67
Summary .......................................................................................................................................68
■■Chapter 4: Client-Side Logic with JavaScript ...................................................................69
Welcome to the Client Side ...........................................................................................................69
Using Advanced JavaScript Concepts .............................................................................................70
Creating JavaScript Objects .......................................................................................................... 71
Prototypes ...................................................................................................................................76
JavaScript Object Notation (JSON) ................................................................................................ 78
Introducing jQuery .......................................................................................................................79
Basic Concepts .............................................................................................................................80
Understanding Selectors .............................................................................................................. 83
Querying DOM Elements .............................................................................................................. 86
Traversing the Document ............................................................................................................. 88
Updating DOM Objects ..................................................................................................................90
Looping in jQuery .........................................................................................................................91
Event Handling ............................................................................................................................ 91
Using the Knockout Library with the MVVM Pattern .........................................................................96
The Model-View-ViewModel (MVVM) ............................................................................................. 96
Introducing Knockout ...................................................................................................................97
Connecting Data with Declarative Bindings .................................................................................... 97
Dependency Tracking with Observable Objects ............................................................................ 100
Generating Complex Views with Templates .................................................................................. 104
Summary ....................................................................................................................................112
■■Chapter 5: Accessing the SharePoint Environment ........................................................113
The SharePoint 2013 APIs ...........................................................................................................113
The Server-Side Object Model ..................................................................................................... 113
The Client-Side Object Model ...................................................................................................... 114
Web Service Endpoints ................................................................................................................115
Request Batching in Client-Side Code ...........................................................................................116
Introduction to CSOM Objects .....................................................................................................117
Context and Infrastructure ......................................................................................................... 117
Content Objects .........................................................................................................................118
Security .....................................................................................................................................119
Managing the App ......................................................................................................................119
Social ........................................................................................................................................120
.NET Framework CSOM ...............................................................................................................120
JavaScript Object Model (JSOM) ..................................................................................................120
Summary ...................................................................................................................................143
■ Chapter 6: SharePoint App Security .................................................................................145
Declaring App Permissions and Scopes ..........................................................................................145
Content Scopes ...........................................................................................................................148
Service Scopes ............................................................................................................................148
Scope Rules ................................................................................................................................149
Controlling Authentication and Identities .......................................................................................155
Principals ....................................................................................................................................155
Retrieving User Information ........................................................................................................ 156
SharePoint Groups, Roles, and Permissions .................................................................................. 161
Using Remote Web Resources......................................................................................................175
Cloud-Hosted Remote Webs ....................................................................................................... 177
High-Trust Apps ..........................................................................................................................178
Understanding the TokenHelper Utility ..........................................................................................179
Summary ...................................................................................................................................184
■ Chapter 7: Web Services with REST and OData ..............................................................185
The SharePoint 2013 REST API ...................................................................................................185
Anatomy of a REST Request .......................................................................................................187
Constructing SharePoint REST URLs ........................................................................................... 187
Choosing an HTTP Method ........................................................................................................ 189
Configuring Request Headers .................................................................................................... 189
SharePoint 2013 REST Endpoints ...............................................................................................190
Choosing a Client-Side Library ....................................................................................................191
SharePoint REST Access with JQuery ......................................................................................... 192
The SharePoint Cross-Domain Library ........................................................................................ 197
The TokenHelper and HTTPWebRequest Objects ........................................................................ 202
Choosing the Appropriate Library ............................................................................................... 206
Managing Data in SharePoint ......................................................................................................207
Passing the Request Digest ........................................................................................................ 207
Ensuring Consistent Updates with ETags ..................................................................................... 208
The Classroom Online Gradebook ............................................................................................... 208
Creating Objects in SharePoint ................................................................................................... 217
Updating Objects ........................................................................................................................219
Deleting Objects .........................................................................................................................222
Summary ...................................................................................................................................223
■■Chapter 8: Business Connectivity Services ....................................................................225
Business Connectivity Services Overview .....................................................................................225
BCS Architecture .......................................................................................................................226
External Content Types ..............................................................................................................227
The Open Data Protocol (OData) Connector ............................................................................... 229
BCS Events and Notifications ..................................................................................................... 229
Creating an OData Endpoint .......................................................................................................229
Creating App-Scoped External Content Types ..............................................................................237
Summary ..................................................................................................................................244
■■Chapter 9: App Logic Components ................................................................................245
Middle-Tier Concepts .................................................................................................................245
Remote Event Receivers ............................................................................................................246
Remote Event Types .................................................................................................................247
Programming Interfaces ............................................................................................................250
Debugging Event Receivers ....................................................................................................... 252
Workflows in Apps for SharePoint ...............................................................................................258
SharePoint 2013 Workflows ....................................................................................................... 259
Architecture ...............................................................................................................................261
Subscriptions and Associations ................................................................................................... 263
Alternatives to Writing Code ....................................................................................................... 264
SharePoint App Workflow Activities ............................................................................................. 265
The Workflow Services Manager ................................................................................................. 267
Summary ...................................................................................................................................282
■■Chapter 10: Developing the User Experience ................................................................283
User Experience Options for Apps ................................................................................................283
Client Web Parts ........................................................................................................................284
Creating App Parts .....................................................................................................................285
Setting Parameters .....................................................................................................................286
Custom Actions ..........................................................................................................................293
Types of Custom Actions .............................................................................................................294
Custom Edit Control Block Actions .............................................................................................. 295
Custom Ribbon Actions ...............................................................................................................298
Conforming to a Brand ...............................................................................................................300
The App Master Page .................................................................................................................301
Host Site Styles .........................................................................................................................303
The Chrome Control ..................................................................................................................303
Adapting to the Browser ............................................................................................................306
The Redirect Page .....................................................................................................................306
Language Support .....................................................................................................................307
Summary ...................................................................................................................................311
■■Chapter 11: Accessing SharePoint Search ......................................................................313
Understanding SharePoint 2013 Search ........................................................................................313
Controlling Rank and Relevance ...................................................................................................315
Federating Search Results ...........................................................................................................316
Refining a Search ........................................................................................................................317
Managing Query Suggestions .......................................................................................................318
Using Search APIs .......................................................................................................................319
The REST Search API ..................................................................................................................319
The JavaScript CSOM Search API ................................................................................................ 324
The Managed .NET Search API ................................................................................................... 326
Summary ...................................................................................................................................330
■■Chapter 12: Using SharePoint’s Social Features ............................................................331
Social Computing Basics .............................................................................................................331
Building Communities in SharePoint ............................................................................................333
Using Community Sites ...............................................................................................................333
Using the Community Portal ...................................................................................................... 336
Sharing Content .........................................................................................................................336
Understanding My Sites ..............................................................................................................337
The SharePoint 2013 Social API ...................................................................................................339
Managing Feeds .........................................................................................................................341
Working with Follows ..................................................................................................................346
Creating Posts, Mentions, Tags, and Links ................................................................................... 348
Summary ...................................................................................................................................349
■■Chapter 13: Enhancing Apps with SharePoint Services .................................................351
Accessing Managed Metadata .....................................................................................................351
Logging SharePoint App Errors ....................................................................................................355
Managing App Licenses ...............................................................................................................358
License Types .............................................................................................................................359
Acquiring Apps from the Office Store ........................................................................................... 359
App Licensing Scope ....................................................................................................................360
Validating License Information .................................................................................................... 361
Summary ...................................................................................................................................369
■■Chapter 14: Using Other App Environments ...................................................................371
Authenticating with SharePoint ....................................................................................................371
Creating Office Apps ...................................................................................................................374
Anatomy of an App for Office ..................................................................................................... 374
Types of Office Apps ...................................................................................................................377
Office App Runtime Environment ................................................................................................. 379
Publishing Office Apps ..................................................................................................................379
Creating Windows and WinRT Apps ...............................................................................................383
Creating Windows Phone Apps ......................................................................................................386
Setting Up the Development Environment ..................................................................................... 386
Windows Phone Empty SharePoint Application Template ................................................................ 387
Windows Phone SharePoint List Application Template .................................................................... 387
Summary .....................................................................................................................................397
Index ...........................................................................................................................................399
Table of Contents
About the Author .......................................................................................................................... xv
About the Technical Reviewer ...................................................................................................... xvii
Acknowledgments ........................................................................................................................ xix
Introduction ................................................................................................................................. xxi
■■Chapter 1: Introduction to SharePoint Apps ..................................................................................1
■■Chapter 2: Creating and Debugging Apps ....................................................................................31
■■Chapter 3: Managing the App Life Cycle ......................................................................................49
■■Chapter 4: Client-Side Logic with JavaScript ................................................................................69
■■Chapter 5: Accessing the SharePoint Environment .....................................................................113
■■Chapter 6: SharePoint App Security ..........................................................................................145
■■Chapter 7: Web Services with REST and OData .........................................................................185
■■Chapter 8: Business Connectivity Services .................................................................................225
■■Chapter 9: App Logic Components ............................................................................................245
■■Chapter 10: Developing the User Experience .............................................................................283
■■Chapter 11: Accessing SharePoint Search .................................................................................313
■■Chapter 12: Using SharePoint’s Social Features .........................................................................331
■■Chapter 13: Enhancing Apps with SharePoint Services ...............................................................351
■■Chapter 14: Using Other App Environments ..............................................................................371
Index .........................................................................................................................................399
Introduction
SharePoint 2013 Server and SharePoint Online provide an entirely new model for developing enterprise solutions called the Cloud App Model. This style of application is architected to run in a hosted environment without unduly impacting the host servers. This provides for levels of scalability and reliability that were difficult, or impossible, to achieve using SharePoint’s previous models that included full-trust and sandboxed solutions.
Pro SharePoint 2013 App Development contains the techniques for delivering advanced solutions on the SharePoint 2013 platform. Using step-by-step tutorials, the reader creates and elaborates on a sample SharePoint app throughout the course of the book. Once complete, the developer will be ready to tackle even the most demanding SharePoint apps with confidence. In this book, we will cover the following points:
We will introduce the Cloud App Model are
• chitecture for creating and hosting SharePoint apps.
• We will walk through the creation and deployment of a complete solution.
• We will examine the security features of the SharePoint app model.
• We will learn to leverage SharePoint data in our apps over the network, securely.
• We will learn to utilize search and other SharePoint services to create rich SharePoint solutions.
• We will explore how to use these techniques to deliver data on a multitude of web and mobile platforms.
This book is intended for developers and IT professionals responsible for delivering solutions on the SharePoint 2013 platform. These solutions may run on-site, in the cloud, or in a hybrid deployment across many locations. We will provide the background and step-by-step introduction needed to create massively scalable SharePoint applications using standard tools such as Visual Studio, and web standards such as HTML and JQuery. Once created, SharePoint apps can be deployed internally or sold through the Microsoft SharePoint Store across the Internet. The objective is to empower organizations to create a new generation of web-based applications on the SharePoint platform. SharePoint enables both on-site and cloud-based deployments of mission-critical business applications, using all of the same tools and technologies, regardless of the environment. Using modern web standards for user interfaces, data access, and most important, security, SharePoint apps can safely break down the wall between internal data and external customers.
The book is designed to introduce each technique in the order necessary for each solution to build on the ones that have come before. In some cases, it may be necessary to use a technique before we have discussed it fully. In these cases, we will try to convey the necessary information and refer the reader to the later section.
This chapter will introduce the new SharePoint app model. We will describe why the app model exists, how it differs
from the previous development models for SharePoint, and where SharePoint apps fit into the Microsoft ecosystem,
including Azure, Windows 8, and Windows Phone. This is the 30,000-foot view.
This chapter will introduce the tools used to create SharePoint apps. We will create a basic app that will begin the book-wide sample project. This sample will be elaborated on in later chapters to demonstrate the techniques presented in each chapter.
This chapter will introduce the concept of an application life cycle. This includes all of the steps used to create and maintain an app. We will look at each stage in the order they will be encountered by the typical app.
Chapter 4: Client-Side Logic with JavaScript
This chapter will provide the reader with an introduction to client-side programming using JavaScript and modern programming patterns. We will introduce JavaScript, JQuery, and Knockout for those readers that are not familiar with them. We will also introduce the Model-View-ViewModel (MVVM) design pattern that will be used throughout the book.
This chapter will cover the means of accessing data that is stored in SharePoint using the SharePoint 2013 client-side object model (CSOM) libraries. This will include lists, libraries, and other SharePoint-specific content.
This chapter will cover the extensive security mechanisms that are inherent in deploying a mission-critical application to SharePoint. This will include SharePoint apps’ means of performing both authentication and authorization. We will also cover the security infrastructure used in Microsoft Azure.
This chapter will cover accessing data from network sources via generic data transfer methods. Unlike accessing SharePoint with the CSOM, this style of data access uses the methods and data elements exposed through standard interfaces such as REST and OData.
Chapter 8: Business Connectivity Services
In this chapter, we will examine the use of BCS within an app. These techniques allow an organization to leverage internal data assets in the cloud, while retaining security and control of that data. We will discuss the best ways to query and update BCS-based data.
Much of the development effort for an app involves accessing data and rendering a user experience. This chapter will focus on the techniques for adding sophisticated logic within a SharePoint app. These techniques will allow us to respond to SharePoint events and manage workflows.
This chapter will deal with the details of creating a modern user experience in a SharePoint app. We will cover the different types of UIs that a SharePoint App can expose and the best tools to use for creating them. We will also learn to make our apps conform to the style of the site in which they reside.
The user interface in SharePoint 2013 sites can be driven more by search results than by content stored locally within the SharePoint site. Microsoft calls this a “search-driven” site. In this chapter, we will discuss the techniques needed to access and display search results with a SharePoint App.
This chapter will describe the social features of the SharePoint 2013 platform as they relate to creating apps. We will cover the MySite and SkyDrive Pro features, as well as newsfeeds, posts, and activities.
The SharePoint 2013 platform contains many integrated services that apps can leverage. These services provide basic infrastructure such as logging and error reporting. They also provide specialized data for metadata, search, and navigation. In this chapter, we will look at how to use some of these services to make our apps more robust and functional.
This chapter will explore the Cloud App Model as it applies to platforms other than SharePoint and how apps can be used to integrate information across the enterprise. SharePoint apps are only one type of “app” in the Microsoft ecosystem. This chapter will delve into creating apps that cross between SharePoint, Windows 8 and RT, Microsoft Office, and Windows Phone.
Summary
In creating the Cloud App Model, Microsoft has attempted to create an architecture that places cloud development at the center. The focus was on creating rich Internet apps that are scalable, maintainable, and robust in a variety of hosting environments. As a result, SharePoint apps can seem overly complex at times. As you will see in the coming chapters, there are reasons for these design decisions. You are encouraged to absorb all of the concepts that you need to design the next great app. Try not to get buried in the details the first time around.
This chapter will introduce the new SharePoint 2013 application model. We will describe why the app model exists, how it differs from the previous development models for SharePoint, and where SharePoint apps fit into the Microsoft ecosystem, including Azure, Windows 8, and Windows Phone. In this chapter, we will go over the following points:
• Why there is a new application model for SharePoint 2013.
• How full-trust and sandbox solutions fit into the new paradigm.
• How SharePoint apps relate to Microsoft’s online offerings, including Office 365, Azure, and SQL Azure.
• When and why to use SharePoint solutions in on-premise, cloud, and hybrid deployments.
• The sample application that will be developed throughout this book.
Introduction to the Cloud App Model
In SharePoint 2013, Microsoft has introduced a new way to build solutions for SharePoint. This new method is called the Cloud App Model. This model is similar to the development model introduced for Windows 8, the Windows Runtime (WinRT), Office 2013, and Windows Phone 8.
A SharePoint app is a single package of functionality that can be deployed and activated on a site with very little overhead or footprint on the SharePoint server farm. An app package contains all of the SharePoint artifacts (lists, libraries, etc.) needed by the application along with any pages, scripts, styles, or other web files needed to complete the application. Apps are designed to be easy to provision on a site and to be removed cleanly when no longer needed.
The Cloud App Model for SharePoint was designed with (surprise!) the cloud in mind. When an app is deployed to a site, the configuration of the files and settings in SharePoint are handled automatically. The server farm is protected from defective installation packages and file updates because apps cannot be installed like traditional SharePoint solution packages. App package files are managed entirely by SharePoint itself.
When running in the cloud, it is imperative that no one application can produce an unmanageable load on the farm or corrupt memory and require restarting of processes in the farm. SharePoint apps are prevented from causing problems on the farm by eliminating use of the SharePoint Server-Side Object Model (SSOM) in app code. In fact, all server-side code execution is off limits to SharePoint apps. To a developer familiar with developing applications for previous versions of SharePoint, this would seem to make apps totally useless in a SharePoint context. As we will see later, the combination of client-side technologies, like HTML and JavaScript, and sophisticated web service call mechanisms, like REST and OData, make building scalable, reliable apps for SharePoint quite possible.
The rest of this chapter will introduce the concepts associated with the Cloud App Model as it applies to SharePoint. We will discuss the components that make up a SharePoint app and how they are managed. The remaining chapters of this book will discuss each of these in detail to enable you to create rich user applications in SharePoint 2013.
Developing Solutions in Previous Versions of SharePoint
Let’s take a moment to revisit SharePoint 2010. Specifically, we will take a look at how custom applications were developed and deployed prior to SharePoint 2013.
When designing a custom application for SharePoint pre-2013, we first had to decide what type of application it would be: full-trust or sandboxed. We then had to consider things like what features that would go into the application. The developer would create the files that make up the application and create feature manifests to manage their installation. Finally, we would create a solution package file (.WSP) that could be deployed to SharePoint. Project templates for Visual Studio made this process easier in later versions, but there were still times when the developer had to work with raw XML or CAML files in order to accomplish even routine tasks.
For full-trust solutions, a farm administrator would need to deploy the solution package to each SharePoint server in the farm. This would have the effect of copying files into various folders throughout the server farm. Most of these files ended up in the “14 hive.” The hive is a folder on the server’s hard drive that contains many of SharePoint’s own files, which might be overwritten or altered by some package installations. Finally, the farm administrator would need to activate the features of the solution in order to begin using them within the farm.
Creating full-trust applications in SharePoint can have several unwanted side effects on the server farm’s stability and performance.
All code in a full-trust application runs whithin SharePoint’s own server processes. Any corruption caused by the application has the potential to crash the server or farm.
• Any slow or inefficient code in an application can consume CPU cycles, memory, or disk space on the farm’s servers and hurt performance.
• If the application does not take appropriate security precautions, it can compromise information stored in the farm because a full-trust application can always elevate its privileges to perform virtually any action.
When deploying a solution file containing a full-trust application to a farm, extensive testing is required to ensure that the application will not cause damage to the farm. As a result, many organizations have adopted policies that drastically limit or completely rule out the use of full-trust applications.
In a hosted or cloud environment, the server farm may support multiple end-user organizations or tenants. In these scenarios, including using SharePoint Online, full-trust applications are simply not an option. No outside code can be allowed to run in full-trust without risking harm to other customers in the farm.
In SharePoint 2013, full-trust applications are still supported and are appropriate for certain types of applications.
Any custom functionality that deals with managing the farm or accessing specialized hardware may require elevated privileges and should still be created as a full-trust application. These solution packages will continue to be supported as they have been, but they are only for use in locally hosted, on-premise farm deployments. They are not appropriate for any functionality being deployed to a hosted or cloud environment.
The other option, prior to the release of SharePoint 2013, was to create a sandboxed solution. These solutions are developed using the same techniques and file formats as full-trust solutions, but with certain limitations.
• Sandboxed applications do not run with full-trust and cannot elevate their privileges to acquire it.
• Sandboxed applications run in a separate isolated process to prevent them from corrupting the server farm’s own processes.
• Applications that run in the sandbox are only allowed to access a subset of the SharePoint Server-Side Object Model (SSOM) through a proxy object that forwards the requests to the main SharePoint processes.
• Sandboxed applications are deployed and managed at the site collection level and can only access resources within the local site collection. They cannot access other resources within the farm or elsewhere on the network, even when using the Client-Side Object Model (CSOM).
The sandbox was introduced in SharePoint 2010 in an attempt to isolate custom applications from SharePoint and limit their potential for harming the overall farm. While this was accomplished, the restrictions placed on sandboxed applications have limited their usefulness. The sandbox model has also been found insufficient for hosting and cloud deployments.
The code in a sandboxed application still runs on the servers in the SharePoint farm. Poorly written or managed applications can still cause performance problems or limit scalability.
• Sandboxed applications that corrupt their own memory or use too many resources may be automatically restarted periodically, further draining server resources.
• The limitations on what data can be accessed from a sandboxed application limits their usefulness in enterprise-style applications that require broader access to SharePoint and network resources.
• Limiting access to the Server-Side Object Model, and the limited implementation of the Client-Side Object Model in SharePoint 2010, made creating rich applications in the sandbox very difficult or impossible.
• Because sandboxed solutions are deployed at the site collection level, they are managed by site collection administrators. These users have to install, activate, configure, and remove these packages within each site collection they own. In many organizations, site collection administration is delegated to non-technical power users who typically find managing solution packages very confusing.
The sandbox was created to solve the application management problems created by full-trust applications, but it has created new problems and imposes severe limitations on the types of applications that can be developed. As a result, sandboxed solutions have been deprecated in SharePoint 2013. In this case, deprecated is Microsoft’s way of saying “Oops, that didn’t work!” In practical terms, deprecated means that while the sandbox still exists in SharePoint 2013 for backward compatibility, it may not be a part of future releases. No new development should be done in sandboxed solution packages.
With full-trust applications limited to living behind the organization’s firewall and sandboxed solutions on the way out, how do we make the leap into the cloud? The answer, of course, is to create SharePoint apps using the Cloud App Model.
Using apps for SharePoint is very similar to using apps on mobile devices such as Android- or iOS-based phones. When a cell phone’s user wants to extend the functionality of their device, they go an app store of some sort. This could be the Google Play Store for Android or the Apple Store for iOS. They find the app they want to install and select it. The app is paid for, in some cases, and then automatically downloaded and installed on their device. Once the user is finished using the app, they can uninstall it from their device as if it had never been there. The key to this usability is the fact that no one but the end user ever needs to be involved.
In the case of SharePoint apps, an app is installed into a SharePoint site. As with mobile apps, a SharePoint app can be acquired from the SharePoint Store (office.microsoft.com/en-us/store/apps-for-sharepoint- FX102804987.aspx) managed by Microsoft, as shown in Figure 1-1. An app adds functionality to the site while it is installed. The app may add SharePoint artifacts, such as lists and web parts, to the site. It can also add menu options, pages, and other behaviors to the site.
